baSeq docs › scTCR-seq

scTCR-seq

An scTCR-seq analysis reads the genes of a cell and the T-cell receptor of that same cell, so a clone is not only a number but a set of cells whose state you can see.

Start an scTCR-seq analysis

In a project, click New session and choose scTCR-seq as the kind of analysis.

What to upload

Two libraries of the same cells: their gene expression, and their receptors.

The genes: anything the single-cell upload reads — Cell Ranger's filtered_feature_bc_matrix (folder or .h5), .h5ad, loom, a Seurat or SingleCellExperiment .rds, or a count table.
The receptors: Cell Ranger's filtered_contig_annotations.csv (or all_contig_annotations.csv), an AIRR rearrangement table with a cell_id column, or TRUST4, BD Rhapsody, Parse Evercode, WAT3R or MiXCR output.

Upload them together. Each receptor table is tied to the sample whose cell barcodes it shares, so the two libraries find each other whatever they are called; where two samples of one run hold the same barcodes, the file names decide. A table whose cells match no sample is set aside and the upload says so.

A table of clonotypes rather than cells (Cell Ranger's clonotypes.csv, or a bulk run's export) cannot be tied to cells: those belong in a TCR repertoire analysis.

What a clone is here

Two cells belong to one clone when they share an alpha and a beta chain — the same CDR3, V and J. Two things follow that a stricter rule gets wrong. A cell with two alpha chains (ordinary: the alpha locus does not shut the second allele down) belongs to both of its pairs, so a second chain missed in one cell does not split a clone in two. And a cell with only one chain, which is most often a cell whose other chain was not captured, joins the one clone that already holds that chain — but not when two clones hold it, because then nobody knows which.

A cell with two alpha and two beta chains is usually two cells in one droplet. Chain QC removes those, and they join nothing through their second pair.

By default two cells are one clone when their rearrangement is the same, down to the nucleotides, which is what descent from one T cell means. The same receptor protein is a different question — convergent recombination — and Define Clonotypes will answer that one instead if you ask it to.

Reading the receptor with the genes

This is what scTCR-seq is for, and three steps do it from three directions.

Clonal Expansion shows which states the expanded cells are in. An expanded clone is a T cell that has divided, so the states holding them are the states that responded.
Clones Across States uses a clone as a label no transcriptome can give: cells of one clone came from one T cell, so a clone found in two states is evidence that cells move between them.
Clone and State Together asks whether the receptor decides the state at all — whether a clone's cells sit together in gene expression, and whether cells with similar receptors are in similar states.

One thing is worth keeping in mind for all three: a clone that is larger in a tumour than in blood may have divided there or simply moved there, and cells alone cannot tell you which. The states its cells are in usually can.

Clones that see the same antigen

T cells that recognise one peptide-MHC often carry receptors that differ in a few residues, so Specificity Groups collects the clones within a TCRdist radius of each other. How far apart two receptors may be is not a number we picked: the step shuffles the alpha chains over the beta chains, which keeps each chain's own biases and breaks only what a receptor's two chains share because they bind one thing, and takes the largest radius at which the shuffled pairs stay under a tenth of those found.

A group is a hypothesis about shared specificity, not a measurement of it. Predicting which antigen a receptor binds is still unsolved: the 2025 IMMREP benchmark's best methods reached an AUC of 0.60 on peptides they had not seen. What the groups do give you is clones to look at together, and a motif to compare with the literature.

Receptor genes and clustering

The V, D and J segments a cell transcribes say which clone it is in, not what state it is in. They are left out of the highly variable genes, so the cells of one clone do not cluster together merely for sharing a receptor.

Step reference

Step	Stage	What it does	You get	Key inputs
Initial Plot	Setup	Reads the genes of the cells and the V(D)J library of the same cells, ties each receptor table to the sample whose barcodes it shares, and keeps every chain of every cell.	Cells per sample, the chains each cell carries, how large each cell's clone is, and tables of the samples and their diversity.	None.
Chain QC	QC	Which chains each cell carries. A cell with two beta chains and a pair each is two cells in one droplet and is removed; a second alpha chain is ordinary and is kept. A chain carried by far fewer molecules than the cell's best chain of that kind is ambient RNA from a large clone, and is dropped.	The chains per sample, how well each chain was captured, and the receptor's own genes by the chains found.	Cells whose chains say two cells: remove (default) or mark. Molecules a chain needs: 1, 2 (default) or 3. A second chain's share of the cell's best: 0, a tenth (default) or a quarter.
Define Clonotypes	QC	Groups the cells that came from one T cell. Cells share a clone when they share an alpha and a beta chain; a cell with two alpha chains belongs to both of its pairs, so a chain missed in one cell does not split a clone, and a cell with only one chain joins the one clone that holds it.	Clone sizes on each sample, the largest clones, how much of each sample they take, and a table of every clone.	Two cells are one clone when they share the same rearrangement (nucleotides, default) or the same receptor protein. The V and J genes must match (default). Clones can be kept inside each donor.
T-cell States	Analysis	Names each cluster. Which clusters are T cells is read from the receptors and CD3 together, so a cluster of B cells, myeloid cells or NK cells is not called T cells whatever its CD3 reads. Each T-cell cluster is then scored over the pan-cancer T-cell atlases' markers (Zheng 2021, Chu 2023): naive, central and effector memory, terminal effector, exhausted, resident memory, regulatory, follicular helper, Th17, MAIT, gamma-delta, proliferating and interferon responding, with CD4 or CD8 in front.	The named cells on the UMAP, each cluster's score for each state, and what says a cluster is T cells. The names go in cell_type, where every later step reads them.	Clustering resolution. Clusters that are not T cells: name and keep (default) or remove.
Clonal Expansion	Analysis	Which cells sit in expanded clones: on the UMAP, per state and per condition, with STARTRAC's expansion index (Zhang 2018) for each state, read per sample so a condition with more cells does not look more expanded.	Clone size on the UMAP, clone sizes in each state, and each state's expansion index by condition.	Cell states. Compare by a sample annotation, or none.
Clones Across States	Analysis	Which states share clones, and so which cells came from one T cell: STARTRAC's transition index for each pair of states, and its migration index across tissues or time points. The shuffling test stays inside each sample, so a state found mostly in one sample does not read as sharing few clones.	Which pairs of states share clones (the ones that stand out starred), how many states each clone reaches, and the largest clones' cells across the states.	Cell states. Tissues or time points, or none. Shufflings: none, 200 (default) or 1,000.
Clone and State Together	Analysis	Where the receptor itself decides the cell's state. Clonotype modularity (Scirpy; Sturm 2020) asks whether a clone's cells sit closer together in gene expression than random cells of the same number. CoNGA's graph-vs-graph test (Schattgen 2022) asks whether a clone's expression neighbours are also its receptor's neighbours, which is how MAIT and iNKT cells and public responses show themselves.	Modularity on the UMAP, the clones whose cells sit together most, and the clones whose receptor goes with their state.	Cell states. Random groups for the test: 200, 1,000 (default) or 5,000.
Specificity Groups	Analysis	Clones whose receptors are alike enough to see the same antigen, grouped by TCRdist (Dash 2017) over both chains. How far apart two receptors may be is measured on the data itself: the alpha chains are shuffled over the beta chains, which breaks only what a receptor's two chains share because they bind one thing, and the largest radius at which the shuffled pairs stay under a tenth is taken.	The radius chosen against the shuffled chains, the largest groups, their CDR3 motifs as logos, where their cells are, and the states each group's cells are in.	Cell states. Radius: automatic (default), 12, 24 or 36. V genes must match (default).
Repertoire Overview	Analysis	Each sample's repertoire measured as a bulk repertoire is, over clones rather than templates: how many clones, how evenly they share the sample (Shannon, clonality, Hill numbers), which V and J genes they use, and how long their CDR3s are. Every sample is also read at the smallest sample's depth, so a deeper sample does not look more diverse.	Clones and clonality per sample or condition, the diversity profile, the most used V genes and the CDR3 lengths.	Compare by a sample annotation, or none. Chain: beta (default) or alpha. Diversity at the smallest sample's depth (default) or every cell captured.
Expanded Clones	Analysis	Which clones grew or shrank between two groups of samples: a binomial test per clone on its cells, Benjamini-Hochberg adjusted. Clones belong to one person, so Pair by compares each person with themselves.	Each clone's share on the two sides, the clones that grew most, and the states those clones are in.	Parameter to compare and its two values. Pair by a patient or donor column. Cell states.