mlvamaps

mlvamaps calls microbial MLVA/VNTR loci from Illumina reads, accurate long or amplicon reads, and genome assemblies. It uses a user-supplied primer panel, so no organism or typing scheme is hard-coded.

The main outputs are an MLVA fingerprint, per-locus calls and evidence, and a self-contained HTML report. Optional reference databases add sequence-aware matching and phylogenetic placement.

Install

Conda/Miniforge (recommended)

Miniforge provides conda on Linux and macOS. Until the Bioconda package is published, install from this checkout:

git clone https://github.com/microbemarsh/mlvamaps.git
cd mlvamaps
conda env create -f environment.yml
conda activate mlvamaps
python -m pip install --no-deps .

Verify the installation:

mlvamaps --version
mlvamaps --help

After the Bioconda recipe is accepted, installation will be:

conda create -n mlvamaps -c conda-forge -c bioconda mlvamaps
conda activate mlvamaps

Bioconda status: the mlvamaps recipe is staged in packaging/bioconda/meta.yaml. Submission is currently blocked until the required native Python dependency sassy-rs is available from Bioconda or conda-forge. See the Bioconda release checklist.

Run your first sample

You need:

1. a FASTA/FASTQ input; and
2. a CSV or TSV primer panel with at least locus_id, forward_primer, and reverse_primer columns.

A richer panel can also describe repeat motifs, flanks, expected repeat ranges, and accepted amplicon sizes. See the input format reference.

Genome assembly

mlvamaps call \
  -p examples/mlva_loci.example.tsv \
  -i sample.fasta \
  -o results/sample \
  -t 8

Paired-end Illumina reads

mlvamaps call \
  -p panel.tsv \
  -i sr \
  --fq1 sample_R1.fastq.gz \
  --fq2 sample_R2.fastq.gz \
  --sample-id sample \
  -o results/sample \
  -t 8

For a directory containing exact SAMPLE_1.fastq.gz / SAMPLE_2.fastq.gz pairs:

mlvamaps call -p panel.tsv -i reads/ --short-reads -o results -t 8

Accurate long or amplicon reads

mlvamaps call -p panel.tsv -i sample.fastq.gz -o results/sample -t 8

Find the results

Start with:

Output	Purpose
report.html	Human-readable calls, QC, evidence, and matches.
mlva_fingerprint.tsv	Sample-by-locus repeat-copy-number profile.
calls.tsv	Tidy per-locus calls and statuses.
locus_repeat_counts.tsv	Compact individual-locus repeat counts.

Failed or unresolved loci are reported explicitly rather than silently changed to zero. See the complete output reference for all evidence and diagnostic files.

Build a reference database

Build directly from NCBI assemblies for one taxon:

mlvamaps build-reference \
  --taxid 86661 \
  -p panel.tsv \
  -o references \
  -t 16

Or compare one primer panel across taxa:

taxid,name
86661,bacillus_cereus_group
1280,staphylococcus_aureus

mlvamaps build-reference \
  --taxids-csv taxa.csv \
  -p panel.tsv \
  -o references \
  -t 16

Multi-taxon builds write:

• taxon_reference_summary.tsv: one row per taxon;
• taxon_locus_amplifiability.tsv: one row per taxon and locus, suitable for compatibility heatmaps; and
• one isolated reference database per taxon.

A locus is amplifiable when at least one examined genome produces an amplicon retained by the normal primer-matching and filtering rules. Valid amplicons that are too few for --min-references-per-tree remain amplifiable and are reported as INSUFFICIENT_REFERENCES. Taxa with no usable loci are recorded, skip tree building, and do not stop later taxa.

Use a built database during calling:

mlvamaps call \
  -p panel.tsv \
  -i sample.fasta \
  --database references/taxid_86661/reference \
  -o results/sample

See the reference-building guide for local assemblies, metadata, resuming downloads, and output interpretation.

Common next steps

• Run mlvamaps COMMAND --help for command-specific options.
• CLI options and thresholds
• Input and panel formats
• Output file reference
• Calling and profiles
• Dataset aggregation and MYOGA export

mlvamaps uses 32 threads by default. Pass -t N to set a limit or -t 0 to use all detected CPUs. Use --quiet to suppress progress messages.

Development

conda env create -f environment.yml
conda activate mlvamaps
python -m pip install --no-deps -e .
pytest -q

The software is licensed under GPL-3.0-only. Please report problems through GitHub Issues.