Simulated studies

ClonoLoom makes bulk T-cell receptor β and artificial paired B-cell studies whose truth is known: every clonotype of every subject, and the numbers an analysis estimates. They are for checking methods, ClonoLoom's or anyone's, against the truth, and for learning ClonoLoom without data of your own.

Make one

The Example data dialog offers six studies, made on your computer in a few seconds (offline too), each labeled simulated wherever it is shown. From the terminal:

$ clonoloom simulate                                # the standard study, into clonoloom-simulated-standard
$ clonoloom simulate --preset null --seed 7         # another study, another seed
$ clonoloom simulate --print-params > study.json   # the parameters, to edit
$ clonoloom simulate --params study.json --out my-study

The same parameters and seed give the same study, byte for byte, on every computer. Open its folder in ClonoLoom as one dataset: its truth folder, and the vaccination study's database folder, are left out.

Presets

A complete artificial immunization workflow

In Example data, generate An artificial B-cell immunization study with known families and open the study. It works offline. Open Tracking for its Guided steps panel. Select Do it for each step, returning to Tracking to choose the next after inspecting a B-cell result, or use the controls below. From a terminal, make the same default study with clonoloom simulate --preset bcell-immunization (seed 20261027).

1. Subjects. Check three subjects and nine samples, at days -7, 14 and 28. Each sample has 240 cells, represented by 480 heavy/light sequence rows. Cells and sequence rows are different units.
2. Inputs. Inspect a row's query, known rearranged ancestor and artificial regions. The fictional SIM genes are not human reference alleles. Structural validity does not establish the accuracy of biological annotations.
3. Families: distances first. Run without a threshold to see nearest distinct-receptor distances within subject and V/J/length partitions. This saves diagnostics without assigning families. Missing neighbors are not zero distances.
4. Families: explicit threshold. Run at 0.1 to recover all 36 known generating families. Paired distance is the larger heavy/light distance; single linkage can connect endpoints farther apart than the threshold. This demonstration threshold is not a recommendation for biological samples.
5. Germlines. Select the saved families and artificial immunization reference. All 4,320 chain rows reconstruct in 72 family/locus groups. The D/N/P interval, including the light-chain junction, is masked: this projection is not the simulator's complete ancestor.
6. SHM. Select that germline result. Every row has 327 evaluable V/J bases and 109 codons. Inspect regional denominators, single-hit replacement/silent counts and separate multi-hit codon endpoints. Net differences do not recover historical mutation events or demonstrate selection.
7. Lineages. Build 72 separate family/locus trees on shared V/J panels. Select nodes to inspect source rows and conditional ancestral states. The default study gives 1,093 changes; 71 trees have multiple optimal topologies. Timepoint, tissue and isotype are observed annotations, not inferred ancestry or trait transitions.
8. Isotypes. Select the thresholded families and summarize 2,160 cells. Inspect class and constant-gene usage, then the families supporting a pair. Each unordered IGHM/IGHG1/IGHA1 pair occurs in all 36 families. These counts do not infer switching events, direction, timing or rates.
9. Methods and exports. Open Methods for the saved parameters, reference hashes, limits and numbered citations. Each result view offers Export result, with complete CSV/JSON tables, manifest and notice; germlines and lineages also include FASTA, and lineages Newick. Exported rows are not limited by the displayed page.

The project saves automatically to the library; keep its source files available. Saved results retain their parent checksums and the annotations used at computation; changing a label or threshold produces a new result. Reopen a saved result from the project tree to inspect its original choices. The record explains projects and provenance.

The model clonoloom-artificial-bcell-v2 supplies known ancestors, substitutions, family assignments, sampling probabilities and isotype histories under truth/, and V/J FASTA under reference/. Analyses use observations and reference sequences, not truth labels. Back-mutations and unsampled states make observed trees different from complete generating histories. The model is a software validation fixture, not a biological SHM-rate or affinity model; see its documented construction.

Studies over time

The car-t, transplant and null-series presets sample each subject at several time points, in days from its reference event, and the Example data dialog offers the first two. Between time points, classes of clones follow known trajectories: in the CAR-T study, 2% of the product's clones expand after the infusion and 20% contract. A reference population is mixed into the blood in a known share at each time point: an infusion product, made from cells collected from the subject's own blood and expanded ex vivo, or a donor's repertoire. It is sampled once as the subject's reference sample, whose tissue (infusion product, donor blood) marks it as the reference in the Tracking view. Every sample, replicates at one time included, draws each clone around its expected frequency with biological variance, so that two samples of one subject differ by more than sampling, as blood samples do; the replicates measure it.

The truth adds each sample's day, the reference's expected share of its cells, and the expected share of its cells in the reference's clonotypes. Because a product is made from the subject's own cells, about three quarters of the blood is in its clonotypes even before the infusion. For each subject, a file gives every clonotype's trajectory and expected frequency at each time point.

Receptors of known specificity

The vaccine preset adds an antigen-specific response to a study over time: receptors that recognize three epitopes of a vaccine (peptides made up for it). Each epitope has founders, rearrangements the subjects share as public receptors do; each subject holds a family of each founder, receptors of the founder's genes and deletions whose non-templated nucleotides differ, so that their CDR3s differ by a residue or two, mostly ones alike; and receptors of its own, unlike any other. Pooled across subjects, 58% of these receptors have another of the same epitope within 12 TCRdist units and 63% within 24, as Dash et al. 2017 found in mice and people (54–61% and 59–71%). They are 0.1% of the blood before the vaccination, rise to 3% at day 14 in the vaccinated and fall back, and stay at 0.1% in the placebo group.

The truth gives every subject's receptors that recognize an epitope, with the epitope and founder (any other clonotype recognizes none), and each subject's expected share in them at each time point. Beside the samples, database/vdjdb.txt is a specificity database in VDJdb's format: each epitope's founders and receptors of other donors around them, with two epitopes no subject responds to.

The TRB truth

Beside the samples (AIRR rearrangement tables, templates as umi_count and reads as duplicate_count, with their Repertoire metadata), the truth folder holds every clone of every subject's population, and for each population its clonotypes, Hill numbers, Shannon and Simpson indices, evenness, clonality, Gini, largest clones' share and homeostasis; for each sample, the clonotypes and coverage a sample of its depth shows on average; and for each pair of subjects, the clonotypes they share. ClonoLoom's own interval coverage is measured against it (Science).

The TRB model

Rearrangements are made from GRCh38's TRB gene segments at Ensembl's annotation, with the V and J usage of 10x Genomics' 10k PBMC data, deletions, palindromic and non-templated insertions, and productive junctions selected on their length so that their lengths are the data's. Each subject's clones have power-law sizes; each sample draws templates from them and sequences them into reads. It is a simple, documented model for testing methods against a known truth, not a model inferred from data: its junctions look like real ones, but they are not a substitute for real repertoires. SIMULATION.md gives every file, field and parameter. Simulated data describe no person, and may be used and shared without restriction.

Work through the specificity examples

Generate A simulated vaccination study with known specificities in Examples. Its six steps show subjects, test the week before against day 14, class transient clonotypes, follow them, match the generated database by exact CDR3 and V/J, then follow a matched vaccine epitope. The database is intentionally incomplete: the matching receptors represent only part of the simulated response, and some chance matches remain.

The Epitope-specific TCRs of Dash et al. 2017 example has two steps for each of its mouse and human openings: compare paired CDR3s at TCRdist 24 and connect all-chain matches into a network. Samples retain the known tetramer epitope and donor. The steps explicitly compare CDR3s alone, so they need no separate reference download. To include V-gene loops, download them in Reference data and change the comparison. Connected components can span distant endpoints through intermediate receptors; inspect the epitope labels rather than treating a component as proof of shared specificity.

Paired receptors and expression

The A paired cell-state study with supplied Gaussian clouds example connects raw counts, imported coordinates, computed PCA/UMAP, clone sizes, phenotype summaries, graph tests and AnnData export. Follow the seven-step single-cell study for expected counts, interpretation and saved reopening. Its four samples deliberately repeat barcodes, so joins always select one receptor sample. Supplied clouds illustrate known states; computed maps fit counts independently. Fictional receptors and chosen expression distributions test the workflow, not antigen specificity or a fitted biological model.

Paired pseudobulk expression controls

Paired pseudobulk expression study and Null pseudobulk expression study each contain 28 artificial subjects, one baseline sample, uneven singleton/larger clone sizes, and 40 fictional genes. Gamma rates shared across each subject's cells produce pseudobulk variability. Four positive-control genes change in the first preset; the null preset has no generating category effect. Sparse, zero-gene and zero-subject controls remain explicit. Supplied Gaussian coordinates are illustrative, not embeddings. The paired expression guide explains the complete workflow and separate generating truth.