From immune-receptor reads to inspectable clonotypes.
Python 3.10+ · Version 0.2.0 · MiXCR 3.0.13 research reconstruction
A Python implementation of human V(D)J alignment and clonotype reconstruction. Read FASTQ files, inspect V/D/J/C assignments, assemble clones, and reconstruct contigs with transparent JSON, TSV and FASTA outputs.
Core algorithms run in Python with NumPy and bundled references. Java is used separately for optional comparisons with the original MiXCR 3.0.13 program.
Research scope. The validated target is 3.0.13, using selected human reference and parameter profiles. The upstream research license restricts eligibility and use; see License. This project is independent of MiLaboratories.
Workflow overview. Gene names and sequence cartoons are illustrative. Clone counts 12 and 8 come from the bundled 20-read synthetic example. Download PDF
Start with reads. Supply single or paired human TCR/BCR FASTQ files. Alignment finds compatible V/D/J/C gene segments and identifies the CDR3 junction; some receptor loci use V and J without a D segment.
Recover clones and sequences. Assembly groups reads into clonotypes and records each read's assignment. Partial-read overlap and contig reconstruction are optional steps. Tables support abundance analysis, while annotated sequences make the result inspectable.
Check the evidence. The lower lane feeds the same FASTQ to the original 3.0.13 program and the Python implementation, then compares scientific fields. This independent development check establishes the documented tested cases.
| Capability | Available in this release |
|---|---|
| Input | Single or paired FASTQ, including gzip |
| Alignment | Human TCR/BCR genes, V/D/J/C hits, scores and feature coordinates |
| Clones | CDR3 and selected multi-feature assembly; quality-aware mapping and clustering |
| Paired reads | Overlapping or unmerged pairs, Opposite layout |
| Partial reads | Overlap assembly with contributing read IDs |
| Contigs | Default CDR3-clone reconstruction with annotated branches |
git clone https://github.com/thekingofall/Biosoft-Project-MiXCR-Python.git
cd Biosoft-Project-MiXCR-Python
python -m venv .venvActivate with source .venv/bin/activate on Linux/macOS or .venv\Scripts\Activate.ps1 in Windows PowerShell, then run:
python -m pip install ./python
python -m mixcrpy analyze examples/trb.fastq results/single --chains TRB
python -m mixcrpy analyze examples/trb_R1.fastq results/paired --read2 examples/trb_R2.fastq --chains TRB
python -m mixcrpy assemble-contigs results/single.alignments.json results/single.clones.json results/contigs
python scripts/check_example.py resultsThe bundled example contains 20 synthetic reads from two TRB templates. The verified result is two clones with counts 12 and 8, and two contig branches. The sequences come from the bundled reference and contain no patient information.
For your own reads:
mixcrpy analyze reads_R1.fastq.gz results/sample --read2 reads_R2.fastq.gz --chains TCRUse a new output prefix for each run. Add --force when replacing an existing run.
| File suffix | What it tells you |
|---|---|
.clones.tsv |
Clone abundance, V/D/J/C hits and CDR3 sequence |
.read-assignments.tsv |
The clone or rejection reason for each input record |
.alignments.tsv |
Gene hits, scores, CDR3 and status for each record |
.report.json |
Read counts, assembly statistics and settings |
.alignments.json, .clones.json |
Structured intermediates for separate steps |
.contigs.fasta, .contigs.tsv, .contigs.json |
Reconstructed sequences, annotations and branch details |
The usage guide covers paired headers, multi-feature assembly, partial reads, contigs and troubleshooting.
Six FASTQ comparisons against the original 3.0.13 program showed zero differences in the fields checked. They cover synthetic TRB and upstream TRB/IGH examples, single and paired reads. Separate comparisons cover partial assembly, multi-feature assembly and contigs. The portable test suite and captured original-program expectations are included.
python -m pip install pytest
python -m pytest python/tests -qThe validation report lists datasets, measured fields, results and limits. To compare the bundled example with your own original 3.0.13 JAR, follow the comparison instructions.
Validation covers finite datasets and selected profiles. Other species, arbitrary scoring, KAligner2, alternative paired layouts, single-cell barcode processing, allele inference and SHM trees are outside the supported interface. Native MiXCR binary files (.vdjca, .clns, .clna) are not accepted by this Python CLI. The CLI holds alignments in memory; size a pilot run before using large datasets. Clinical validation and production-scale performance have not been established.
| This project | Official MiXCR |
|---|---|
| Python package 0.2.0 | Latest stable GitHub release checked: 4.7.0 |
| Compatibility target 3.0.13 | Published 7 August 2024 |
| Human references exported from repseqio.v1.6 | Newer features described in version notes |
The latest-release check was made on 12 October 2026. This repository contains the older research reconstruction and a sourced overview of the newer release.
MiXCR/MiLib-derived portions retain the original research license, including its restriction to educational, research and nonprofit purposes by nonprofit institutions. Commercial use requires separate permission from the upstream licensor. Public visibility does not expand these rights.
WELL19937c-derived code retains the Apache Commons Math notices and Apache 2.0 terms. See NOTICE, third-party license and provenance.