Skip to content

SNV_calling_tutorial.md

Latest commit

 

History

History
91 lines (47 loc) · 4.09 KB

SNV_calling_tutorial.md

File metadata and controls

91 lines (47 loc) · 4.09 KB
Raw

AMR++ SNV Workflow (bam_snv) Tutorial

This tutorial covers the bam_snv workflow, which performs Single Nucleotide Variant (SNV) calling starting from pre-aligned BAM files.

1. Environment Setup

Before running the workflow, you need to set up your environment. If you are using the AMR++ Docker container, all required tools are already included.

If you are running the pipeline locally via Conda, you will need to create and activate the dedicated SNV environment:

# Create the environment
conda env create -f envs/AMR++_SNV_env.yaml

# Activate the environment
conda activate AMR++_SNV_env

2. Running the Workflow

The SNV workflow is designed to use the BAM alignment files generated by AMR++ during the alignment phase.

Here is an example command to run the pipeline:

nextflow run main_AMR++.nf --pipeline bam_snv \
  --bam_files 'test_results/Alignment/BAM_files/Standard/*.bam' \
  --snv_min_match_size 100 \
  --snv_min_identity_pc 97 \
  --output snv_results

3. Configurable Parameters

You can customize the SNV calling behavior using the following parameters:

  • --snv_reference: The FASTA file used for alignment (Default: "${baseDir}/data/amr/megares_database_v4.00.fasta"). Crucial note: The BAM files must be aligned to this exact FASTA file. It is highly recommended to use the MEGARes REPRESENTATIVE database rather than the complete database to avoid excessive multi-mapping of short reads among near-identical accessions.

  • --snv_min_match_size: The minimum aligned block size in base pairs used by the NGLess filter before variant calling. A value of 45 is the floor for benchmarking, while 100 is the stricter setting (Default: 100).

  • --snv_min_identity_pc: The minimum percent identity (ANI) for alignments. MetaSNV guidance suggests 97 or above (Default: 97).

  • --snv_n_splits: MetaSNV option. Values greater than 1 will write one raw SNP file per split (Default: 1).

  • --snv_db_ann: MetaSNV option for providing an optional gene annotation file (Default: "").

  • --snv_snpfile_prefix: The prefix shared by the raw call files (Default: "called_SNPs").

  • --snv_aln_wf: Indicates which alignment set was used, controlling the output filenames. Options are "Standard" or "Deduped" (Default: "Standard").

  • --snv_filter_by_resistome: Restricts the final SNV matrix to only include genes that were also detected in the resistome matrix (Default: "N"). Note: This requires a prior resistome run; leave it as "N" if you are running bam_snv alone.

4. Under the Hood: The Pipeline Steps

When you launch the bam_snv workflow, the pipeline runs the following sequence of scripts and subworkflows:

  1. NGLess Filtering (ngless_filter_snv)

  • This process runs on each sample individually.

  • It filters the alignments based on the specified minimum aligned-block size and minimum percent identity.

  • It strictly keeps only reads that mapped uniquely, discarding multi-mapped reads. This unique-mapping requirement is essential because metaSNV cannot accurately attribute an allele to a specific gene when a read maps equally well elsewhere.

  1. BAM Indexing (index_snv_bams)
  • Because metaSNV requires an index alongside each BAM file, this step generates a coordinate-sorted index (.bai) using Samtools for each filtered sample.
  1. Variant Calling (run_metasnv)

  • Unlike the previous steps, metaSNV is run once across all samples simultaneously to derive per-position statistics across the whole sample set.

  • It uses a writable copy of the reference FASTA to write its auxiliary index and position files.

  1. Data Parsing (clean_metasnv)

  • This step reformats the raw metaSNV calls into a standard AMR++-style count matrix and annotation file.

  • It uses a custom script (clean_metaSNP_1.0.2.py) to structure variants as distinct resistome features.

  1. Matrix Filtering (filter_snv_matrix) - Optional
  • If --snv_filter_by_resistome "Y" is used, this final process restricts the newly generated SNV matrix to only include genes that are present in the resistome count matrix.