Find TCRalpha/beta pairs from individual well read counts

This function runs the MAD-HYPE and T-SHELL algorithms (with efficient GPU implementations) on multi-well TCR-seq data, returning TCR alpha/beta chain pairs predicted to come from the same clone.

The MAD-HYPE (Multicell Analytical Deconvolution for High Yield Paired-chain Evaluation) algorithm uses Bayesian inference over well co-occurrence counts to call TCR alpha/beta chain pairings from multicell-per-well sequencing data.

The T-SHELL algorithm (TCRαβ Sequence Highly Efficient Linkage Learning) is a heuristic for pairing TCR chains from multi-well data, based on correlation of read frequency across wells.

Usage

run_pairing(
  folder_path,
  folder_out,
  prefix,
  well_filter_thres = 0.5,
  min_reads = 0,
  min_wells = 2,
  well_pos = 3,
  tshell_settings = get_tshell_settings(format = "auto"),
  wellset = get_well_subset(1:16, 1:24),
  wellset1 = lifecycle::deprecated(),
  compute = lifecycle::deprecated(),
  backend = c("auto", "cpu", "cupy", "mlx"),
  pval_thres_tshell = lifecycle::deprecated(),
  wij_thres_tshell = lifecycle::deprecated(),
  verbose = TRUE,
  write_extra_files = FALSE,
  filter_before_top3 = FALSE,
  fork = lifecycle::deprecated(),
  shared = lifecycle::deprecated(),
  chunk_size = 500,
  exclude_nonfunctional = FALSE,
  select_best_madhype = FALSE,
  select_best_tshell = FALSE,
  gzip_output = FALSE,
  pseudobulk_only = FALSE,
  run_qc = TRUE,
  clone_threshold_chain = c("alpha", "beta", "independent")
)

Arguments

folder_path

the path of the folder with well-level data

folder_out

the path of the folder to write results to. The function will create the folder if it does not exist.

prefix

a prefix for the output file names

well_filter_thres

wells are removed if they have fewer unique clones than: wellfilter_thres*(Avg. # of unique clones per well). The default value is 0.5

min_reads

minimum number of reads a chain must have in a well to be considered observed (note: actual minimum is min_reads+1. Default value is 0, i.e. chain must have >= 1 read in a well)

min_wells

minimum number of wells a chain must be observed in to be paired.

well_pos

the position of the well ID (e.g. "B5") in the file names. For example, files named "<well_id>_TCRalpha.tsv" would use well_pos=3. (default is 3)

tshell_settings

a named list with pairing settings for T-SHELL: pval_thres_tshell and wij_thres_tshell. You may pass your own list or call get_tshell_settings() with setting "auto", "384_well", or "96_well". By default, "auto" is selected and "384_well" settings will be used if there are >= 150 wells passing QC, otherwise "96_well" settings will be used.

pval_thres_tshell is the adjusted p-value threshold for T-SHELL significance (default 1e-10 for 384-well plate, 1e-3 for 96-well plate)
wij_thres_tshell is the threshold for the number of wells containing both chains for T-SHELL significance (default >2 wells for 384-well plate, >3 wells for 96-well plate)

wellset

a vector of wells to use for the pairing

backend

the computing backend to use. The function looks for a GPU and automatically chooses an appropriate backend by default.

verbose

whether to print out messages (default TRUE)

write_extra_files

whether to write un-necessary intermediate files (default FALSE)

filter_before_top3

whether to filter by loss fraction before extracting top 3 correlation values for T-SHELL (default FALSE)

chunk_size

batch size for calculations in pairing scripts

exclude_nonfunctional

whether to exclude non-functional chains before pairing (default is FALSE)

select_best_madhype

whether to use a secondary algorithm on the pairs from the MAD-HYPE algorithm to select the best pairs for each clone (default is FALSE)

select_best_tshell

whether to use a secondary algorithm on the pairs from the T-SHELL algorithm to select the best pairs for each clone (default is FALSE)

gzip_output

whether to compress (gzip) output files (default is FALSE)

pseudobulk_only

only output pseudobulk with no pairing (default is FALSE)

run_qc

whether to run the quality control pipeline on the samples, dropping wells with a number of unique alpha or beta clones below a certain threshold.

clone_threshold_chain

the chain to use to determine the clone threshold for QC. If "alpha", clone counts for TCRalpha will be used to determine a threshold for both alpha and beta chains. If "beta", TCRbeta clone counts will be used to determine the threshold for both chains. If "independent", then TCRalpha clones will be used to determine a QC threshold for alpha and TCRbeta clones will be used to determine a separate QC threshold for beta clones. ("alpha" is default)

Value

A data frame with the TCR-alpha/TCR-beta pairs.

The function also writes three files to "folder_out":

A data frame ("_pseudobulk_TRA.tsv") of pseudobulk counts for TCRalpha chains
A data frame ("_pseudobulk_TRB.tsv") of pseudobulk counts for TCRbeta chains
A data frame ("_TIRTLoutput.tsv") of TCR-alpha/TCR-beta pairs.

These files can be loaded using the load_tirtlseq() function.

If write_extra_files is TRUE, the function also writes sparse matrices of per-well read counts (well x chain) for TCR-alpha and beta to "_alpha_mat.rds" and "_beta_mat.rds". Metadata for the chains in these matrices are written to "_alpha_meta.parquet" and "_beta_meta.parquet" and metadata for the wells is written to "_well_meta.parquet".

These files can be loaded using the load_well_counts_binary() function.

Details

The function also performs QC on the wells, dropping wells with unusually small numbers of clones, and calculates "pseudobulk" for TCRα and TCRβ, aggregating reads over all wells. It writes three tab-separated files (.tsv), one for TCRα pseudobulk, one for TCRβ pseudobulk, and one for predicted TCRαβ pairs.

Output may include alpha or beta chains with many predicted partners. To keep only the best partners by p-value for each algorithm (allowing up to two alphas for each beta chain), you may run with the options select_best_madhype = TRUE and select_best_tshell == TRUE. Removing nonfunctional chains with exclude_nonfunctional = TRUE may also help to reduce multi-pairing.

See Pogorelyy & Kirk et al. (2026) for a full description of the T-SHELL algorithm.

See Holec et al. (2019) for a full description of the MAD-HYPE algorithm.

References

Pogorelyy MV, Kirk AM, Adhikari S, Minervina AA, Sundararaman B, Vegesana K, Brice DC, Scott ZB, SJTRC Study Team, Thomas PG (2026). "TIRTL-seq: deep, quantitative and affordable paired TCR repertoire sequencing." Nature Methods, 23, 56-64. doi:10.1038/s41592-025-02907-9