migec

PyPI CI docs python C++ license

UMI barcode extraction, correction and consensus assembly for barcoded sequencing data.

A complete C++20 rewrite of MIGEC (Shugay et al., Nature Methods 2014) and MAGERI (Shugay et al., PLoS Computational Biology 2017).

Version 2 is under construction. All three stages work today, with cell barcodes, whitelists, dual-end and positional (10x) layouts, mate merging, cell calling, index-hopping estimation, QC figures, and suggest/subsample/plot. The published benchmark comparisons are what remain; see ROADMAP.md. The Groovy MIGEC 1.2.9 is archived on branch legacy-v1 and at tag v1-final — Java users want the jars on the 1.2.9 release.

Why

Tag each molecule with a random barcode before amplification and every read carrying that barcode descends from one original molecule, so collapsing them into a consensus removes essentially all sequencing error. The difficulty is entirely in the details: barcodes acquire errors of their own and an error child has to be told from a genuine collision; a molecule seen three times is still information rather than something to threshold away; and no consensus can repair an error made before the first amplification cycle, because it is in every read. migec measures that floor from the data and refuses to claim a quality above it.

the migec pipeline

Install

uv tool install migec      # or: uv pip install migec, or: pip install migec
migec info                 # prints the three version strings; they must agree

Wheels for CPython 3.10–3.13 on Linux x86-64 and macOS arm64, so nothing compiles. On a cluster whose system Python is older than 3.10, bring your own:

uv venv --python 3.12 ~/envs/migec && source ~/envs/migec/bin/activate && uv pip install migec

From source, for development: git clone https://github.com/antigenomics/migec && cd migec && bash setup.sh. See installation.

Where the barcode is

This is the one thing migec has to be told. Most libraries put the barcode at a fixed offset in one read, so that is the primary way to say it — a position, no sheet, no anchor:

migec checkout reads.fq.gz --bc-pattern '^NNNNNNNN'  -o out/    # 8 nt UMI at the read start
migec checkout reads.fq.gz --bc-pattern '0:8'        -o out/    # the same, as a half-open slice
migec checkout reads.fq.gz --bc-pattern '0:4,5:10'   -o out/    # 9 nt UMI split by one spacer base
migec checkout R1.fq.gz R2.fq.gz --bc-pattern 'cell:0:16,16:26' -o out/     # 10x

N is a UMI base, X a cell-barcode base, and slices are half-open and 0-based like Python's. A leading ^, and every slice list, anchors the barcode at the first base, so --max-offset never has to be passed. Or name the chemistry — migec sheet --presets prints all of them with the source each layout is written down in:

preset layout
umi ^NNNNNNNN generic inline UMI
migec cagtggtatcaacgcagagtNNNNtNNNNtNNNN MIGEC 5'-RACE RepSeq
primerid NNNNNNNNNcagtttaacttttgggccatcca HIV-1 Primer ID, as used by MAGERI
duplex ^NNNNNNNNNNNN..... on both mates duplex sequencing
10x ^XXXXXXXXXXXXXXXXNNNNNNNNNNNN 10x Chromium 3' v3
10x-v2 ^XXXXXXXXXXXXXXXXNNNNNNNNNN 10x Chromium 3' v2 and 5'
tso500 ^NNNNN..... on R1 Illumina TSO500 ctDNA — read the warning in layouts
smarter-umi ^NNNNNNNNNN... SMARTer template-switching RNA-seq 
migec checkout R1.fq.gz R2.fq.gz --preset 10x-v2 -o out/          # a named chemistry
migec checkout R1.fq.gz R2.fq.gz --read-structure 5M5S+T -o out/  # fgbio, Picard, samtools, TSO500
migec checkout reads.fq.gz -b barcodes.txt -o out/                # many samples: MIGEC's own table
migec suggest  reads.fq.gz                                        # if you do not know: read it off the data

A preset says where the barcode is. It does not say what a consensus is worth, and that matters more: the same 12 nt UMI serves a repertoire census and an MRD assay, and the right settings are opposite. migec sheet --assay ctdna prints the second half — the --min-reads and the pre-amplification floor the experiment implies, for eight profiles from airr to mrd (assays, layouts).

The pipeline

migec checkout  reads.fq.gz -b barcodes.txt -o out/   # find the barcode, cut it out, demultiplex
migec refine    out/S1.fq.gz -o ref/                  # correct the errors IN the barcode
migec assemble  ref/S1.fq.gz -o cons/                 # one consensus per molecule
migec subsample out/S1.fq.gz -o small.fq.gz --keep 1  # a fixture that is still a library

Those four and suggest are the pipeline; plot, sheet and info read no reads at all (commands).

Every stage takes -t/--threads (one per core by default) and --limit-read N / --limit-umi N, which stop the intake early — for getting an answer out of a 400 GB run in a minute, never as a sample. -t changes the wall clock and nothing else: the output is byte-identical at any thread count, which is what makes a retry on different cores comparable. Every run says what it did, what it cost, and what the barcode was worth:

reads       2,000,000
  assigned  2,000,000 (100.0%)
  unmatched 0 (0.0%)
  ambiguous 0 (0.0%)

1.6 s (1,243,801 reads/s) = 1.5 s matching on 8 threads + 0.1 s UMI statistics
peak RSS 136.0 MB of which UMI counters 11.5 MB

sample             reads        UMIs  reads/UMI  UMI len  eff len
S1               500,000     125,000       4.00       12    12.00

What comes out

Ordinary FASTQ, trimmed of adapter, sample tag and UMI. One record is one molecule, and its identity is carried twice — in the read name (<sample>.<cell>.<umi>, for tools that drop FASTQ comments) and in tab-separated SAM tags that survive into a BAM:

@r0 RX:Z:GCTAAAGACAAT	QX:Z:IIIIIIIIIIII	BC:Z:S1
TACATAACATACACGTCAGCACGAAACTTGTTGGCCCAGTGTGAATCGCTT
output what
<sample>.fq.gz, <sample>.consensus.fq.gz the reads, then one record per molecule
checkout.summary.tsv, .coverage.tsv, .umi_composition.tsv yields, MIG sizes, per-position base usage
<sample>.barcodes.tsv, .umi_errors.tsv, .mig.tsv every barcode with its parent, the error rate per depth, every molecule
<stage>.json all of it, machine-readable 
migec plot cons/          # twenty QC panels with gnuplot, straight off those TSVs

barcode rank plot

Each of these was run against real output (downstream):

minimap2 -ax sr -y ref.fa cons/S1.consensus.fq.gz | samtools sort -o S1.bam   # RX, CB, MI in the BAM
minibwa map -y -t8 ref.fa cons/S1.consensus.fq.gz | samtools sort -o S1.bam   # `-y`, not bwa's `-C`
bwa mem -C     ref.fa cons/S1.consensus.fq.gz     | samtools sort -o S1.bam
arda amplicon --r1 cons/S1.consensus.fq.gz -p S1      # AIRR sequence_id IS the molecule id
salmon quant -i tx.idx -l A -r cons/S1.consensus.fq.gz -o quant/   # NumReads are molecule counts

Never run alevin, bustools or STARsolo on a consensus FASTQ. They read the barcode out of a raw barcode read and deduplicate themselves; migec already did, and that read no longer exists.

What makes it different

  • Barcode correction uses the evidence that survives at one read per UMI — the barcode's own base quality and payload agreement, not only the count ratio, which reports zero there (refine).
  • Emitted quality is capped at the measured RT/first-cycle floor, Q40 by default and fitted from the data with --pre-amp-error auto, never taken from the instrument's (quality floor).
  • Every model-derived number has something model-free beside it: collisions, the barcode error rate, the split threshold (nulls, barcode space).
  • Nothing scales with the library — a range partition into buckets and a sorted counter array, 22 B per distinct UMI against a hash map's 48 (performance).
  • Twenty QC panels, each a gnuplot script over a TSV a stage already wrote, so a figure can never disagree with the report (plots).
  • For rare variants the molecule count decides, not the caller, and it is fixed before any software runs (variants, detection).

Documentation

https://antigenomics.github.io/migec/
Installation, Examples a copy-paste run per platform, and six marimo notebooks
Layouts, Assays where the barcode is, and what a consensus is worth once it is found
Commands all eight, with the number each one decides
Downstream what consumes the consensus, measured tool by tool
Variant calling, Detection limits which caller, and the molecules that decide whether any can see it
Method why every default is what it is: barcode space, nulls, the quality floor
Reference file formats, speed and memory, pipelines, roadmap
SOURCES.md every dataset, where it came from, and the command that re-fetches it

Citing

Until the v2 paper exists, cite the original methods:

  • Shugay M et al. Towards error-free profiling of immune repertoires. Nat Methods 11:653–655 (2014). doi:10.1038/nmeth.2960
  • Shugay M et al. MAGERI: Computational pipeline for molecular-barcoded targeted resequencing. PLoS Comput Biol 13(5):e1005480 (2017). doi:10.1371/journal.pcbi.1005480

License

GPL-3.0-or-later. The archived v1 code on legacy-v1 remains under its original MiLaboratory non-commercial license.

Project links

Data verified by PyPI on Aug 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.5.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mikessh from gravatar.com mikessh

Credits

Author: Mikhail Shugay

GitHub Statistics

Data verified by PyPI on Aug 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU General Public License v3 or later (GPLv3+) (GPL-3.0-or-later)

Requires

Python >=3.10

Provides Extra

seqtree notebooks docs test dev

Tags

umi barcode consensus airr repseq single-cell sequencing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

migec-2.4.0.tar.gz (853.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

migec-2.4.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (662.9 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

migec-2.4.0-cp313-cp313-macosx_11_0_arm64.whl (468.7 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

migec-2.4.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (662.9 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

migec-2.4.0-cp312-cp312-macosx_11_0_arm64.whl (468.2 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

migec-2.4.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (661.9 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

migec-2.4.0-cp311-cp311-macosx_11_0_arm64.whl (466.2 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

migec-2.4.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (661.9 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

migec-2.4.0-cp310-cp310-macosx_11_0_arm64.whl (464.1 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file migec-2.4.0.tar.gz.

File metadata

  • Download URL: migec-2.4.0.tar.gz
  • Upload date:
  • Size: 853.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for migec-2.4.0.tar.gz
Algorithm Hash digest
SHA256 b2756128ccbe32ef187f1aedde376da0defd96e25bc7fe9a602af58385fd7862
MD5 0461ee02029b3d5cbca19630e338b885
BLAKE2b-256 28424d4e9d95cf4fff1311bbe5fb982abb079bc7ad95eca3b605ea084518686d

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0.tar.gz:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file migec-2.4.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for migec-2.4.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fa4bd6c6e6e2944ca29cd193ae5115c2e49f38533728957b7fe6ffa984e02109
MD5 7f57bdda601fde484b86486db47d1d5d
BLAKE2b-256 a1277d791cf21f3ee964799345652a8e9ce49ee15c62c88ef3437e2048622767

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file migec-2.4.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for migec-2.4.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 48a8446f027219495f8c89f2231627d92c10afe8896030a4255bbc042cee8233
MD5 a348bf6fb44a60c808ab0a4024241b0e
BLAKE2b-256 e44089ebe1cfde546f32dcb15eb8beb3302cf01d6ce1957a6397c0bdcd6f11f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file migec-2.4.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for migec-2.4.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 805e8f9a4ac5fa65b8290d0ed5b77aae74572870a83395e34217a5033ad77a63
MD5 6aeaa371c1918f947802c31ffe5ba684
BLAKE2b-256 bca6cc73d3c2cd13316b496f8f2d77b53d2315ba849073d3684f061977c6eb92

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file migec-2.4.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for migec-2.4.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7e345a1d6cfb844e24be8726d53d0f8dfb8fc5d70d59e80abd63e366378da2ff
MD5 3bc0f8c83e36fd20f3fc1dfb136c5140
BLAKE2b-256 261fcf6f52d549bbae38bc7da557493a590becd60f3061e565c26009ae40b9c9

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file migec-2.4.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for migec-2.4.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ea737d5479994ac212d6325f791b06f88c3cc8b58aed33627f98134d7be65fa0
MD5 000cd53005af2fba698c0d04e23d3020
BLAKE2b-256 aff844fc9626ed5c1bef2d29d6cd25509e42bc963b0729e21ec2f1ca37dc043a

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file migec-2.4.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for migec-2.4.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4ec3c5d5b11ade338e87660265849771ce8228e6e2643e486fa85a80979863dd
MD5 61df7f941df309eadea3af118881ab77
BLAKE2b-256 a2ff3129500e92e51e99ca93e526ca487541a7e41e1d1cc81d1f374a6426fa58

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file migec-2.4.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for migec-2.4.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f19937f75b8774cb63da6eae8424bba0b1433275a268202e8965cfec68e56fcb
MD5 dc92c3264f3264ff438f5557e9ce3c57
BLAKE2b-256 5cc372ef168dc767db514b280ae1551ce40d56f898ef8f8ccccc25f1602b5a1b

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file migec-2.4.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for migec-2.4.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f926e6972ce0a7cf689aae4fc2205e7fa2919a44ebdf5e0b32198ec066b9a8a2
MD5 cb963ef64ff2db86afff6c73ece34b49
BLAKE2b-256 9d266c826da264399a6d9922d41fde1f64c007e332e07d88f9554dd7c51309a9

See more details on using hashes here.

Provenance

The following attestation bundles were made for migec-2.4.0-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: publish.yml on antigenomics/migec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page