Align V(D)J reads and assemble TCR/BCR clonotypes with MiXCR, driven by a chemistry-matched preset. Use when choosing/auditing the preset for a library (5'RACE/template-switch vs multiplex-primer amplicon -> rigid vs floating boundaries; RNA vs gDNA -> --rna/--dna; bulk vs 10x single-cell; UMI vs no-UMI -> tag pattern and barcode collapse; kit presets Takara/NEBNext/QIAseq/BD/MiLaboratory); assembling clonotypes by CDR3 vs VDJRegion; setting the reads-vs-UMI-vs-cell quantitation denominator; exporting native MiXCR fields vs AIRR rearrangement TSV for downstream Immcantation/scirpy/VDJtools; and running alignment/chain-usage QC. Keywords: MiXCR, analyze, align, refineTagsAndSort, assemblePartial, assemble, assembleCells, exportClones, exportAirr, exportQc, CDR3, V(D)J, clonotype, UMI, cell barcode, 10x VDJ, license.
Align V(D)J reads and assemble TCR/BCR clonotypes with MiXCR, driven by a chemistry-matched preset. Use when choosing/auditing the preset for a library (5'RACE/template-switch vs multiplex-primer amplicon -> rigid vs floating boundaries; RNA vs gDNA -> --rna/--dna; bulk vs 10x single-cell; UMI vs no-UMI -> tag pattern and barcode collapse; kit presets Takara/NEBNext/QIAseq/BD/MiLaboratory); assembling clonotypes by CDR3 vs VDJRegion; setting the reads-vs-UMI-vs-cell quantitation denominator; exporting native MiXCR fields vs AIRR rearrangement TSV for downstream Immcantation/scirpy/VDJtools; and running alignment/chain-usage QC. Keywords: MiXCR, analyze, align, refineTagsAndSort, assemblePartial, assemble, assembleCells, exportClones, exportAirr, exportQc, CDR3, V(D)J, clonotype, UMI, cell barcode, 10x VDJ, license.
Before using code patterns, verify installed versions match. If versions differ:
CLI: mixcr --version (also prints the JVM) then mixcr <command> --help to confirm flags
If a command errors with an unknown-flag, unknown-preset, or missing-license message, run
mixcr <command> --help and mixcr exportPreset --preset-name <name> and adapt rather than retrying.
Note: MiXCR 4.x is a rearchitecture of 3.x. The hand-built mixcr analyze amplicon/analyze shotgun pipelines are GONE, replaced by mixcr analyze <preset>; correctAndSortTags became refineTagsAndSort; AIRR export moved to a dedicated mixcr exportAirr. Current 4.x needs Java 17 and an activated license (see the licensing gate below). Any 3.x tutorial is stale.
MiXCR Analysis
"Extract TCR/BCR clonotypes from my sequencing data" -> align raw reads to V/D/J/C germline, collapse molecules/cells by barcode, and assemble reads into clonotypes keyed on CDR3 + V + J.
CLI: mixcr analyze <preset> runs the whole ordered pipeline; the underlying stages (align -> refineTagsAndSort -> assemblePartial/extend -> assemble -> assembleCells -> exportClones/exportAirr -> qc) can be run by hand for control.
The governing principle: the preset IS the analysis, and the wrong one fails silently
In MiXCR 4.x there is no default-correct pipeline. Correctness is ~90% preset choice plus library-chemistry match. mixcr analyze <preset> expands the preset into an ordered stage list encoding material (RNA vs DNA), 5'/3' alignment-boundary behavior (rigid vs floating), the barcode tag pattern, the assembling feature, and species defaults. The wrong preset does NOT raise an error -- it emits plausible-but-wrong clonotypes: a mismatched RNA/DNA model or boundary model mis-places V/J boundaries and truncates CDR3; a UMI kit run without a tag pattern skips barcode collapse and inflates diversity with PCR/sequencing artifacts. Because the failure is silent, the load-bearing skill is choosing and AUDITING the preset. Dump exactly what a preset does with mixcr exportPreset --preset-name <name> (full resolved parameter YAML), and confirm chemistry with mixcr exportQc align/chainUsage after the run. A clonotype is an analyst choice, not a fact: it is CDR3 (+ V + J) at a chosen boundary (assembling feature), counted in a chosen denominator (reads vs UMIs vs cells) -- every downstream number depends on these.
Licensing gate (do this first, or every run fails)
MiXCR 4.x refuses to run any analysis command until a license is activated -- the single most common reason a copied 3.x recipe fails today. Academic/non-profit use is free (obtain a key at platforma.bio/getlicense); for-profit use needs a business license. Activate by any one of:
mixcr activate-license then paste the key (interactive).
Place mi.license (or ~/.mi.license) in ~/, next to mixcr.jar, or next to the executable.
Set MI_LICENSE=<key content> or MI_LICENSE_FILE=/path/mi.license (best for HPC/Docker/CI).
MiXCR also validates the key over the internet periodically. On air-gapped or firewalled compute nodes, whitelist IPv4 75.2.96.100 and 99.83.215.63 (and the corresponding IPv6) or arrange an offline license, or a job silently stalls waiting on egress.
Preset selection by library type
The preset must match the exact wet-lab chemistry. Inspect the built-in list with mixcr exportPreset and the docs; verify current names against mixcr analyze --help since MiLaboratories occasionally renames presets between minor releases.
Library / chemistry
Preset (verified 4.7)
Material
5' boundary
UMI/barcode
Biology consequence if mismatched
5'RACE / template-switch bulk (e.g. SMARTer)
kit preset, or generic-amplicon/-with-umi with --rigid-left-alignment-boundary
--rna
RIGID (5' set by template-switch oligo)
kit UMI or --tag-pattern
Floating-left on RACE trims real 5' V sequence; missing tag pattern skips UMI collapse
Multiplex-primer amplicon (V/J or V/C primers)
kit preset, or generic-amplicon with --floating-left-alignment-boundary
--rna or --dna
FLOATING on the primer side
as designed
Rigid boundary counts primer bases as germline mismatch -> wrong V call, truncated CDR3
name decodes <vendor>-<species>-<rna/dna>-<chain>-[umi]-<protocol>
For generic-* presets --species <hsa|mmu|...> is REQUIRED (forgetting it fails or misaligns). xcr presets cover TCR and BCR together; single-chain presets (trb, ig) cover one locus. For gamma-delta (TRG/TRD), use the same generic/kit presets and restrict chains at export with -c TRG / -c TRD (or a gd-specific kit preset if the wet-lab kit targets gd); note that a gd repertoire is invisible if the library only primed alpha-beta.
Pipeline stages and where each one fails
mixcr analyze <preset> R1.fastq.gz R2.fastq.gz out_prefix runs the ordered stages below; the preset is embedded in the binary .vdjca/.clns files so hand-run commands only name the preset on align.
Stage
Command
Purpose
Common failure
Align
mixcr align -p <preset> --species hsa ...
Reads -> V/D/J/C germline; extract barcodes if tag pattern set
Low alignment rate: wrong species/material/boundaries, untrimmed primers, reads too short to span CDR3
Refine tags
mixcr refineTagsAndSort
UMI + cell-barcode error correction and sort
Skipped on a UMI library -> barcode errors become fake clonotypes; memory-heavy (~32 GB on large single-cell)
Assemble partial
mixcr assemblePartial (run x2)
Overlap fragmented mates that each cover part of CDR3 (RNA-seq/10x)
Needs align --keep-non-CDR3-alignments first; on amplicon reads that already span CDR3 it is wasted
Extend
mixcr extend
Impute unambiguous missing V/J germline ends
Safe for TCR; on BCR can fabricate germline over SHM-mutated ends
Assemble
mixcr assemble
Collapse alignments into clonotypes by the assembling feature; PCR/error correction, UMI consensus
Native field-name mistakes; forgetting -c/--chains; not filtering non-productive
QC
mixcr qc, mixcr exportQc align/chainUsage
Alignment rate, chain composition, tag coverage
Not run -> silent quality problems pass downstream
From MiXCR 4.7, presets that do not intrinsically define an assembling feature REQUIRE --assemble-clonotypes-by <feature> (e.g. CDR3, VDJRegion); older tutorials that omit it now error. CDR3 is the robust default on short reads; VDJRegion needs reads/contigs spanning V-through-J and keeps SHM variants separate (useful for BCR full-length).
The quantitation denominator: reads vs UMIs vs cells
Clonotype abundance is only meaningful relative to the chemistry. Report the right unit or reintroduce the bias the chemistry was meant to remove:
Non-UMI bulk: abundance = readCount (cloneCount is an alias). PCR-amplification biased -- not a molecule count.
UMI bulk: after refineTagsAndSort, report uniqueMoleculeCount (generic form uniqueTagCount Molecule), NOT reads. Reporting reads on a UMI library re-adds the amplification bias the UMIs removed.
Single-cell: the unit is the CELL (uniqueTagCount Cell / cellGroup), not reads or UMIs.
Export: native MiXCR fields vs AIRR
MiXCR's native export headers are NOT AIRR or VDJtools names. Downstream renaming to a chosen schema is a user-side step; the field names to select from MiXCR are its own.
For AIRR-schema interchange (Immcantation, scirpy, any AIRR tool) use the dedicated command, which emits sequence_id, v_call, d_call, j_call, junction, junction_aa, productive, duplicate_count, cell_id:
mixcr exportAirr clones.clns clones.airr.tsv
Field-name traps (do NOT use as MiXCR selectors): count/frequency/cdr3_aa/vGene are VDJtools/AIRR conventions, not MiXCR headers. A downstream tool expecting AIRR names should be fed exportAirr output, not renamed native output.
The D-gene caveat: never key or trust the D call in TRB/IGH
Dbeta and Dh segments are short (~12-16 nt) and heavily trimmed at both ends with N-additions between; the surviving germline-matchable D stretch is often 0-5 nt, statistically indistinguishable from random junctional nucleotides. A substantial fraction of TRB rearrangements have no detectable D at all (de Greef & de Boer 2021 PNAS 118:e2104367118), and any "longest germline D match" over-calls D by chance. Treat bestDGene/allDHitsWithScore as unreliable: never use the D call as a clonotype key, never stratify biology by D usage without heavy skepticism, and expect large tool-to-tool D disagreement. Clonotypes are keyed on CDR3 + V + J -- not D. This caveat is TRB- and IGH-specific: the TRD (delta) chain can incorporate one to two D segments in tandem, giving more germline D content than TRB's single heavily-trimmed D, so the D call is more informative for gamma-delta work (the junction is still highly diverse from N-additions).
QC: match preset to chemistry, catch cross-contamination
Read exportQc align: targeted amplicon should align high (often >80-90%); a low rate signals wrong species/library/boundaries or untrimmed primers, and "absent CDR3" means reads too short or wrong boundaries. RNA-seq mining legitimately aligns a tiny fraction (only receptor-overlapping reads) -- judge it by absolute clonotype yield, not %. Read chainUsage: a TRB library showing appreciable IGH signals cross-contamination or index hopping on patterned flowcells. A huge reads-to-clonotypes drop (millions -> thousands, worse after UMI collapse) is normal; a tiny clone count with high alignment suggests over-aggressive filtering or a wrong assembling feature.
Common Errors
Symptom
Cause
Fix
Every processing command (align/analyze/assemble) refuses to run
No activated license (4.x mandatory for the pipeline; mixcr --version/exportPreset still work)
mixcr activate-license or set MI_LICENSE_FILE; whitelist phone-home IPs on firewalled nodes
mixcr analyze amplicon ... unknown
3.x command removed in 4.x
Use mixcr analyze <preset>; pick a chemistry-matched preset
Runs cleanly but clonotypes look wrong (truncated CDR3, odd V calls)
Wrong preset / boundary / material -- silent, no error
Match preset to chemistry; audit with mixcr exportPreset; check exportQc align
Diversity far too high, many near-identical clones
UMI kit run without tag pattern -> no barcode collapse
Use the UMI preset or add --tag-pattern; ensure refineTagsAndSort ran; report uniqueMoleculeCount
RNA-seq run yields almost no clonotypes
No assemblePartial/extend; partials filtered at align
align --keep-non-CDR3-alignments, assemblePartial twice, then extend (or use rna-seq preset)
assemble errors asking for an assembling feature
Preset lacks intrinsic feature (4.7+)
Add --assemble-clonotypes-by CDR3 (or VDJRegion)
Downstream AIRR tool rejects the table
Fed native MiXCR headers, not AIRR
Export with mixcr exportAirr, not renamed exportClones
