docs: add BEAM-T receptor query tutorial

[matteobroketa]

Summary

• add a tutorial for querying antigen-annotated TCR data
• use the full public 10x Genomics HLA-A*11:01 BEAM-T dataset
• construct a conservative EBV-enriched reference subset and query the remaining cells
• demonstrate ir_dist, define_clonotype_clusters, ir_query, ir_query_annotate_df, and group_abundance
• retain EBV and CMV antigen-specificity scores as continuous metadata

The score threshold of 90 is used only to select a conservative EBV reference subset. The tutorial explicitly treats it as an illustrative, dataset-specific convention rather than a universal cutoff.

Scope

This is a documentation-only contribution. It downloads the processed data directly from 10x Genomics using pinned hashes.

This first version does not add a scirpy.datasets loader, mirror the dataset, or include an unrelated external query dataset.

Validation

• executed the notebook successfully
• reproduced deterministic reference/query and match counts
• built the documentation with warnings treated as errors
• ran git diff --check
• checked the saved notebook for local paths, credentials, tracebacks, and unstable outputs

Closes #677

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.32%. Comparing base (dae3334) to head (8c5304e).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #724      +/-   ##
==========================================
+ Coverage   78.31%   78.32%   +0.01%     
==========================================
  Files          51       51              
  Lines        4607     4628      +21     
==========================================
+ Hits         3608     3625      +17     
- Misses        999     1003       +4     

see 9 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[grst]

Thanks for putting this together @matteobroketa.

I suggest the following improvements:

• remove the EBV, CMV, and negative_control variables from the gene expression AnnData object (they are in .X and .var)
• I think you could explain a bit better what the different objects are and what they contain, e.g. what do the columns in the antigen_scores table mean, explain that query and reference are just mudata objects as any other scirpy dataset
• show the whole dataset as a umap by gene expression, highlight expression of some basic T-cell markers and the EBV/CMV scores
• Do you think some additional QC steps make sense? For instance, I was thinking it could make sense to filter out rows from the reference dataset where negative control > 0? Should we also filter out cases where both umi_ebv > 0 and umi_cmv > 0?

To show a bit better that the querying works, I was thinking of the following evaluation. Do you think this makes sense, or would that not work at all in the small demo dataset?

• query/reference split such that query does not contain any sequences that are identical to reference.
• match query against reference using a lenient metric, e.g. tcrdist with TCRblosum and use it to classify query into EBV / other
• evaluate results against know scores (confusion matrix)
• maybe add a UMAP or clonotype network plot with true and predicted labels.

LMK what you think.

[grst]

Line #22.    for column in antigen_table.columns:

I think instead of the loop, you could just do

python

mdata.mod["airr"].obs = mdata.mod["airr"].obs.join(antigen_table.set_index("barcode"), validate="1:1")

Reply via ReviewNB

[matteobroketa]

Thanks a lot for these suggestions, I am always learning more as I go.

I’ve separated the Antigen Capture features from the gene-expression AnnData, expanded the explanations of the gex, antigen, and airr modalities and the antigen-score columns. I also added a GEX UMAP with basic T-cell markers and the EBV/CMV scores.

For the additional antigen QC, I checked the current EBV reference candidates before applying a filter. Some cells have non-zero negative-control or CMV UMIs, but all candidates have more EBV UMIs than either the negative control or CMV. Since the Cell Ranger specificity score already incorporates the negative-control counts, I think it is more transparent to show these as QC diagnostics rather than automatically discard every cell with a non-zero control/off-target count.

I also added the sequence-mismatch evaluation idea. I ran unique receptor groups rather than individual cells to avoid clone-size weighting, and put a comparison as agreement with BEAM-derived labels. There's also a validation subset for the distance cutoff rather than tuning it on the final query set.