<!-- -->

Introduction

NOTES: spectra plotting is temporarily turned off for the branches due to an error in SigProfilerPlotting waiting to be fixed

lcmb is a bioinformatics pipeline that processes sequencing data from LCMB pipeline to obtain clean somatic mutations

There are two main options, each with five possible subworkflows. These workflows can be turn on and off for different use cases, as follows:

• Option 1: Workflow for samples with matching normal samples (--with_match_normal true, default)

1. CONPAIRFILTERWITHMATCHNORMAL, run when --run_conpair true (default): Use conpair to filter out contaminated samples.

• pileup: use gatk to calculate pileups for the bam files
• calculate the concordance between samples and their nominated match normal, as well as match normal samples for samples from other donors.
• calculate the contamination score for each sample
• If a sample matches more than ONE match normal (defaul concordance threshold for matching: >= 90%), it is contaminated and filtered out of the input sample sheet.
• If a sample passes a contamination threshold (default >= 0.3%), it is filtered out. If a match normal passes a contamination threshold (default >= 5%), all of its matched samples are filtered out.

1. LCMBFILTERSNV_MATCH, run when --run_filter_snv true (default). Filtering SNVs, taking vcf files. This workflow can be broken down into the following steps

• Add hairpin label with hairpin
• Initial filtering. Default initial filtering criteria can be found here.
• For each donor with multiple samples, use cgpVAF to calculate and pool VAF across their samples.
• Use beta-binomial test based on VAF to filter out LCM artefact mutations.
• Generate a mutation matrix using SigProfilerMatrixGenerator
• Plot the mutation matrix using SigProfilerPlotting

1. LCMBFILTERINDEL_MATCH, run when --run_filter_indel true (default). Filtering INDELs, taking indel vcf files. This workflow can be broken down into the following steps

• Initial filtering. Default initial filtering criteria can be found in here.
• For each donor with multiple samples, use cgpVAF to calculate and pool VAF across their samples.
• Use beta-binomial test based on VAF to filter out LCM artefact mutations.
• Generate a mutation matrix using SigProfilerMatrixGenerator
• Plot the mutation matrix using SigProfilerPlotting

1. PHYLOGENETICS for SNVs, run when run_phylogenetics true (default) and --run_filter_snv true, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false and --with_topology false, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false and --snv_then_indel true. Note that if run_phylogenetics true and --run_filter_snv false --run_filter_indel false, --run_conpair cannot be true, and with_topology must be true or snv_then_indel cannot be null but with_topology and snv_then_indel must not both be true. (details in docs/usage.md)

• For each donor pdid, use NR (total depths), NV (reads supporting variant) and the binary genotype file (outputs from LCMBFILTERSNVMATCH, otherwise should specified in the sample sheet) to create a fasta file of aligned sequences, where each sequence represents a sample of a donor.
• From the fasta file representing each donor, create a phylogenetic tree using MPBoot.
• Assign mutations to each branch of the tree using treemut
• For each donor, generate a mutation matrix for the branches using SigProfilerMatrixGenerator
• Plot the mutation matrices using SigProfilerPlotting

1. PHYLOGENETICSPROVIDEDTREE_TOPOLOGY for Indels, run when --phylogenetics == true (default) and --run_filter_indel true, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false and --with_topology true, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false and --snv_then_indel true. Note that if run_phylogenetics true and --run_filter_snv false --run_filter_indel false, --run_conpair cannot be true, and with_topology must be true or snv_then_indel cannot be null but with_topology and snv_then_indel must not both be true. (details in docs/usage.md)

• For each donor pdid, use NR (total depths), NV (reads supporting variant), the binary genotype file (outputs from FILTERWITHMATCHNORMALINDEL) and a tree topology (output from PHYLOGENETICS). If FILTERWITHMATCHNORMAL_INDEL and PHYLOGENETICS are not run, these files should specified in the sample sheet.
• Assign mutations to each branch of the tree (output from PHYLOGENETICS for SNVs or provided in sample sheet)
• For each donor, generate a mutation matrix for the branches using SigProfilerMatrixGenerator

• Plot the mutation matrices using SigProfilerPlotting

• Option 2: Workflow for samples without matching normal samples (-with_match_normal false)

1. CONPAIRFILTERWITHOUTMATCHNORMAL, run when --run_conpair true (default): Use conpair to filter out contaminated samples.

• pileup: use gatk to calculate pileups for the bam files
• calculate the concordance between all samples pairwise.
• Filter out samples if they match samples from more than one donor, or if they match the wrong donor (defaul concordance threshold for matching: >= 90%)
• calculate the contamination score for each sample (match normal is what ever samples they match with that's not themselves)
• If a sample passes a contamination threshold (default >= 0.3%), it is filtered out.

All filtered out samples will be recorded in a log file.

1. LCMBFILTERSNV_UNMATCH, run when --run_filter_snv true (default). Filtering SNVs, taking vcf files. This workflow can be broken down into the following steps

• Add hairpin label with hairpin
• Initial filtering. Default initial filtering criteria can be found here.
• For each donor with multiple samples, use cgpVAF to calculate and pool VAF across their samples.
• Use exact binomial test to filter out germline mutations
• Use beta-binomial test based on VAF to filter out LCM artefact mutations.
• Generate a mutation matrix using SigProfilerMatrixGenerator
• Plot the mutation matrix using SigProfilerPlotting

1. LCMBFILTERINDEL_UNMATCH, run when --run_filter_indel true (default). Filtering INDELs, taking indel vcf files. This workflow can be broken down into the following steps

• Initial filtering. Default initial filtering criteria can be found in here.
• For each donor with multiple samples, use cgpVAF to calculate and pool VAF across their samples.
• Use exact binomial test to filter out germline mutations
• Use beta-binomial test based on VAF to filter out LCM artefact mutations.
• Generate a mutation matrix using SigProfilerMatrixGenerator
• Plot the mutation matrix using SigProfilerPlotting

1. PHYLOGENETICS for SNVs, run when run_phylogenetics true (default) and --run_filter_snv true, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false and --with_topology false, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false and --snv_then_indel true. Note that if run_phylogenetics true and --run_filter_snv false --run_filter_indel false, --run_conpair cannot be true, and with_topology must be true or snv_then_indel cannot be null but with_topology and snv_then_indel must not both be true. (details in docs/usage.md)

• For each donor pdid, use NR (total depths), NV (reads supporting variant) and the binary genotype file (outputs from LCMBFILTERSNVMATCH, otherwise should specified in the sample sheet) to create a fasta file of aligned sequences, where each sequence represents a sample of a donor.
• From the fasta file representing each donor, create a phylogenetic tree using MPBoot.
• Assign mutations to each branch of the tree using treemut
• For each donor, generate a mutation matrix for the branches using SigProfilerMatrixGenerator
• Plot the mutation matrices using SigProfilerPlotting

1. PHYLOGENETICSPROVIDEDTREE_TOPOLOGY for Indels, run when --phylogenetics == true (default) and --run_filter_indel true, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false and --with_topology true, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false and --snv_then_indel true. Note that if run_phylogenetics true and --run_filter_snv false --run_filter_indel false, --run_conpair cannot be true, and with_topology must be true or snv_then_indel cannot be null but with_topology and snv_then_indel must not both be true. (details in docs/usage.md)

• For each donor pdid, use NR (total depths), NV (reads supporting variant), the binary genotype file (outputs from FILTERWITHMATCHNORMALINDEL) and a tree topology (output from PHYLOGENETICS). If FILTERWITHMATCHNORMAL_INDEL and PHYLOGENETICS are not run, these files should specified in the sample sheet.
• Assign mutations to each branch of the tree (output from PHYLOGENETICS for SNVs or provided in sample sheet)
• For each donor, generate a mutation matrix for the branches using SigProfilerMatrixGenerator
• Plot the mutation matrices using SigProfilerPlotting

Dependencies

• Nextflow >= 24.04.2 required

[!NOTE] If you are new to Nextflow and nf-core, please refer to this page on how to set-up Nextflow.

The following does not need to be installed if using a container runtime like Docker or Singularity

• python, required packages: pandas (1.5.3 recommended), numpy (1.26.1 recommended), scipy, matplotlib (3.8.2 recommended), pillow (10.1.0 recommended), SigProfilerMatrixGenerator, SigProfilerPlotting
• gatk
• hairpin
• vafCorrect
• R, required packages: ape, ggplot2, ggtree, treemut
• MPBoot

Installation

Clone this repository, including the MutationsPy submodule

git clone git@github.com:Phuong-Le/lcmb.git

Usage

[NOT PUBLIC YET] Make sure to test your setup with -profile test before running the workflow on actual data.

The input sample sheet should be in a tab delimited format (extension must be .tsv), like samplesheetfullpipeline.tsv. The column requirements depends on which subworkflows you would like to run (column names must be accurate but no need to be in this order, redundant columns will be ignored):

| Column | Description | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | REQUIRED COLUMNS FOR ALL SUBWORKFLOWS | | pdid | Donor ID for your sample | | | REQUIRED COLUMNS FOR CONPAIR, FILTERSNV and/or FILTERINDEL (--run_conpair true and/or --run_filter_snv true and/or --run_filter_indel true) | | sample_id | sample ID, must be unique | | match_normal_id | ID for your match normal sample | | | bam | bam file for sample_id, must exist | | | bai | tabix index file for bam, must exist | | bam_match | bam file for match_normal_id, must exist | | bai_match | tabix index file for bam_match, must exist | | REQUIRED COLUMNS FOR FILTERSNV and/or FILTERINDEL PIPELINE (--run_filter_snv true and/or --run_filter_indel true) | | bas | bam status file for bam, must exist | | met | met (samtools markedup) file for bam, must exist | | REQUIRED COLUMNS FOR FILTERSNV (`--runfiltersnv true) | |snvvcf| VCF file for the SNVs ofsampleid, must exist | |snvvcftbi| tabix index file for VCF file forsnvvcftbi`, must exist | | REQUIRED COLUMNS FOR FILTERINDEL (--run_filter_indel true) | | indel_vcf | VCF file for the indels of sample_id, must exist | | indel_vcf_tbi | tabix index file for VCF file for indel_vcf_tbi, must exist | | REQUIRED COLUMNS FOR PHYLOGENETICS FOR BOTH SNVs AND INDELs WITHOUT FILTERING SNVs OR INDELs (--run_phylogenetics true --run_filter_snv false --run_filter_indel false --snv_then_indel true) | | nr_path_snv | NR file (depths at variants) for SNVs for pdid, must exist | | nv_path_snv | NV file (reads supporting variants) for SNVs for pdid, must exist | | genotype_bin_path_snv | binary genotype file for SNVs for pdid, must exist | | nr_path_indel | NR file (depths at variants) for INDELs for pdid, must exist | | nv_path_indel | NV file (reads supporting variants) for INDELs for pdid, must exist | | genotype_bin_path_indel | binary genotype file for INDELs for pdid, must exist | | REQUIRED COLUMNS FOR PHYLOGENETICS or PHYLOGENETICS-GIVEN-TREE-TOPOLOGY WITHOUT RUNNNING FILTERING SNVs OR INDELs (--run_phylogenetics true --run_filter_snv false --run_filter_indel false --snv_then_indel [false/null]) | | nr_path | NR file (depths at variants) for pdid, must exist | | nv_path | NV file (reads supporting variants) for pdid, must exist | | genotype_bin_path | binary genotype file for pdid, must exist | | REQUIRED COLUMNS FOR PHYLOGENETICS-GIVEN-TREE-TOPOLOGY WITHOUT RUNNNING FILTERING SNVs (--run_phylogenetics true --run_filter_snv false --run_filter_indel true, or --run_phylogenetics true --run_filter_snv false --run_filter_indel false --with_topology true) | | topology | tree topology file for pdid, must exist |

Please find the detailed instructions to run the pipeline, including the input parameters in docs/usage.md. You can run the pipeline using:

```bash

nextflow run /path/to/lcmb/main.nf \ -profile \ --input /path/to/samplesheet.tsv \ --withmatchnormal true \ --runconpair true \ --runfiltersnv true \ --runfilterindel true \ --runphylogenetics true \ --hairpingenome hg38 \ --sigprofilergenome GRCh38 \ --usecustomgenome true \ --genome genomelabelincustomgenomeconfig \ #eg yourgenome_label --outdir /path/to/outdir ```

The following required parameters (depending which subworkflows are run) can be specified either directly via the nextflow run command, or via a custom genome profile like in the above example (this involves setting use_custom_genome to true and specifying the genome label - detailed instructions to create a custom genome profile can be found in docs/usage.md)

--fasta --fai --fasta_dict --marker_bed --marker_txt --hidepth --hidepth_tbi

[!WARNING] Please provide pipeline parameters via the CLI or Nextflow -params-file option. Custom config files including those provided by the -c Nextflow option can be used to provide any configuration except for parameters; see docs.

Sanger users

Sanger users can run the pipeline as follows. Please refer to docs/sanger.md to ensure you have the right set up.

```bash module load cellgen/nextflow/24.10.2 module load ISG/singularity/3.11.4

outdir=/path/to/outdir mkdir -p $outdir script=/path/to/lcmb/main.nf # should be part of this pipeline configfile=/path/to/lcmb/conf/sangerlsf.config # should be part of this pipeline samplesheet=/path/to/samplesheet.tsv # or .csv, format should be consistent with extension

species=Human # please refer to docs/usage.md speciesassembly=GRCh38 # please refer to docs/usage.md customgenomebase=/lustre/scratch124/casm/references/pipelineref/Homosapiens # please let me know if you're using a different genome so I can update the config for you genome=GRCh38fullanalysissetplusdecoyhla # same as above hairpingenome=hg38 sigprofiler_genome=GRCh38

withmatchnormal=false runconpair=false runfiltersnv=true runfilterindel=true runphylogenetics=false

bsub -cwd ${workingdir} -q week -o %J.out -e %J.err -R "select[mem>5000] rusage[mem=5000]" -M5000 -env "all" \ "nextflow run $script -c ${configfile} --input ${samplesheet} --outdir $outdir --runconpair ${runconpair} --runfiltersnv ${runfiltersnv} --runfilterindel ${runfilterindel} --runphylogenetics ${runphylogenetics} --usecustomgenome true --customgenomebase $customgenomebase --genome ${genome} --hairpingenome ${hairpingenome} --sigprofilergenome ${sigprofilergenome} --withmatchnormal ${withmatchnormal} -profile singularity -resume" ```

Pipeline output

For more details about the output files and reports, please refer to the output documentation.

Credits

Sangersomatic was originally written by Phuong Le, Rashesh Sanghvi, Alex Tidd, Alex Byrne and Raul Alacantra Aragon.

We thank the following people for their extensive assistance in the development of this pipeline:

Chloe Pacyna Yichen Wang Shriram Bhosle Daniel Leongamornlert

Contributions and Support

Please feel free to contribute by either creating a pull request or create a new issue on this github repo

Citations

An extensive list of references for the tools used by the pipeline can be found in the CITATIONS.md file.