MADCATS

Marker-Anchored Discovery and Counting of Alleles from Targeted Sequencing.

madcats is a command-line tool that turns targeted-sequencing FASTQs into MADC microhaplotype count tables. It counts the alleles a panel was designed for and finds additional ones in the reads. The output is a raw MADC table, which goes through HapApp before dosage calling and VCF conversion.

The same code handles DArTag, AgriSeq (Ion Torrent), GT-seq, rhAmpSeq and Flex-Seq capture data. It needs only the Python 3 standard library. Every analysis threshold is a command-line option, and each run writes a JSON file recording its parameters and read counts.

A prior MADC is not an input. Generation uses only the FASTQs plus the assay design: the DArTag primer/probe files, a probe design alone, or a platform-neutral Ref/Alt tag manifest.

Highlights

• Validated against vendor MADCs: count correlation r = 0.9997 on DArTag sweetpotato, and 95–99% dosage agreement across five DArTag panels
• Three ways to define a panel: from vendor design files (madcats design), from the probe design plus reads when the primer file is withheld (madcats infer-design), or from any hand-curated Ref/Alt tag CSV
• Evidence-based allele discovery: a new microhaplotype is reported only when it recurs across samples, reaches high depth in one sample, or (optionally) has enough high-quality reads. UNOISE-style denoising then removes sequencing errors without changing any sample's Ref/Alt dosage
• Indel-aware: designed indels are supported, and undesigned indels are recovered with a gapped alignment that caps the number of substitutions and gaps
• Non-primer-started platforms: madcats normalize-reads orients and windows AgriSeq-style reads, and madcats merge-pairs handles paired-end data
• HapApp-ready output: raw MADC tables with an optional vendor-style preamble for HapApp, which prepares them for BIGr and other downstream tools, plus per-row Variants / MarkerType annotations
• Pure Python, no dependencies, with parallel processing (--jobs) and a reusable per-sample cache

Installation

From PyPI (Recommended)

Requires Python 3.9 or newer.

pip install madcats
madcats --help

To keep it isolated from other Python packages, use pipx: pipx install madcats.

Pre-built Binaries

Standalone executables that need no Python installation are attached to each release:

• madcats-linux-x86_64.tar.gz: Linux
• madcats-macos-x86_64.tar.gz: macOS (Intel)
• madcats-macos-aarch64.tar.gz: macOS (Apple Silicon)

# Download and extract (example: Linux)
curl -LO https://github.com/Breeding-Insight/MADCATS/releases/latest/download/madcats-linux-x86_64.tar.gz
tar -xzf madcats-linux-x86_64.tar.gz
./madcats --help

# Optional: install to PATH
mkdir -p ~/bin && mv madcats ~/bin/
# Add to PATH if not already (add to ~/.bashrc or ~/.zshrc):
# export PATH="$HOME/bin:$PATH"

From Source

git clone https://github.com/Breeding-Insight/MADCATS.git
cd MADCATS
pip install .            # or: python3 madcats.py --help (no install needed)

Quick Start

To try MADCATS on a small simulated project first, see Try the Example.

# 1) Reconstruct each marker's Ref/Alt tags from the DArTag design files
madcats design \
  --primers panel_primer_sequence.csv \
  --probe-design panel_probe-design.txt \
  --output reference_tags.csv

# 2) Generate the MADC count table from one FASTQ per sample
madcats generate \
  --fastq-dir fastqs/ \
  --reference-tags reference_tags.csv \
  --cache-dir work/cache \
  --jobs 8 \
  --output results/project_MADC.csv

# 3) Optional: compare against a vendor-delivered MADC
madcats validate \
  --generated results/project_MADC.csv \
  --expected vendor_MADC.csv \
  --report results/validation.json

No primer file? Infer the panel from the probe design and the reads:

madcats infer-design \
  --probe-design panel_probe-design.txt \
  --fastq-dir fastqs/ \
  --output reference_tags.csv

Reads that are not primer-started (for example AgriSeq on Ion Torrent) are normalized first:

madcats normalize-reads --probe-design markers.tsv --fastq-dir raw_fastqs/ --out-dir normalized/ --jobs 8
madcats generate --fastq-dir normalized/ --fastq-glob "*.fastq" \
  --reference-tags normalized/window_reference_tags.csv \
  --tag-length 41 --min-supporting-freq 0.10 --output project_MADC.csv

Documentation

Full documentation is available at madcats.readthedocs.io, including:

• Getting Started: installation and first steps
• Tutorials: walkthroughs for DArTag, primer-free, AgriSeq and paired-end data
• Command Reference: every subcommand and option
• Evidence Model: how alleles are counted, discovered and denoised

The design rationale and version-by-version measurements behind every default are recorded in the development record.

Commands

Command	Description
madcats design	Reconstruct Ref/Alt tags from vendor primer + probe-design files
madcats infer-design	Infer a reference-tag panel from the probe design plus FASTQ evidence
madcats merge-pairs	Merge overlapping paired-end reads into single fragments
madcats normalize-reads	Orient and window non-primer-started amplicon reads (e.g. AgriSeq)
madcats window-scan	Sweep candidate tag lengths and recommend one from the project's own reads
madcats generate	Generate the MADC count table
madcats validate	Compare a generated MADC against a reference MADC

Run madcats <command> --help for full options.

Input Formats

Reference tags (CSV)

The platform-neutral panel definition that generate consumes. Produced by design, infer-design or normalize-reads, or curated by hand.

MarkerName,LeftPrimerSequence,RefSequence,AltSequence
Chr01_000123,ACGTTGCAGGTCAAGT,ACGTTGCAGGTCAAGTTCA...,ACGTTGCAGGTCAAGTTCG...

VariantPositionInTagSequence, VariantRef, VariantAlt, RightPrimerSequence and LocusGroup are optional.

Probe design (TSV/CSV)

MarkerName and TargetSequence with one bracketed variant: a SNP such as [C/T] or an anchored indel such as [A/ACTTG].

FASTQs

One FASTQ (optionally gzipped) per sample in a folder. Sample columns are named by the FASTQ stem, or by a --sample-lookup table.

Output

File	Contents
project_MADC.csv	MADC table: AlleleID, CloneID, AlleleSequence, summary columns, one read-count column per sample
project_MADC.csv.qc.json	Parameters, provenance, and per-sample read accounting
project_MADC.csv.variants.csv	One line per variant event per row (with --annotations on, the default)

Validation

Each platform was checked against the best independent comparison available for its dataset. "Genotype agreement" means updog dosage calls made from the MADCATS table (through HapApp and BIGr) compared with the reference genotypes.

Platform	Accuracy	Validated against
DArTag (sweetpotato, red clover, blackberry, alfalfa, pecan)	count r = 0.9997; dosage agreement 95.4–98.8%	vendor MADC, vendor/updog dosage, families, skim-seq VCF
AgriSeq, Ion Torrent (honeybee, oyster)	94.9% vs Torrent VariantCaller; 98.0% replicate concordance	vendor caller + replicates
GT-seq (delta smelt)	99.49%	independent BWA/bcftools truth VCF
Flex-Seq capture (cranberry)	95.13% genotype agreement	published population VCF + 20 trios
rhAmpSeq (8 grape families)	99.92–99.99% family transmission	Mendelian constraints + same-reads head-to-head

Details: Validation & Accuracy.

Development

python3 -m unittest discover -s tests -v

See Contributing for the docs build and release process.

Citation

If MADCATS is useful in your work, please cite:

Sandercock, A.M. (2026). MADCATS: Marker-Anchored Discovery and Counting of Alleles from Targeted Sequencing. GitHub repository: https://github.com/Breeding-Insight/MADCATS

(A formal article/DOI is planned; this section will be updated when available.)

For the MADC format, see Breeding Insight's MADC file format overview.

AI assistance: MADCATS was developed in collaboration with Claude Opus 5.5 and Fable 5.1 (Anthropic), which helped write its code and documentation. The authors directed the work, reviewed and tested the results, and are ultimately responsible for the application.

License

GPL-3.0-or-later