migec#
UMI barcode extraction, correction and consensus assembly for barcoded sequencing data — a complete C++20 rewrite of MIGEC and MAGERI.
Warning
Version 2 is under construction. All three stages work today — checkout, refine and
assemble — with cell barcodes, whitelists, dual-end and positional layouts, cell calling,
and suggest/subsample/plot. Index hopping and the published benchmark comparisons
are what remain; see Roadmap. The Groovy MIGEC 1.2.9
that this replaces is archived on the legacy-v1 branch and at tag v1-final.
What it does#
Molecules are tagged with a random barcode (a UMI) before amplification, so every read carrying the same UMI descends from one original molecule. Collapsing those reads into a consensus removes essentially all sequencing error, which is what makes rare-variant and repertoire work possible. Doing it correctly is harder than it looks:
barcodes themselves acquire errors, and telling an error-child barcode from a genuine collision needs the birthday bound, the base qualities, and the fact that a polymerase error in an early PCR cycle carries high quality in every read that inherits it;
a molecule seen 3–5 times is still information. Throwing it away because it is under a coverage threshold discards real sequence; migec keeps it and reports the uncertainty instead;
consensus cannot fix an error made during reverse transcription or the first PCR cycle, because it is present in every read. Any quality score above that floor is a fiction, so migec measures the floor from the data and refuses to emit a quality above it.
Pipeline#
FASTQ ──checkout──▶ tagged FASTQ ──refine──▶ corrected ──assemble──▶ consensus FASTQ
│ │ │
suggest barcode table, QC per-molecule tables
Every stage writes plain TSV beside its output, and migec plot draws those tables with gnuplot – so a figure can always be redrawn from the numbers that produced it.
The output is ordinary FASTQ with the sample, cell barcode and UMI in the read name and in
SAM-style tags, so minimap2, bwa, arda, salmon and kallisto consume it
directly – see Downstream: what consumes the consensus, where each of those was run against it.
The only thing that changes between platforms is where the barcode is, and the primary way to say that is a position:
migec checkout reads.fq.gz --bc-pattern '^NNNNNNNN' -o out/
migec checkout reads.fq.gz --bc-pattern '0:8' -o out/
migec checkout R1.fq.gz R2.fq.gz --preset 10x-v2 -o out/
See Layouts: where the barcode is for the presets, the slice grammar, fgbio read structures and barcode tables.
Where to go#
if you want to |
go to |
|---|---|
run something now |
Installation, then Examples – a copy-paste run per platform, and three marimo notebooks that fetch their own fixtures |
say where your barcode is |
Layouts for the grammar and the presets; suggest if you do not know |
start from a BAM that already has the UMI |
Bring your own UMI – capture, exome and ctDNA kits put the UMI in the
index read, so it arrives in |
know what to set for your experiment |
Assays – eight profiles, the |
understand one stage |
Commands – all eight, with the number each one decides |
look at the QC figures |
plot – twenty panels over the TSVs the stages wrote, including Cell Ranger’s barcode rank plot and the MIG size spectrum |
run a cohort |
Pipelines – the Nextflow modules and the SLURM array templates |
align, quantify or call variants on the consensus |
Post-processing – the headline benchmark against certified cfDNA, then Downstream: what consumes the consensus, Variant calling: which caller, and what it can possibly see and How low can you go: exome, ctDNA and MRD |
know why a default is what it is |
|
look up a column or a tag |