wf-tb-amr documentation
Mycobacterium tuberculosis workflow
Mycobacterium tuberculosis workflow for multiplexed Nanopore sequencing data.
Introduction
wf-tb-amr is a workflow for determining the antibiotic resistance of
Mycobacterium tuberculosis targeted sequencing samples. The workflow handles
multiplexed sequencing runs and provides clear and simple reports summarising
the predicted resistance profile of each sample according to genetic variants
discovered.
Compute requirements
Recommended requirements:
- CPUs = 16
- Memory = 32GB
Minimum requirements:
- CPUs = 8
- Memory = 16GB
Approximate run time: 5 minutes per sample
ARM processor support: True
Install and run
These are instructions to install and run the workflow on command line. You can also access the workflow via the EPI2ME application.
The workflow uses nextflow to manage compute and software resources, therefore nextflow will need to be installed before attempting to run the workflow.
The workflow can currently be run using either Docker or
singularity to provide isolation of
the required software. Both methods are automated out-of-the-box provided
either docker or singularity is installed. This is controlled by the -profile parameter as exemplified below.
It is not required to clone or download the git repository in order to run the workflow. More information on running EPI2ME workflows can be found on our website.
The following command can be used to obtain the workflow. This will pull the repository in to the assets folder of nextflow and provide a list of all parameters available for the workflow as well as an example command:
nextflow run epi2me-labs/wf-tb-amr --help
A demo dataset is provided for testing of the workflow. It can be downloaded using:
wget <https://ont-exd-int-s3-euwst1-epi2me-labs.s3.amazonaws.com/wf-tb-amr/wf-tb-amr-demo.tar.gz>tar -xzvf wf-tb-amr-demo.tar.gz
The workflow can be run with the demo data using:
nextflow run epi2me-labs/wf-tb-amr \--fastq wf-tb-amr-demo/fastq \--sample_sheet wf-tb-amr-demo/sample_sheet.csv \-profile standard
For further information about running a workflow on the cmd line see https://labs.epi2me.io/wfquickstart/
Related protocols
This workflow is designed to take input sequences that have been produced from Oxford Nanopore Technologies devices.
Find related protocols in the Nanopore community.
Input example
This workflow accepts either FASTQ or BAM files as input.
The FASTQ or BAM input parameters for this workflow accepts the path to a directory containing one level of sub-directories which in turn contains FASTQ or BAM files. The data is assumed to be multiplexed with the names of the sub-directories as barcodes. A sample sheet must be provided with --sample_sheet.
input_directory├── barcode01│ ├── reads0.fastq│ └── reads1.fastq├── barcode02│ ├── reads0.fastq│ ├── reads1.fastq│ └── reads2.fastq└── barcode03└── reads0.fastq
Input parameters
Input Options
| Nextflow parameter name | Type | Description | Help | Default |
|---|---|---|---|---|
| fastq | string | FASTQ files to use in the analysis. | This accepts the path to a directory containing one level of sub-directories which in turn contain FASTQ files. | |
| bam | string | BAM or unaligned BAM (uBAM) files to use in the analysis. | This accepts the path to a directory containing one level of sub-directories which in turn contain BAM files. | |
| analyse_unclassified | boolean | Analyse unclassified reads from input directory. By default the workflow will not process reads in the unclassified directory. | If selected and if the input is a multiplex directory the workflow will also process the unclassified directory. | False |
Sample Options
| Nextflow parameter name | Type | Description | Help | Default |
|---|---|---|---|---|
| sample_sheet | string | A CSV file used to map barcodes to sample aliases. | The sample sheet is a CSV file with, minimally, columns named barcode and alias. Extra columns are allowed. A type column is required for this workflow and should have one of the following values; test_sample, positive_control, no_template_control. |
Output Options
| Nextflow parameter name | Type | Description | Help | Default |
|---|---|---|---|---|
| out_dir | string | Directory for output of all workflow results. | output |
Reference Options
| Nextflow parameter name | Type | Description | Help | Default |
|---|---|---|---|---|
| reference | string | NCBI accession for reference genome. | By default the workflow uses NC_000962.3. WARNING: If you change this parameter but don’t alter the variant database, Genbank file, and the amplicon BED (all generated for NC_000962.3) to match, then the behaviour of the workflow is unlikely to be as expected. | |
| amplicons_bed | string | The location of the amplicons for the assay. | A BED file describing the location of the amplicons used to generate the data to be processed by this workflow, based on NC_000962.3. | |
| primers_bed | string | The location of the primers for the assay. | A BED file describing the location of the primers used to generate the data to be processed by this workflow, based on NC_000962.3. | |
| who_json | string | WHO v2 variant database in JSON format. | A list of WHO variants in JSON format, that this assay will genotype. | |
| amr_regions_bed | string | The location of the regions for AMR calling in the assay. | A BED file describing the location of the regions used for AMR calling in this workflow, based on NC_000962.3. | |
| snpeff_config | string | SnpEff configuration file. | SnpEff configuration file, used to alter start codon possibilities for MTB. | |
| expert_rules | string | Expert rules in JSON format. | Structured data describing expert rules to be applied to variants. | |
| genbank | string | Genbank file for organism of interest. | Genbank file used for variant annotation, defaults to NC000962.3 annotations. | |
| crispr_regions | string | FASTA file of CRISPR regions from Galru. | FASTA file used to identify sample reads mapping to CRISPR regions. | |
| spoligo_db | string | Spoligotype database from SITVIT2. | The SITVIT2 database is used to call the spoligotype of the sample. |
Advanced Options
| Nextflow parameter name | Type | Description | Help | Default |
|---|---|---|---|---|
| maf | number | Minimum mutant allele frequency to consider. | By default the workflow will filter any variant which is present at less than 15% allele frequency (0.15). Change this parameter to alter this filtering behaviour. Minimum is set at 1%. | 0.15 |
| low_maf | number | Minimum mutant allele frequency to consider for samples with 10-20 amplicons passing. | By default the workflow will filter any variant which is present at less than 40% allele frequency (0.40) if between 10-20 amplicons have sufficient coverage. Change this parameter to alter this filtering behaviour. Minimum is set at 1%. | 0.4 |
| downsample | integer | Number of reads to downsample to in each direction, leave empty for no downsampling. | Downsampling can help with run times without significantly impacting the result of your analysis. By default no downsampling is performed, but here you can specify the number of reads to downsample to in each direction, to a minimum of 100. | |
| min_coverage | integer | The minimum total coverage for a region to be coinsidered in variant calling. | By default the workflow expects a minimum of 20 total reads in a region. This is to ensure that very low coverage regions do not contribute to potentially false positive variant calls. | 20 |
| minimum_read_support | integer | The minimum number of reads to consider for a variant call on each strand. | By default the workflow expects a minimum of 5 reads on each strand supporting a variant. This is to ensure that when using the maf, very low coverage regions do not contribute to potentially false positive variant calls. | 5 |
| strand_bias | integer | Set a threshold for strand bias filtering. | Strand bias is represented as a Phred scaled p-value from a Fisher’s exact test, with a value close to 0 being preferable. | 1000 |
| pos_thresh | integer | Set a threshold for presence in positive filtering. | Presence of variant in positive and sample is represented as a Phred scaled p-value from a Fisher’s exact test, with a larger value preferable. | 50 |
| report_config | string | Report configuration file. | The report can be configured to help with translation. See report_config.eng.json in the data/general directory. Here you can provide a path to your own report configuration file. | |
| control_config | string | Control configuration file. | Provides details required to assess the quality of the run and the samples. | |
| antimicrobial_details | string | Antimicrobial agent details. | Provides details about the antimicrobials in the assay. | |
| spacers | string | FASTA file of spacer regions. | The presence or absence of the 43 spacer regions in this FASTA file is used to classify the sample strain. | |
| kraken_db | string | Custom Kraken2 database of hsp65 alleles. | The workflow assigns reads from the hsp65 locus to a database of pre-defined species, and then collapses these to a single taxonomy. | |
| complex_species_to_exclude | string | Tab delimited file describing how some TaxIDs fall into species complex (e.g MTBC or MAC). | ||
| taxid_map | string | File describing the map between TaxID and scientific name. | Used in species identification module to map TaxID to scientific name. | |
| screen | boolean | Option to screen data for non-specific amplified reads and remove from analysis. | Screening samples for non-specific amplification is switched on by default. | True |
| store_dir | string | Directory to store Kraken database used for screening. | The Kraken database is downloaded to to this location when the workflow is run for the first time, and is used for screening non-specific amplified reads. | store_dir |
| filter_white_list | string | File containing taxids for the Mycobacteriaceae family - one taxid per line. | ||
| find | boolean | Option to output results CSV in FIND format. | Set this to true to produce FIND CSV results. | False |
Outputs
Output files may be aggregated including information for all samples or provided per sample. Per-sample files will be prefixed with respective aliases and represented below as {{ alias }}.
| Title | File path | Description | Per sample or aggregated |
|---|---|---|---|
| analytical run report | ./wf-tb-amr-report.html | The report for all samples on the workflow. | aggregated |
| workflow csv results summary | ./wf-tb-amr-report.csv | The CSV summary of the results of the workflow. | aggregated |
| workflow results | ./results.json | Structured workflow results for internal/onward use. | aggregated |
| workflow checkpoints | ./checkpoints.json | Structured workflow checkpoints for internal/onward use. | aggregated |
| alignment | ./{{ alias }}.bam | Aligned reads for the sample in BAM format. | per-sample |
| alignment index | ./{{ alias }}.bam.bai | An index file for the alignment in BAI format. | per-sample |
| variants | ./{{ alias }}.final.vcf | Called, annotated variants for the sample. | per-sample |
| per-sample report HTML | ./{{ alias }}-report.html | Per sample reports HTML. | per-sample |
| per-sample report PDF | ./{{ alias }}-report.pdf | Per sample reports PDF. | per-sample |
Pipeline overview
1. Concatenates input files and generate per read stats.
The fastcat/bamstats tool is used to concatenate multifile samples to be processed by the workflow. It will also output per read stats including average read lengths and qualities.
2. Align reads to NC_000962.3 reference genome
minimap2 is used to align reads from the samples to the Mycobacterium tuberculosis reference genome FASTA (NC_000962.3). This step also discards unmapped reads and generates statistics from the resulting BAM file.
3. Screen reads
Kraken2 is used to screen reads in the sample to filter those derived from non-specific amplification.
4. Run AMR module
The following steps are carried out during this stage:
- The bcftools mpileup tool is used to determine base composition of pre-defined variants.
- Clair3 is used to perform indel calling, and the results merged with the previous step.
- The whatshap tool is used to phase variants, and the results annotated using SnpEff.
- Variants are then matched to the WHO catalogue, and the WHO expert rules are applied to retrieve those which adhere to these rules, but are not present in the catalogue.
5. Run species identification module
Kraken2 is run using a custom hsp65 database, to identify the Mycobacterium species.
6. Run spoligotyping module
Samples are mapped to CRISPR regions using minimap2, and the results are then processed with blast to detect the presence or absence of 43 spacers. The pattern of spacers is then used to classify strains into the different lineages.
7. Quality control
The workflow generates checkpoint data at various stages which captures which quality control checks have passed or failed.
8. Report results
The workflow outputs an HTML report with overall results for all samples in the run, indivdual sample HTML reports, and a summary CSV file.
Troubleshooting
- If the workflow fails please run it with the demo dataset to ensure the workflow itself is working. This will help us determine if the issue is related to the environment, input parameters or a bug.
- See how to interpret some common nextflow exit codes here.
FAQ’s
If your question is not answered here, please report any issues or suggestions to Technical Support.
Related blog posts
See the EPI2ME website for lots of other resources and blog posts.
Share
Information