Abundance or unique sequences?

A repertoire is a list of distinct sequences, CDR3s for example, each carried by some number of cells (templates, UMIs, reads). When you build a model you choose how much each sequence counts, and that choice defines what the model describes.

BeamModel(sequences, abundances=counts)   # weighted: each CELL counts
BeamModel(sequences)                      # unique: each distinct SEQUENCE counts once

What each describes

Weighted by abundance, the model describes the cells: its probability for a sequence is the chance that a cell drawn at random carries it. Expanded clones count as many times as they have cells.

Unique sequences, the model describes the sequence composition of the repertoire: which CDR3s are present, regardless of how much each was expanded.

weighted_vs_unique.py

import numpy as np
import BEAM
from BEAM import BeamModel
# seqs: the distinct CDR3s of one repertoire; counts: how many cells carry each
by_cells = BeamModel(seqs, abundances=counts)    # each cell counts: describes the cells
by_sequence = BeamModel(seqs)                    # each distinct sequence counts once

top = seqs[int(np.argmax(counts))]
print(f"largest clone {top}: {max(counts) / sum(counts):.2%} of the cells")
print(f"P(largest clone)  weighted by cells: {by_cells.pseq(top):.2e}   "
      f"unique: {by_sequence.pseq(top):.2e}")
print(f"distinct sequences: {len(seqs):,}   cells: {sum(counts):,}")

Output

largest clone CATSDFRRGLAGGPYEQYF: 2.85% of the cells
P(largest clone)  weighted by cells: 3.42e-02   unique: 6.72e-12
distinct sequences: 48,964   cells: 2,347,888

Full program, including the set-up hidden here

The largest clone holds 2.9% of this stand-in repertoire’s cells (stand-in population A, with clonal expansion added), and the weighted model gives it a probability of 3.4%, close to that share. The two need not agree exactly: the model builds probabilities from overlapping stretches of sequence rather than storing each sequence’s frequency, which is also what lets it score sequences it has never seen. To the unique model it is one sequence among 48,964, and its probability, about $7 \times 10^{-12}$, reflects only its sequence.

Clonal expansion

Clonal expansion is a response to antigen: a few T cells divide and fill a large part of the repertoire. Whether it should influence the model depends on the question.

Clonal expansion and the two kinds of model

Loading…

Drag the slider to make the clones of one stand-in repertoire more expanded. The numbers show how much of the repertoire the largest clones take, the largest clone's probability under each model, and the distance between the weighted and the unique model. The chart shows each model's length distribution: the weighted model follows the expanded clones, the unique model does not move.

Two repertoires of the same population, one with expanded clones and one without, look very different weighted by cells and similar counted by unique sequences:

expansion_distance.py

from BEAM import BeamModel
from BEAM.analytics.distance import compare
# two repertoires of the same population (sequences s1, s2 and their clone sizes c1, c2):
# donor 1 has large expanded clones, donor 2 does not
weighted = compare(BeamModel(s1, abundances=c1, order=3),
                   BeamModel(s2, abundances=c2, order=3))
unique = compare(BeamModel(s1, order=3), BeamModel(s2, order=3))

print(f"distance, weighted by cells:          {weighted.distance:.4f}")
print(f"distance, each distinct sequence once: {unique.distance:.4f}")

Output

distance, weighted by cells:          0.5821
distance, each distinct sequence once: 0.1564

Full program, including the set-up hidden here

Weighted by cells, the expanded clones make the two stand-in repertoires almost four times as distant as when each distinct sequence counts once. The size of the effect depends on how strongly the clones are expanded; the explorer above shows the whole range. If the question is whether two people’s repertoires differ in composition, the weighted distance is mostly measuring expansion.

Benefits and drawbacks

	Weighted by abundance	Unique sequences
Describes	what the abundances count: cells (templates, UMIs) or reads	the sequence composition
Clonal expansion	dominates the model	no longer weighted, though it still takes up depth and decides which sequences were seen
Depends on depth	little: more cells sharpen the same distribution	strongly: deeper samples add rare, often longer, sequences, so compare at an equal number of distinct sequences
Differences in abundance units (templates, UMIs, reads) between platforms	carried into the model	removed
Sampling questions (depth, overlap, publicness)	in cells, as sequenced	in distinct sequences, not cells
Frequencies of individual sequences	kept	lost
Best for	how a sample of cells will look; expanded responses; the population as sampled	comparing repertoires’ composition across samples, studies and platforms

Use abundance weighting when the question is about cells: how many distinct sequences a sample of cells will contain, how many people will carry a sequence at a given sequencing depth, how an expanded response changes a repertoire. The reference model is weighted by template counts where the platform reported them, and counts each distinct sequence once per repertoire otherwise.

Use unique sequences when the question is about which sequences a repertoire contains, and compare repertoires at the same number of distinct sequences, as the paper did: comparing cell types, conditions or studies, especially across platforms whose abundance units differ, or when a few expanded clones would otherwise decide the comparison. The paper’s comparison of CD4 and CD8 repertoires across two independent studies counted each distinct sequence once for this reason.

Depth changes meaning

With unique sequences, a model’s “draws” are distinct sequences, not cells. Sampling calculations such as expected distinct sequences at a depth then answer questions about distinct sequences, and their depths must be counted the same way.