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. Reference databases add alignment-based reference support using nucleotide variation and VNTR repeat-length evidence.

Assembly and FASTQ inputs retain their own evidence-recovery paths:

• Genome assemblies: Sassy-backed, primer-directed in silico PCR recovers candidate amplicons; the assembly caller applies MLVA_finder-compatible product selection and size-to-repeat conversion.
• Illumina reads: competitive minimap2 alignment supplies molecule evidence to the shared allele caller. Paired reads also use flank recruitment with mate rescue and, for uncertain loci, bounded local assembly through the shared product-length parser.
• Long-read or amplicon FASTQ: the same competitive candidate mapping is followed by direct molecule measurement and shared allele inference. SPOARS remains available for representative sequence correction and confirmation; it is not required before a repeat-count call.

Locus detection does not by itself imply a confident repeat-count call. Unresolved and missing calls remain explicit and are never converted to zero.

mlvamaps uses competitive minimap2 alignment against candidate MLVA allele contexts for both short- and long-read sequencing data. Technology-specific evidence is extracted from these alignments and integrated by a shared locus-level allele inference framework. minimap2 supplies competing alignments; it does not by itself determine the MLVA allele.

Reference typing uses one Emu-inspired alignment-likelihood framework: Sassy-recovered assembly amplicons are aligned to observed reference loci with Parasail; FASTQ molecules are competitively aligned to observed reference amplicons with minimap2. Nucleotide mismatches and repeat-length disagreement both contribute. Assemblies use isolate support; mixed read samples use EM. This is an independent implementation; the Emu package is not required.

Sassy-backed assembly PCR, MLVA_finder-compatible repeat counts and tables, recovered amplicons, and read SNP evidence remain available. Assembly runs with a database also retain reference-relative mismatch counts, repeat differences, and alignment CIGARs in classification/assembly_reference_evidence.tsv.

Optional repeat-profile trees visualize sample similarity and do not determine reference classification. See alignment-based classification and migration to the emu workflow.

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. Its native dependencies include the sassy>=0.2.2 command-line tool used for primer matching. If Sassy is installed outside the active environment, set SASSY_BIN to its executable path.

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.

Single-input calls write directly to the requested output directory. Directory and manifest calls write each sample under OUTDIR/<sample_id>/ and place only batch-wide aggregate tables and status information under OUTDIR/batch_summary/.

Build a reference database

Build directly from NCBI assemblies for one taxon:

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

The panel may be a minimal primer.csv (locus, forward primer, reverse primer) or a rich CSV/TSV panel. To compare one panel across taxa, provide taxids.csv:

taxid,name
86661,bacillus_cereus_group
1280,staphylococcus_aureus

mlvamaps build-reference \
  --taxids-csv taxids.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;
• one isolated extraction/QC work area per taxon; and
• a combined top-level database containing all taxa for automatic taxon identification.

Candidate indexes and the Deacon index are built once from the merged cohort, including when taxids.csv contains only one taxon.

A locus is amplifiable when at least one examined genome produces an amplicon retained by the normal primer-matching and filtering rules. Any retained reference amplicon remains available for comparison, including loci represented by a single genome. Taxa with no usable loci are recorded and do not stop later taxa.

Use a built database during calling:

mlvamaps call \
  -i sample.fasta \
  --database references \
  -o results/sample

Current databases store reusable competitive_mapping/candidate_contexts.fasta, candidate_metadata.tsv, short/long minimap2 indexes, and a broad real-genome Deacon recruitment index. A rich panel may still be used without a database; bounded contexts are then synthesized from its primers, flanks, repeat motif, expected range, and observed database states when available.

For a multi-taxid build, that command automatically loads the saved panel and taxon metadata, then identifies the closest reference IDs with taxon annotations. No separate panel, target taxid, calibration artifact, or taxon-identification flag is required. Databases that predate schema 2.0 must be rebuilt with the current mlvamaps build-reference so all competitive-mapping and recruitment assets have reproducible provenance.

See the reference-building guide for local assemblies, metadata, resuming downloads, and output interpretation. See the workflow architecture for resource reuse, streamed candidate mapping, and batch thread allocation.

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.