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.29%. Comparing base (dae3334) to head (7fba710).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #724      +/-   ##
==========================================
- Coverage   78.31%   78.29%   -0.03%     
==========================================
  Files          51       51              
  Lines        4607     4607              
==========================================
- Hits         3608     3607       -1     
- Misses        999     1000       +1     

see 1 file 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