Recommended workflow for TCR diversity calculation: combineTCR() directly or combineExpression() with T cell subsetting

[guohout]

Dear scRepertoire Developers
I am working with paired single-cell RNA-seq and TCR sequencing data for multiple samples and using the scRepertoire package for my analysis. I have a question regarding the recommended workflow for calculating sample-level TCR diversity metrics.
Specifically, I would like clarification on the proper step for diversity computation. Should I:
Calculate diversity directly using the combined list object generated by combineTCR()?
Or, should I first integrate the TCR data into my Seurat/SingleCellExperiment object using combineExpression(), subset to confirmed T cells based on gene expression, and then perform the diversity calculation on that subset?
While I have observed that both approaches can yield similar trends in some samples, in others, the results show a significant discrepancy. This variation has led to uncertainty about which method provides the most accurate biological interpretation.
I would be very grateful for any guidance on the intended or recommended workflow for this purpose. Understanding the best practice would greatly help ensure the correctness of my downstream analysis.
Thank you for your time and for developing this incredibly useful tool.
Best regards

TCR_list <- lapply(tcr_files, read.csv)
data_tcr <- combineTCR(
  TCR_list,
  sample = sample_names,
  removeNA = TRUE,
  removeMulti = TRUE
)

diversity_tcr = clonalDiversity(data_tcr, 
                cloneCall = "strict", 
                group.by = "sample", 
                chain = "both",
                metric = "norm.entropy",
               exportTable = TRUE,
               skip.boots = FALSE )

or

T_sub_Pbmc = combineExpression(
  data_tcr,
  T_sub_Pbmc,
  cloneCall = "strict",
  chain = "both",
  proportion = TRUE,
  cloneSize = c(Rare = 1e-04, Small = 0.001, Medium = 0.01, Large = 0.1, Hyperexpanded = 1)
)

diversity_tcr = clonalDiversity(T_sub_Pbmc, 
                cloneCall = "strict", 
                group.by = "sample_id", 
                chain = "both",
                metric = "norm.entropy",
               exportTable = TRUE,
               skip.boots = FALSE )

[ncborcherding]

@guohout,

Thanks for the detailed question and for including your code, super helpful.

Both approaches are technically valid, but they're answering slightly different questions.

1. Using combineTCR directly gives you diversity across all detected TCR sequences
2. Going through combineExpression and subsetting to confirmed T cells gives you diversity specifically among your verified T cell population.

For most biological interpretations, the latter is probably what you actually want to report since you're ensuring each cell is a bona fide T cell rather than potentially including doublets, ambient RNA contamination, or cells that failed your expression-based QC.

That said, the discrepancies you're seeing between methods might not be entirely about which cells are included. By default, clonalDiversity() bootstraps and subsamples to the size of your smallest group to enable fair comparisons across samples. If your smallest sample changes substantially between the two approaches (which it likely does after subsetting to T cells), that alone could drive meaningful differences in your normalized entropy values. Worth checking whether your smallest sample is the same in both cases and how different the cell counts are.

The samples where the two methods agree are probably those where your T cell subset captures most of the TCR-containing cells anyway. The ones that diverge are worth a closer look as it could be interesting biology or could flag samples with quality issues.

Hope that helps clarify things!

Nick