Reference
CLI Reference
Full reference for the get_mnv command-line options (version 1.1.6). Run get_mnv --help for the same list in your terminal.
Synopsis
get_mnv [OPTIONS] --fasta <FASTA_FILE> <--vcf <VCF_FILE>|--tsv <TSV_FILE>>You must provide a reference (--fasta) and exactly one variant source (--vcf or --tsv), plus a gene annotation (--gff or --genes). The one exception is --report-from, which builds a report out of existing TSV outputs and needs none of them.
Input
| Option | Description |
|---|---|
-v, --vcf <FILE> | Variant input in plain VCF, BGZF-compressed VCF or BCF (SNVs/MNVs and indels). |
--tsv <FILE> | iVar variants.tsv input. |
-b, --bam <FILE> | Optional aligned reads for read support, as BAM or CRAM. Must be coordinate-sorted and indexed; a CRAM is decoded against --fasta. |
-f, --fasta <FILE> | Reference FASTA (required). |
--sample <NAME> | Sample to annotate in a multi-sample VCF (default: first sample; all for all). Its FORMAT metrics become the original depth and frequency, and its genotype decides which ALT alleles it carries. |
--chrom <NAME> | Restrict processing to one contig (default: all contigs in the input). |
Annotation
| Option | Description |
|---|---|
--gff <FILE> | Gene annotation in GFF/GFF3 format. |
-g, --genes <FILE> | Simple gene table TSV: gene,start,end,strand. Use instead of --gff. |
--gff-features <LIST> | Comma-separated GFF feature types to analyze (default: gene,pseudogene). Use CDS for spliced transcripts. |
--translation-table <N> | NCBI genetic code (default: 11, bacterial). Supported: 1, 2, 3, 4, 5, 6, 11, 12, 25. |
--exclude-intergenic | Drop variants outside annotated genes. |
Read support and quality
These apply only when --bam is provided.
| Option | Default | Description |
|---|---|---|
-q, --quality <N> | 20 | Minimum base Phred quality. |
--min-mapq <N> | 0 | Minimum mapping quality (MAPQ). |
-s, --snp <N> | 0 | Minimum SNP-supporting reads. |
--min-snp-frequency <F> | 0.0 | Minimum BAM-derived SNP allele frequency (0.0–1.0). |
-m, --mnv <N> | 0 | Minimum MNV-supporting reads. |
--min-mnv-frequency <F> | 0.0 | Minimum BAM-derived MNV haplotype frequency (0.0–1.0). |
--min-snp-strand <N> | 0 | Minimum SNP-supporting reads on each strand. |
--min-mnv-strand <N> | 0 | Minimum MNV-supporting reads on each strand. |
--min-strand-bias-p <F> | 0.0 | Minimum Fisher exact p-value accepted for strand-bias metrics. VCF output only: the TSV writer has no strand-bias threshold, so this never removes a TSV row. |
How the SNP and MNV thresholds combine
Frequency and read-count filters use support recalculated from --bam, not the original OFREQ/ODP from the input.
A codon-level (SNP/MNV) row is kept when either side clears its bar: its individual SNVs pass the SNP thresholds, or its haplotype passes the MNV thresholds. That keeps a well-supported haplotype whose individual SNVs are weak, and it also works the other way: with the SNP thresholds left at their default of 0 the SNP side always passes, so raising --mnv alone removes nothing. Raise both, or neither. The run warns when you have asked for an MNV threshold that cannot reach a codon-level row.
Which thresholds govern which row:
| Row | Judged by |
|---|---|
SNP | the SNP thresholds |
MNV, SNP/MNV | either side, as above |
INDEL | the MNV thresholds, measured against the indel's own event support (Event Reads, Event Forward Reads, Event Reverse Reads, Event Depth), not against any SNP column |
A TSV row is kept or dropped whole, and a codon-level row clears the SNP side only when every one of its substitutions does. A VCF record is one allele, filtered on its own. So a --both run under a threshold that one substitution meets and another does not writes that allele to the VCF while no TSV row carries it: the row failed, the allele did not. Neither output is wrong; they are different units.
So an indel is filtered with --mnv, --min-mnv-frequency and --min-mnv-strand; --snp never touches it. That holds outside genes too: an intergenic indel is counted and judged on its own support like any other. Only a row that reached no counter at all is exempt, since a threshold cannot be applied to a measurement nobody took.
Indel tuning
| Option | Default | Description |
|---|---|---|
--frameshift-min-freq <F> | 0.5 | Minimum frequency an upstream indel must reach to mark downstream SNV/MNV codons as frameshifted. The default propagates only from a majority upstream indel; set 0.0 to propagate from every one. With --bam the frequency is the one get_MNV counts from the reads (the same number it reports as EFREQ), not the AF the caller declared; without a BAM it falls back to the declared AF. An indel whose frequency is unknown either way always propagates, since there is nothing to compare. |
--legacy-indel-depth | off | Restrict indel-locus depth (the EFREQ denominator) to reads spanning the whole REF allele. By default it is counted from reads observing the anchor base, which avoids under-counting depth on multi-base deletions; this flag restores the older, narrower denominator. |
--phased-indel-min-reads <N> | 2 | Minimum BAM-supporting reads to emit a phased indel/complex haplotype row. One read is not evidence of a haplotype. |
--count-mates-separately | off | Count the two mates of a paired-end fragment as two observations instead of one molecule. |
--phased-indel-min-freq <F> | 0.0 | Minimum BAM-derived frequency to emit a phased indel/complex haplotype row. |
--normalize-alleles | off | Trim shared REF/ALT prefix/suffix before processing. |
--left-align | off | Left-align indels against the reference before processing, as bcftools norm -f does: an indel in a homopolymer or repeat moves to its leftmost equivalent position, where aligners place the gap, so its read support can be counted. An indel stops at a base another record of the sample changes on the same molecules, where its reads put the gap. Includes the trimming of --normalize-alleles; complex records are trimmed but not moved. Applies to VCF and iVar TSV input. See Left-Alignment. |
--split-multiallelic | on | Split multiallelic VCF records into independent ALT alleles. On by default since 1.1.6; still accepted so existing commands keep working. |
Output
| Option | Description |
|---|---|
--output-dir <DIR> | Where to write the TSV, VCF and BCF. Created if missing. Without it they go to the current directory. |
--output-prefix <PREFIX> | Base name for those files, in place of the input's. With --sample all the sample name is still appended. |
--convert | Write VCF output (.MNV.vcf) instead of TSV. |
--both | Write both TSV and VCF in one run. |
--vcf-gz | Write BGZF-compressed .vcf.gz (VCF output mode). |
--index-vcf-gz | Build a Tabix .tbi index (requires --vcf-gz). |
--bcf | Also write a BCF converted from the generated VCF (requires --convert/--both). |
--strand-bias-info | Add Fisher exact strand-bias p-values to VCF INFO (SBP/MSBP). |
--keep-original-info | Preserve original VCF INFO fields in the output (requires --convert/--both). |
--emit-filtered | Emit records that fail thresholds with FILTER tags instead of skipping them. |
--index-vcf-gz and --bcf call external programs
Everything else get_MNV writes is written by get_MNV. These two are not: --index-vcf-gz runs tabix and --bcf runs bcftools, both taken from PATH. They come with samtools/htslib and bcftools respectively, and neither is a build dependency, so a machine can have get_MNV and not have them.
A missing program is not a failed run. get_MNV warns, skips that one step, and finishes: the TSV and the VCF are written either way, and the run exits 0. Nothing else claims the file that was not written, so the summary JSON reports no BCF and --run-manifest records no checksum for one. Check the warnings, or check for the file, if a later step needs it.
Interactive HTML report
| Option | Description |
|---|---|
--report <HTML_FILE> | Write a self-contained interactive HTML report of the called variants. Needs the TSV output, which is the default. --convert writes the VCF instead of the TSV, and the two flags are mutually exclusive, so use --both rather than --convert when you want a report alongside VCF output. With --sample all the report covers every sample. |
--report-from <TSV>... | Build the report from existing get_MNV TSV files instead of running the pipeline, for cohorts processed one sample per run. Each file becomes one sample, labelled by its file name. Requires --report, --matrix or both for the output. |
--matrix <TSV_FILE> | Write a variant-by-sample matrix as TSV: one row per variant, one column per sample, holding the allele frequency the reads gave, called for a call with no measured frequency, or NA where the sample has no call. Works in a normal run, with --sample all, and with --report-from; needs the TSV output like --report. |
--catalogue <TSV_FILE> | Flag calls that match a catalogue of known variants: a tab-separated table with gene, variant and optional label columns, the variant written as p., c., n., g. or LoF. Matches go to the Catalogue column and CAT INFO key. See Input formats. example/who_catalogue_2023.tsv is the WHO catalogue of M. tuberculosis resistance mutations in this form. |
--keep-unphased-codon-matches | List a catalogue match that one reading of a codon alone makes even when no read carries that reading. By default, with --bam, such a match goes to the Catalogue Withheld column and the CATW INFO key instead, with the reason. See Read-level linkage. |
--phase-conflict-dprime <F> | How far D' must be from zero before the reads refute a reading of a codon: at or below minus this value the codon reading, at or above it the per-SNV one, and in either case only when no read carries the refuted reading. Between 0 and 1. Default: 0.5. |
--phase-conflict-p <F> | Largest Fisher exact p-value accepted as that evidence, so a handful of molecules refutes nothing. Between 0 and 1. Default: 0.05. |
See Output formats for what the report contains.
Validation and metadata
| Option | Description |
|---|---|
--dry-run | Validate inputs and print a per-contig summary without writing outputs. |
--strict | Fail if original depth/frequency metrics (ODP/OFREQ) are missing in the input. |
--summary-json <FILE> | Write a machine-readable run summary. |
--run-manifest <FILE> | Write a reproducibility manifest (inputs, outputs, checksums, runtime metadata). |
--error-json <FILE> | Write structured error details as JSON when the command fails. |
--threads <N> | Number of worker threads (default: Rayon auto). |
-h, --help | Print help. |
-V, --version | Print version. |