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 :doc:`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 -------- .. code-block:: text 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 :doc:`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 :doc:`downstream`, 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: .. code-block:: bash 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 :doc:`layouts` for the presets, the slice grammar, fgbio read structures and barcode tables. Where to go ----------- .. list-table:: :header-rows: 1 :widths: 22 78 * - if you want to - go to * - **run something now** - :doc:`Installation `, then :doc:`Examples ` -- a copy-paste run per platform, and three marimo notebooks that fetch their own fixtures * - say where your barcode is - :doc:`Layouts ` for the grammar and the presets; :doc:`suggest ` if you do not know * - start from a BAM that already has the UMI - :doc:`Bring your own UMI ` -- capture, exome and ctDNA kits put the UMI in the index read, so it arrives in ``RX`` and never passes through ``checkout`` * - know what to set for **your** experiment - :doc:`Assays ` -- eight profiles, the ``--min-reads`` each one wants, and which pre-amplification floor your chemistry has * - understand one stage - :doc:`Commands ` -- all eight, with the number each one decides * - look at the QC figures - :doc:`plot ` -- twenty panels over the TSVs the stages wrote, including Cell Ranger's barcode rank plot and the MIG size spectrum * - run a cohort - :doc:`Pipelines ` -- the Nextflow modules and the SLURM array templates * - align, quantify or call variants on the consensus - :doc:`Post-processing ` -- the headline benchmark against certified cfDNA, then :doc:`downstream`, :doc:`variants` and :doc:`detection` * - know why a default is what it is - :doc:`Method ` * - look up a column or a tag - :doc:`Reference ` .. toctree:: :maxdepth: 1 :hidden: installation examples Layouts Bring your own UMI Assays commands Post-processing method reference