Methods and validation
ClonoLoom implements each method itself, from its publication, and checks it against an independent implementation, the vendor's own numbers, or a simulated repertoire whose every clonotype is known. Each method below names its source and what it agrees with.
How methods are checked
Three kinds of check, as each method allows: the same numbers as an independent implementation of the same method on the same inputs (the airr library, pandas, scirpy, iNEXT, immunarch, vegan and R, run by scripts in the repository's validation/reference/ and their outputs committed); the truth of a simulated study, whose every clonotype, sample and expectation is known; and invariants worked by hand on small cases. Tools under licenses ClonoLoom cannot include are only run, never copied.
| Data | What it is | Used for |
|---|---|---|
| 10x Genomics single-cell V(D)J runs (human PBMC 1k and 10k, mouse splenocytes 1k and 5k) | Cell Ranger 4.0, 6.1 and 9.0 outputs, CC BY 4.0 | Readers, QC, clonotypes, overlap, the examples, CI |
| The AIRR Community's test files (v2.0.0) | CC BY 4.0 | The AIRR reader, every analysis, CI |
| Dash et al. 2017's epitope-specific TCRs (mouse and human), as tcrdist3 distributes them | MIT (tcrdist3) | The tcrdist3 reader, an example, CI |
| OTS and OAS data units: three donors' paired TCRs, an antibody repertoire's paired and unpaired chains | CC BY 4.0 (Oxford Protein Informatics Group) | The units' reader, an example, CI |
| tcrdist3's database of genes (the V genes' CDR1, CDR2 and CDR2.5), downloaded on request | MIT (tcrdist3); IMGT's germline genes, CC BY 4.0 | TCRdist's loops, CI |
| OLGA's seven default recombination models (IGoR's format), downloaded on request | GPL-3.0 (OLGA's repository); the model files carry no license of their own | Generation probabilities, CI |
| MiXCR 3 clone tables (PyClonal's sample inputs) and a MiXCR 4 single-cell table (MiLaboratories' benchmark) | MIT; no license stated | The MiXCR reader: CI, and the maintainer's computer only for MiXCR 4's |
| Emerson et al. 2017, three subjects, in immunoSEQ's format and from the AIRR Data Commons | immuneACCESS Terms of Use: research only, no redistribution | Validation on the maintainer's computer only |
| Simulated TRB studies | Made by clonoloom simulate, seeded | Accuracy against the truth; interval coverage; scale |
Reading and checking data
ClonoLoom reads AIRR Rearrangement TSV (schema 1.3 to 2.0; Vander Heiden et al. 2018) with its Repertoire metadata (Rubelt et al. 2017), Cell Ranger V(D)J contig annotations and output folders, immunoSEQ v2 and v3 exports, MiXCR 2, 3 and 4 clone tables, the data units of the Observed Antibody Space (Olsen et al. 2022) and the Observed T cell receptor Space (Raybould et al. 2024), and tcrdist3's clone tables (Mayer-Blackwell et al. 2021) with its own readers, into one columnar table. Every column of 35 development files equals what the AIRR Community's airr library 2.0.0 and pandas 3.1.0 read from them, and the SHA-256 each reader takes while reading equals each file's recorded checksum: every byte was read, and none was changed. The readers were fuzzed with 33 million inputs without a fault. Gene calls are kept in IMGT nomenclature (Lefranc 2014), Adaptive's names mapped to IMGT's by ClonoLoom's rules and the HGNC list of human TR and IG genes (Seal et al. 2023). A table of another tool is read through a mapping of its columns that the user confirms, checked over the whole file first. A million rearrangements are read and validated in 1.5 s, at 58 bytes a row and their junctions.
Quality control
On six bulk samples (immunoSEQ, the AIRR Data Commons and the AIRR Community's files), rows, abundance, productive share, clonotypes, singletons, doubletons and the largest clonotype's share equal an independent R implementation's, and sample coverage (Chao and Jost 2012) equals iNEXT 3.0.2's, to 10⁻¹². Cell Ranger's cell metrics (cells, cells with a productive pair, with a productive chain of each locus, as counts and shares) are reproduced exactly as Cell Ranger 4.0, 6.1 and 9.0 reported them for six T- and B-cell runs, and immunoSEQ's productive clonality, Simpson clonality, entropy and largest frequency from each rearrangement's reads, as Adaptive computes them, to seven significant digits. On the simulated standard study, each sample's estimated coverage is within 0.005 of the coverage a sample of its depth has on average.
Clonotypes
A clonotype definition names the junction (nucleotides or amino acids, the IMGT junction from the conserved cysteine at 104 to the phenylalanine or tryptophan at 118; Lefranc et al. 2003), the V and J genes at allele, gene or family level or not at all, the chains, and for single cells which chains of a cell count. On eight Cell Ranger runs (T and B cells, Cell Ranger 4.0, 6.1 and 9.0), ClonoLoom's paired definitions give exactly scirpy 0.25.1's partitions of cells (Sturm et al. 2020), by nucleotide and amino-acid junction, with and without the V gene; Cell Ranger's own clonotypes have the sizes its clonotypes.csv gives; bulk clonotypes equal the R implementation's on six samples under three definitions. A page of a million clonotypes, sorted and searched, comes in 37 ms.
Diversity
| Measure | Source | Checked against | Agreement |
|---|---|---|---|
| Hill numbers of order 0 to 4, Shannon's entropy, Simpson's index, evenness, clonality, Gini, the largest clonotypes' shares, homeostasis | Hill 1973 | R; immunarch's functions on 18 samples | to 10⁻⁹ |
| Chao1 (bias-corrected) and its log-transformed interval | Chao 1984; Chao et al. 2014 | iNEXT 3.0.2 and immunarch | to iNEXT's three printed decimals |
| ACE | Chao and Lee 1992 | vegan 2.7.6 | equal |
| The Shannon and Simpson diversity of the repertoire | Chao, Wang and Jost 2013; Chao et al. 2014 | iNEXT 3.0.2 | to its three printed decimals |
| Sample coverage | Chao and Jost 2012 | iNEXT 3.0.2 | to 10⁻¹² |
| Bootstrap standard errors (200 replicates) | Chao et al. 2014, Appendix G | iNEXT 3.0.2 | 0.86 to 1.13 times iNEXT's (median 0.98) |
Over 200 samples of a well-sampled simulated repertoire (coverage 0.99), the 95% intervals held the truth in 96.0% of samples for Chao1, 93.5% and 91.5% for the estimated Shannon and Simpson diversity, and 92.5% to 99.5% for the values seen. In an undersampled repertoire (coverage 0.62), Chao1 and the estimated Shannon diversity are lower bounds and their intervals never held the truth; the Repertoire view says so whenever a sample's coverage is below 0.9. iNEXT floors the estimated Simpson diversity's interval at the value seen; with that floor, the interval held the truth in under half the samples, so ClonoLoom does not apply it.
Rarefaction and extrapolation
Each sample's clonotypes, Shannon diversity and Simpson diversity (the Hill numbers of order 0, 1 and 2) and its coverage are rarefied below its size and extrapolated up to twice it (Chao et al. 2014), and the Hill numbers given at any coverage (Chao and Jost 2012). On 18 samples, at iNEXT 3.0.2's 40 sizes along each curve (Hsieh et al. 2016), every value equals iNEXT's to 10⁻⁹, except the extrapolated Shannon diversity, within 8 × 10⁻⁸: its extrapolation magnifies iNEXT's rounding of the value seen, which ClonoLoom computes to 10⁻¹⁵. Two cohorts compared at iNEXT's default levels give the same levels and values; the bootstrap standard errors are 0.85 to 1.26 times iNEXT's (median 1.01, over 4,240).
On simulated repertoires, rarefied to half a sample's size, every value's 95% interval held the truth in 90% to 98% of samples. Extrapolated to twice the sample, the values were within 3% of the truth on average, but where rare clonotypes abound only the Simpson diversity's intervals held the truth as often as they say. ClonoLoom therefore compares samples first at levels every sample reaches by rarefaction alone (the lowest coverage among them, or the smallest sample's size), and offers iNEXT's extrapolated levels second, with a warning.
Gene usage and junctions
Each sample's V, D, J and C genes and families, V–J pairs, junction lengths and their mean, and amino acids overall and at each IMGT position of the commonest lengths (Lefranc et al. 2003), by clonotypes or by abundance, with intervals from 200 bootstrap replicates of the clonotypes. A call tied between genes gives each an equal part. On 15 samples, all 8,277 shares equal an independent R implementation's to 10⁻¹²; against the simulator's truth, of 2,308 intervals, 97.4% to 100% held the expected shares.
Overlap
| Measure | Source | Checked against | Agreement |
|---|---|---|---|
| Shared clonotypes; Jaccard's and Sørensen–Dice's indices; the overlap coefficient | Jaccard 1912; Dice 1945 | immunarch and R on 69 pairs; scirpy 0.25.1 on four single-cell runs | to 10⁻⁹; the same shared clonotypes and Jaccard index |
| The same, rarefied exactly to the smallest sample | Chao et al. 2014's subsample expectations | R by lchoose; 200,000 random subsamples | to 10⁻⁹; their mean |
| Morisita's index; the Morisita–Horn index | Morisita 1959; Horn 1966 | vegan 2.7.6 and immunarch | to 10⁻⁹ (vegan stops Morisita's at 1) |
| Intervals: the samples' cells resampled, widened for the chance of sharing | Horvitz and Thompson 1952 | Five simulated studies, 330 pairs | held the expected shared clonotypes in 95.2% of pairs, the rarefied ones in 97.0% |
Morisita's own index is shown first: the Morisita–Horn index, which immunarch and vegan give, reads two samples of one repertoire about 0.98 when they are shallow, and its intervals held the simulated repertoires' overlap in 85.8% of pairs, against 93.9% for Morisita's. A bootstrap of the cells alone held the shared clonotypes in only 64% of pairs: which clonotypes two samples share is itself random, and the intervals now include that.
Tracking
| Measure | Source | Checked against | Agreement |
|---|---|---|---|
| Time points read as days from a subject's reference event; each subject's samples ordered, its reference samples and replicates found | AIRR Repertoire metadata; the forms studies write | Every simulated series, read back as made | every sample placed at its day, with its reference and replicates |
| A clonotype's frequency at a time point (the samples taken at one time pooled), with Wilson's score interval | Wilson 1927 | R's prop.test without continuity correction | to 10⁻¹⁴ |
| The intervals against the truth | Wilson 1927 | The simulated CAR-T study, 2,700 frequencies in blood samples | held the true frequency in 95.2% where samples differ by sampling alone |
Wilson's interval is for sampling alone. When each clone's frequency in each blood sample also varies around its expectation, as in the simulated CAR-T study (by a factor of mean 1 and variance 0.1), the same intervals held the true frequency in only 76.9% of cases. The view and the methods paragraph say so; replicate samples, taken at one time, measure that variance.
Expanded and contracted clonotypes
| Method | Source | Checked against | Agreement |
|---|---|---|---|
| The binomial test of a clonotype's count at the first time point given its total, at the share of the depth; two-sided and one-sided | Rytlewski et al. 2019 | R's binom.test on 215 cases, from a clonotype absent at one time to thousands in samples of a million | to 4 × 10⁻¹² |
| Fisher's exact test of the 2 × 2 table; two-sided and one-sided | DeWitt et al. 2015 | R's fisher.test on the same cases | to 4 × 10⁻¹² |
| The beta-binomial test with the scale v(n) = 2 + (b ln n + a)²; two-sided and one-sided | Rytlewski et al. 2019 | An independent R implementation on 150 cases | to 2 × 10⁻¹² |
| Its variance fitted by maximum likelihood (Nelder–Mead from (1, 1), restarted) | Rytlewski et al. 2019 | R's optim (Nelder–Mead, then BFGS) on two sets of 3,000 clonotypes drawn from the model | the same likelihood to 10⁻⁶, the same scale to 10⁻³ |
| Benjamini and Hochberg's adjusted p-values; Storey's q-values at λ = 0.5 | Benjamini and Hochberg 1995; Storey 2002 | R's p.adjust; Storey's π₀ and q-values computed in R | to 10⁻⁹; π₀ equal |
| False discoveries where nothing changes | A simulated series, four subjects, day 0 against day 14, two samples each | none of 6,634 clonotypes called where samples differ by sampling alone | |
| Calls where clonotypes change | The simulated CAR-T study, the week before the infusion against two weeks after | all 66 calls in the true direction where samples differ by sampling alone |
The binomial and Fisher's tests account for sampling alone. When each clone's frequency in each blood sample also varies around its expectation (by a factor of mean 1 and variance 0.1), they called 13 of 6,599 clonotypes on the series where nothing changes (0.2%, as Rytlewski et al. found between blood samples two weeks apart), and 6 of the binomial test's 73 calls on the CAR-T study were against the truth (8%, against the 1% asked for). The beta-binomial test, its variance fitted on the replicate samples, called none on the series, and none of its 20 calls on the CAR-T study was against the truth. Between the replicate samples themselves, a test at 0.05 called 8.2% of the clonotypes changed by sampling alone, and 2.7% with the fitted variance.
Classes and attribution
| Measure | Source | Checked against | Agreement |
|---|---|---|---|
| Each clonotype classed emerging, transient, contracting or persistent by its calls against a base time point | The beta-binomial test (Rytlewski et al. 2019) | The simulated CAR-T study, with its variation between blood samples, against the week before the infusion | all 20 clonotypes classed by their calls classed the way the truth's frequencies moved |
| A sample's share in its reference sample's clonotypes, with Wilson's interval | Wilson 1927 | The simulated CAR-T and transplant studies: the share the truth expects in the clonotypes the reference sample holds | within 0.023 at every sample |
| The share derived from a donor, among the clonotypes found on one side only | The simulated transplant study: the donor's true share of each recipient's blood | within 0.065 at every sample (60% to 97%) |
The share in the reference's clonotypes ran 0.17 (CAR-T) to 0.28 (transplant) below the share in all the reference population's clonotypes, which the reference sample misses some of; its interval, for sampling alone, held the truth it estimates in about half the samples. Where the reference was made from the subject's own blood (an infusion product), about 60% of the blood was in its clonotypes before the infusion, and three quarters of its cells were in clonotypes found before it: no measure by clonotype tells the infused cells from the patient's own, and the share derived from it is not given.
Similar receptors
| Measure | Source | Checked against | Agreement |
|---|---|---|---|
| TCRdist between two T-cell receptors, α, β and paired, with the V genes' CDR1, CDR2 and CDR2.5, and each loop's alone | Dash et al. 2017, as tcrdist3 computes it (Mayer-Blackwell et al. 2021) | tcrdist3 0.3 on Dash et al.'s 1,924 mouse and 415 human clones, every pair (3.87 million) | every distance equal |
| Each clonotype's neighbors within a radius and its nearest, found in parallel with a lower bound that skips far pairs | Every distance, on the same clones, at radii 0, 24, 48 and 96 | every neighborhood equal | |
| Specificity database chain matches and epitope shares | Shugay et al. 2018; Dash et al. 2017 | pandas exact lookups and simulated vaccine truth; real VDJdb data used only locally | 424 simulated and 4,000 real lookups; 150 sample/epitope shares equal |
| Clonotype networks: complete connected-component partitions under identity, Hamming, Levenshtein and TCRdist | Levenshtein 1966; Dash et al. 2017 | scirpy 0.25.1 on eight 10x runs and three OTS units; matched gene resolution and gap cost | all 420 partitions equal |
| A receptor's neighborhood against a background: its radius, the receptors within it, and their enrichment (rates, odds ratio, χ² with Yates's correction) | Mayer-Blackwell et al. 2021 | tcrdist3 0.3's bkgd_cntl_nn2 on Dash et al.'s 415 human β chains against 5,204 OTS β chains with weights | every centroid equal |
| The neighborhoods of receptors whose specificity is known | The simulated vaccination study: a vaccinated subject's day-14 sample, and one given the placebo | the 20 most enriched, and all 149 receptors in them, recognize an epitope; none in the placebo |
Where tcrdist3 and Dash et al.'s description differ, ClonoLoom does as tcrdist3 does: the CDR3's gap placed where it costs least, 12 for each residue of difference in length, and the gap character of the V genes' aligned loops costing nothing against a residue. The loops are tcrdist3's database of genes (made from IMGT's germline genes), downloaded on request and named by its checksum in every result. The neighbors of 100,000 paired TCRs (real α and β chains of three OTS donors, paired at random) are found in 25 seconds on 10 processors, within 0.1 GB.
A centroid's radius is the largest of 0, 2, …, 48 TCRdist units at which the weighted background within it is at most a share of the background's receptors (10−6 by default, Mayer-Blackwell et al.'s; tcrdist3's own default is 10−5), and the dataset's receptors within it are its neighborhood. The backgrounds are ClonoLoom's own: receptors drawn from a recombination model with the dataset's V–J usage, each weighted by the model's probability of its pair over the dataset's share of it, so that the weighted background is the repertoire recombination alone makes; or the dataset's own chains with their CDR3s moved among its genes. Because a radius is chosen to leave almost no background within it, a neighborhood's size is the signal, not its radius; enriched neighborhoods are ordered by descending χ², with depleted ones after them. Ten thousand receptors against a background of 100,000 take 1.3 seconds on ten processors.
Generation probabilities
| Measure | Source | Checked against | Agreement |
|---|---|---|---|
| The generation probability of an amino-acid or nucleotide CDR3, alone or with its V and J genes, under a V(D)J recombination model | Sethna et al. 2019 (OLGA), on IGoR's models (Marcou et al. 2018) | OLGA 1.3.0 under its seven default models: 99,949 CDR3s of the development data, drawn from each model, as nucleotides, with their genes, and with residues of any amino acid | within a relative 3 × 10−15 |
| The same, under ClonoLoom's own model of human TRB | The simulator: how often 200 junctions are made in 20 million rearrangements | mean squared z 0.96 | |
| Receptors drawn from a model | The probabilities, under ClonoLoom's model and OLGA's human TRB model | mean squared z 1.08 and 0.89 |
ClonoLoom computes a CDR3's probability as OLGA does, summed over every gene choice, deletion, palindrome and insertion by dynamic programming over its codons, and with OLGA's choices: every insertion length the model allows, a palindrome made from the gene's part of the CDR3, and only the genes OLGA's anchor files mark functional. OLGA leaves out an insertion of the longest length a model allows when that length is one more than a multiple of three and the insertion starts a codon, which its own generator makes; ClonoLoom counts them, and is checked against OLGA on a copy of each such model that allows one nucleotide more with probability 10−30. Of the seven models, only mouse TRA's probabilities change by it by more than 10−15: by up to 13% among the 5,583 mouse TRA CDR3s compared. A million TRB CDR3s' probabilities take 32 seconds on 10 processors.
Simulated studies
clonoloom simulate makes TRB rearrangements from GRCh38's gene segments at Ensembl's annotation (Dyer et al. 2025), with V and J usage from 10x Genomics' 10k PBMC data, deletions, palindromic and non-templated insertions (Murugan et al. 2012), and productive junctions selected on their length (Elhanati et al. 2014); each subject's repertoire a population of power-law clone sizes, sampled into templates and reads. Over 150,000 rearrangements, the productive junctions' mean length is within 0.1 amino acids of the 10x data's, its standard deviation within 0.15, and V usage within 0.03 of the model's in total variation. The same seed gives the same bytes on every computer.
The vaccination study's receptors that recognize an epitope are families around founders the subjects share, each member the founder's genes and deletions with other non-templated nucleotides, and receptors of each subject's own. Their nearest receptors of the same epitope are as near as in Dash et al. 2017's epitope-specific β chains: 58%, 63% and 68% within 12, 24 and 48 TCRdist units, against 54–61%, 59–71% and 69–85% in Dash et al.'s human and mouse chains. Their share of each sample is within a quarter of the truth's at every time point.
Figures, exports and the record
The 0.8.0 worked study preserves original query JSON across HTTP, MCP, Python and R, restores checkpoint evidence and transfers a portable archive with its original source paths unavailable. These checks measure transport and recovery fidelity. Certificate integrity checks saved bytes; native replay recomputes captured batch-QC, motif and cohort evidence exactly. Neither establishes authorship or validates experimental assumptions. Headless source computation remains limited to batch QC and motifs; unsupported replay kinds report unavailable. The certificate guide states the per-kind input boundary.
Figures are written as SVG, as PNG at 300 dpi (the resolution recorded in the file) and as PDF; the PDF's structure, page size and image are checked by tests. An exported AIRR Rearrangement TSV, read back by ClonoLoom's own reader, gives the same clonotypes with the same abundances. Each release saves a project with its data and results, and every later release must open it under the same dataset and result IDs and make each result again: the 0.2.0 project's five results are made again with the same values. Results are the same, bit for bit, on every processor: ClonoLoom computes its own logarithms, exponentials, powers and log-gamma (fdlibm's, as SituCraft's), rounds every product on its own so that no processor fuses it with an addition, and a test searches the compiler's arm64 output for fused multiply-adds; every analysis's results, and a simulated study, are pinned by digests that arm64 and amd64 builds both give.
Cite ClonoLoom
If you use ClonoLoom in your research, please cite it (the repository's CITATION.cff) with its version, and the methods you used as its methods paragraph lists them:
McDermott R. ClonoLoom: a local-first workbench for adaptive immune receptor repertoires. Version 0.9.0. https://github.com/robert-mcdermott/clonoloomB-cell evidence, families and lineages
The artificial immunization study supplies known generating families, ancestors, mutation events and isotype labels. Independent checks read its truth and source files directly; they do not call the analysis implementation. These checks validate the stated computations on known artificial inputs, not biological sensitivity, an optimal family threshold or switching-event inference.
| Result | Method and ClonoLoom choices | Independent check |
|---|---|---|
| Sequence evidence | AIRR coordinates and IMGT native annotations retained separately; missing and invalid evidence remain explicit | Independent CSV reading of all 42 retained AIRR fields on four public B-cell datasets; synthetic IMGT identity joins, coordinate mappings and AIRR round trips |
| Families | Normalized nucleotide Hamming distance, V/J/length partitions and single linkage (Gupta et al. 2017). Subject boundaries, paired maximum distance and conservative eligibility are ClonoLoom choices | Every nearest distance and membership against independent graph calculations at four thresholds in heavy and paired modes; all 36 known families recovered at demonstration threshold 0.1 |
| Germlines | D/N/P masking follows the Change-O framework (Gupta et al. 2015); explicit common V/J allele intersection and checked AIRR CIGAR projection are ClonoLoom choices | Known reference projection and masking, coordinate orientation, gaps and ambiguity; 4,320 reconstructed rows in 72 family/locus groups |
| SHM | Query/reference differences under explicit evaluability rules, AIRR regions and NCBI genetic code table 1; single-hit replacement/silent substitutions separate from multi-hit endpoints | All 4,320 rows and 43,200 row/region records against independently read ancestors; 327 evaluable bases and 109 codons per default artificial row |
| Lineages | Equal-cost parsimony (Fitch 1971), conditional ancestral states (Sankoff 1975); ClonoLoom shared panels, deterministic tie handling and bounded exact/heuristic search | Independent exhaustive search for all 72 artificial family/locus trees: 1,093 changes and every optimal-topology count; 71 trees have ties |
| Isotypes | ClonoLoom descriptive counting and ambiguity policies using AIRR/IMGT constant calls; observed traits kept separate from phylogenetic inference (Hoehn et al. 2022) | Independent direct tallies for 2,160 cells, 36 families and 466 usage rows; all three unordered IGHM/IGHG1/IGHA1 pairs in every family |
Public Ramos and 10x PBMC B-cell inputs test evidence coverage and explicit exclusions, not known biological ancestry. Each result pins its source and parent identities. A saved 0.5.0 project with paired AIRR and joined IMGT inputs reproduces all seven result documents byte for byte on arm64 and amd64, alongside the earlier release fixtures. Human OGRDB IGH v10, IGK v5 and IGL v4 germlines are available as checksum-pinned CC0 downloads; the artificial study uses its own fictional reference.
Exact lineage search covers at most eight distinct states including the reference; the bounded 9–64-state heuristic does not certify a global optimum. Conditional ancestral states are not probabilities. Mutation frequencies are net differences, not historical rates or selection tests. Isotype pairs do not establish switching events, timing, direction, ancestral traits or rates. The linked method guides and each result's methods paragraph state these limits.
References
- Gupta NT, Vander Heiden JA, Uduman M, et al. Change-O: a toolkit for analyzing large-scale B cell immunoglobulin repertoire sequencing data. Bioinformatics 2015;31:3356–3358. doi:10.1093/bioinformatics/btv359.
- Gupta NT, Adams KD, Briggs AW, et al. Hierarchical Clustering Can Identify B Cell Clones with High Confidence in Ig Repertoire Sequencing Data. J Immunol 2017;198:2489–2499. doi:10.4049/jimmunol.1601850.
- Fitch WM. Toward Defining the Course of Evolution: Minimum Change for a Specific Tree Topology. Syst Zool 1971;20:406–416. doi:10.1093/sysbio/20.4.406.
- Sankoff D. Minimal Mutation Trees of Sequences. SIAM J Appl Math 1975;28:35–42. doi:10.1137/0128004.
- Hoehn KB, Pybus OG, Kleinstein SH. Phylogenetic analysis of migration, differentiation, and class switching in B cells. PLoS Comput Biol 2022;18:e1009885. doi:10.1371/journal.pcbi.1009885.
- Benjamini Y, Hochberg Y. Controlling the false discovery rate: a practical and powerful approach to multiple testing. J R Stat Soc B 1995;57:289–300.
- Chao A. Nonparametric estimation of the number of classes in a population. Scand J Stat 1984;11:265–270.
- Chao A, Gotelli NJ, Hsieh TC, et al. Rarefaction and extrapolation with Hill numbers: a framework for sampling and estimation in species diversity studies. Ecol Monogr 2014;84:45–67.
- Chao A, Jost L. Coverage-based rarefaction and extrapolation: standardizing samples by completeness rather than size. Ecology 2012;93:2533–2547.
- Chao A, Lee SM. Estimating the number of classes via sample coverage. J Am Stat Assoc 1992;87:210–217.
- Chao A, Wang YT, Jost L. Entropy and the species accumulation curve: a novel entropy estimator via discovery rates of new species. Methods Ecol Evol 2013;4:1091–1100.
- DeWitt WS, Emerson RO, Lindau P, et al. Dynamics of the cytotoxic T cell response to a model of acute viral infection. J Virol 2015;89:4517–4526.
- Dice LR. Measures of the amount of ecologic association between species. Ecology 1945;26:297–302.
- Dash P, Fiore-Gartland AJ, Hertz T, et al. Quantifiable predictive features define epitope-specific T cell receptor repertoires. Nature 2017;547:89–93.
- Dyer SC, Austine-Orimoloye O, Azov AG, et al. Ensembl 2025. Nucleic Acids Res 2025;53:D948–D957.
- Elhanati Y, Murugan A, Callan CG Jr, Mora T, Walczak AM. Quantifying selection in immune receptor repertoires. Proc Natl Acad Sci USA 2014;111:9875–9880.
- Emerson RO, DeWitt WS, Vignali M, et al. Immunosequencing identifies signatures of cytomegalovirus exposure history and HLA-mediated effects on the T cell repertoire. Nat Genet 2017;49:659–665.
- Hill MO. Diversity and evenness: a unifying notation and its consequences. Ecology 1973;54:427–432.
- Horn HS. Measurement of "overlap" in comparative ecological studies. Am Nat 1966;100:419–424.
- Horvitz DG, Thompson DJ. A generalization of sampling without replacement from a finite universe. J Am Stat Assoc 1952;47:663–685.
- Hsieh TC, Ma KH, Chao A. iNEXT: an R package for rarefaction and extrapolation of species diversity (Hill numbers). Methods Ecol Evol 2016;7:1451–1456.
- Jaccard P. The distribution of the flora in the alpine zone. New Phytol 1912;11:37–50.
- Lefranc MP. Immunoglobulin and T cell receptor genes: IMGT and the birth and rise of immunoinformatics. Front Immunol 2014;5:22.
- Lefranc MP, Pommié C, Ruiz M, et al. IMGT unique numbering for immunoglobulin and T cell receptor variable domains and Ig superfamily V-like domains. Dev Comp Immunol 2003;27:55–77.
- Marcou Q, Mora T, Walczak AM. High-throughput immune repertoire analysis with IGoR. Nat Commun 2018;9:561.
- Mayer-Blackwell K, Schattgen S, Cohen-Lavi L, et al. TCR meta-clonotypes for biomarker discovery with tcrdist3 enabled identification of public, HLA-restricted clusters of SARS-CoV-2 TCRs. eLife 2021;10:e68605.
- Morisita M. Measuring of interspecific association and similarity between communities. Mem Fac Sci Kyushu Univ Ser E Biol 1959;3:65–80.
- Murugan A, Mora T, Walczak AM, Callan CG Jr. Statistical inference of the generation probability of T-cell receptors from sequence repertoires. Proc Natl Acad Sci USA 2012;109:16161–16166.
- Olsen TH, Boyles F, Deane CM. Observed Antibody Space: a diverse database of cleaned, annotated, and translated unpaired and paired antibody sequences. Protein Sci 2022;31:141–146.
- Raybould MIJ, Greenshields-Watson A, Agarwal P, et al. The Observed T cell receptor Space database enables paired-chain repertoire mining, coherence analysis, and language modeling. Cell Rep 2024;43:114704.
- Rubelt F, Busse CE, Bukhari SAC, et al. Adaptive Immune Receptor Repertoire Community recommendations for sharing immune-repertoire sequencing data. Nat Immunol 2017;18:1274–1278.
- Rytlewski J, Deng S, Xie T, et al. Model to improve specificity for identification of clinically-relevant expanded T cells in peripheral blood. PLoS One 2019;14:e0213684.
- Seal RL, Braschi B, Gray K, et al. Genenames.org: the HGNC resources in 2023. Nucleic Acids Res 2023;51:D1003–D1009.
- Sethna Z, Elhanati Y, Callan CG Jr, Walczak AM, Mora T. OLGA: fast computation of generation probabilities of B- and T-cell receptor amino acid sequences and motifs. Bioinformatics 2019;35:2974–2981.
- Storey JD. A direct approach to false discovery rates. J R Stat Soc B 2002;64:479–498.
- Sturm G, Szabo T, Fotakis G, et al. Scirpy: a Scanpy extension for analyzing single-cell T-cell receptor-sequencing data. Bioinformatics 2020;36:4817–4818.
- Vander Heiden JA, Marquez S, Marthandan N, et al. AIRR Community standardized representations for annotated immune repertoires. Front Immunol 2018;9:2206.
- Wilson EB. Probable inference, the law of succession, and statistical inference. J Am Stat Assoc 1927;22:209–212.
Credits
The public example datasets are 10x Genomics' single-cell V(D)J runs, the AIRR Community's test files and a healthy donor's paired TCRs from the Observed T cell receptor Space, each used under the Creative Commons Attribution 4.0 license; Dash et al. (2017)'s epitope-specific TCRs as tcrdist3 distributes them, under the MIT license; and three subjects of Emerson et al. (2017) from immuneACCESS, downloaded only by a user who accepts their terms of use. Their source and license are shown on each example's card and cited in the methods paragraph. The TRB simulator's gene segments are GRCh38's at Ensembl (no restrictions), and its V and J usage and junction lengths are computed from 10x Genomics' 10k PBMC data (CC BY 4.0). The artificial B-cell simulator instead uses fictional SIM genes and regions, with no data-use restrictions. The website, its build and parts of ClonoLoom's host and library are adapted from SituCraft and MaveScape, by the same author, under the Apache License 2.0.
ClonoLoom is for research use only. It is not a medical device and makes no diagnostic claims.
Single-cell expression and receptor links
ClonoLoom 0.6.0 keeps expression matrices separate from receptor data and joins exact barcodes within an explicitly selected sample. Independent SciPy, h5py, AnnData, MuData and Awkward fixtures check raw counts, sparse structure, annotations, missingness and modality-local identities. The artificial paired cell-state model has separate truth, deliberate unmatched observations and a measured zero-count cell; supplied Gaussian coordinates are illustrations, not inferred embeddings.
Computed maps use all-gene count normalization, log1p, variance-ranked features, centered unscaled PCA, exact Euclidean neighbors and seeded UMAP. Independent numerical references check feature moments, PCA, neighbors and fuzzy-graph weights; known-state recovery and map-quality checks supplement deterministic result hashes. Expression methods distinguishes published methods from ClonoLoom's feature-selection and initialization choices.
Phenotype summaries count distinct cells under recorded sample, definition and QC rules, with denominators checked by independent SQL tabulations. Clonotype modularity uses a binary induced expression graph and uniform size-matched null, with exhaustive or seeded Monte Carlo tails and Benjamini–Yekutieli correction. Paired receptor/expression comparisons use mean PCs, TCRdist, shared-chain exclusions and inclusive cutoff ties, with conditional hypergeometric tails and all-scale Bonferroni adjustment. SciPy references and exhaustive small controls check those calculations. Modularity and CoNGA-style comparisons record population and null assumptions; these tests do not remove cell-state confounding, prove antigen specificity or make cells biological replicates.
AnnData 0.12.6 and h5py 3.15.1 independently read and rewrite the export, checking integer precision, every sparse count, Unicode, missing labels and coordinate alignment. The complete study retains 360 input cells in its export, including the cell excluded from its computed map. Its 0.6.0 project fixture replays all five results and the AnnData binary with recorded source and parent provenance, alongside the unchanged earlier release fixtures.