Key ideas
Five ideas are enough to read every page of these docs.
A probability for every sequence
Section titled “A probability for every sequence”A BEAM model is a probability distribution over sequences, of amino acids or of nucleotides. It gives every possible sequence a probability: for the reference model of TCRβ CDR3s, the chance that one T cell drawn at random from the population has exactly that CDR3. Summed over all possible sequences, these probabilities add up to one.
That is a very large space. The reference model, of human TCRβ CDR3 amino-acid sequences, covers sequences of up to 27 residues, the longest in its corpus, and every string of 1 to 27 of the 20 standard amino acids is a possible sequence: about 1.4 × 10³⁵ of them, 95% of them of length 27 alone (20²⁷ ≈ 1.3 × 10³⁵). Every one has a probability, including the vast majority that no one has observed, and BEAM’s sums run over all of them, by dynamic programming rather than by listing them. Building a model from more sequences does not add or remove possibilities: it moves probability within this space, towards the patterns the sequences show.
A model is built from a repertoire, or from many, by counting short stretches of sequence. It reads every residue twice: once by its position counted from the start of the sequence, and once counted from the end. The two readings are combined, which captures the conserved start (CASS…) and end (…YEQYF) of a CDR3 as well as what lies between.
A model also gives a sensible probability to sequences it has never seen. A plausible new CDR3 gets a moderate probability; a string that looks nothing like a CDR3 gets a vanishingly small one.
Reading a sequence from both ends
Loading…
Each residue is scored twice: by the reading from the start (teal) and by the reading from the end (orange). The bars show how unexpected the residue was to each; press Play to read the sequence one residue at a time.
More: how the two readings become one probability →
Computed, not simulated
Section titled “Computed, not simulated”Many questions about a repertoire are sums over every possible sequence: how many distinct sequences will 100,000 cells contain? There are far too many sequences to list, so the usual answer is simulation: draw many samples and count, and accept some random error.
BEAM is built so that these sums can be computed directly, over every combinatorially possible sequence, without listing or sampling them. Where a sum is evaluated numerically, the answer carries a guaranteed bound on its error: BEAM aims for one part in 10¹⁰ by default, and in the examples on this site the bounds are between 10⁻¹³ and 2 × 10⁻¹². The same question always gives the same answer, so differences between groups are not hidden by simulation noise.
Simulated, or computed once
Loading…
How many distinct sequences do 100,000 cells from the reference population contain? Each dot is one simulation: 100,000 cells drawn from the model and counted. The teal line is BEAM's expected count and the shaded band how far one sample's count varies around it (one and two standard deviations), both computed once. Run the simulations and watch them land in the band and their mean settle on the line.
BEAM computes both the expected count, 96,771.4, and how much the count of one sample varies
around it: a standard deviation of 60.5 (richness_sd). Their guaranteed relative errors are below
4.6 × 10⁻¹³ and 2.4 × 10⁻¹¹. Of the 100 simulations, 94 fell within two standard deviations of the
expected count, about the 95 one would expect, and their mean, 96,769 ± 14 (two standard
errors), agrees with it.
More: what the error bounds mean →
Depth: how many cells you sample
Section titled “Depth: how many cells you sample”The depth of a sample is the number of T cells (or receptor molecules) drawn from the population. Because common sequences are drawn many times, a sample of depth 100,000 contains fewer than 100,000 distinct sequences.
BEAM’s sampling calculations treat a sample as independent draws from the model’s distribution. That is the right baseline for “what would I expect by chance”, but it does not model clonal expansion within one person. Keep that in mind when comparing predictions with a real repertoire.
Depth and distinct sequences
Drag the slider to change the number of cells sampled. Teal: the expected number of distinct sequences. Orange: how many of them a second sample of the same depth would also contain. The dashed line is where every cell would carry a new sequence.
More: planning sequencing depth →
Publicness
Section titled “Publicness”A sequence is public when many people carry it. Given a cohort, described by how deeply each person’s repertoire was sampled, BEAM gives the expected number of people whose sample contains a sequence, and the full distribution of that number.
How many people carry a sequence
Loading…
Choose a cohort size, a sampling depth and a sequence, or set any probability with the slider. The bars show the probability that each number of people carries the sequence.
More: publicness of sequences and cohorts →
The reference model and your own models
Section titled “The reference model and your own models”The reference model (BEAM.load_pretrained("human_tcrb_cdr3_aa_foundation")) was built from 38,538 published
human TCRβ repertoires. It describes this broad, aggregated population, which makes it the
natural reference for “how likely is this sequence in people in general”.
You can also build a model from a single repertoire, which then describes that person or sample, or from a group of repertoires, such as one cell type or one patient cohort. See Which model do I need?, and for whether to weight by abundance, Abundance or unique sequences?
Describes one sample or one person. Compare samples, follow a person over time, plan the depth for this sample.
Describes a cell type, a condition or a cohort. Compare groups, ask which group a sequence resembles, predict sharing within the group.
Generalises over all the data given, like the reference model built from 38,538 repertoires. The baseline for "how likely in people in general".
Where next
Section titled “Where next”- How likely is a sequence?: scoring, and what makes a score high or low.
- Building a model from your data: models of your own repertoires.
- How deeply should I sequence?: sampling calculations without simulation.
- What can I do with BEAM?: every question, with where it is answered.
- How BEAM works: the model behind the numbers.