diff --git a/docs/tutorials.rst b/docs/tutorials.rst
index 6a181420f..4c4af49af 100644
--- a/docs/tutorials.rst
+++ b/docs/tutorials.rst
@@ -7,5 +7,6 @@ Tutorials
tutorials/tutorial_io.ipynb
tutorials/tutorial_3k_tcr.ipynb
+ tutorials/tutorial_beam_t_query.ipynb
tutorials/tutorial_5k_bcr.ipynb
tutorials/large-datasets.md
diff --git a/docs/tutorials/tutorial_beam_t_query.ipynb b/docs/tutorials/tutorial_beam_t_query.ipynb
new file mode 100644
index 000000000..dc032a3e1
--- /dev/null
+++ b/docs/tutorials/tutorial_beam_t_query.ipynb
@@ -0,0 +1,1175 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "996661d8",
+ "metadata": {},
+ "source": [
+ "# Querying antigen-annotated T-cell receptors\n",
+ "\n",
+ "This tutorial uses the public 10x Genomics **10k Human A1101 PBMCs with EBV Spike In (BEAM-T)** dataset to combine gene expression, Antigen Capture, and paired TCR data in {class}`~mudata.MuData`. We first inspect the full dataset, then build sequence-disjoint reference, validation, and test subsets and query them with Scirpy using TCRdist and the TCRBLOSUM substitution matrices.\n",
+ "\n",
+ "The assay is `HLA-A*11:01` restricted and includes EBV peptide `AVFDRKSDAK`, CMV peptide `NLVPMVATV`, and an HLA-matched negative-control peptide. Expanded anti-EBV T cells were spiked into donor PBMCs.\n",
+ "\n",
+ "The evaluation below measures **agreement with BEAM-derived labels**, not biological ground truth. A receptor match does not by itself prove antigen specificity, and cells without a high EBV score are labelled **not EBV-high**. This is a BEAM-derived category, not a validated antigen-negative class.\n",
+ "\n",
+ "**Sources and attribution**\n",
+ "\n",
+ "- [10x Genomics dataset page](https://www.10xgenomics.com/datasets/10k-human-a1101-pbmcs-with-ebv-spike-in-beam-t-2-standard)\n",
+ "- [Cell Ranger Antigen Capture algorithm](https://www.10xgenomics.com/support/software/cell-ranger/latest/algorithms-overview/cr-5p-antigen-algorithm)\n",
+ "- [10x Loupe worked example using an antigen-specificity threshold of 90](https://www.10xgenomics.com/support/software/loupe-vdj-browser/latest/tutorials/lvb-integrated-analysis-loupe-browser)\n",
+ "- Dataset license: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)\n",
+ "- {func}`scirpy.pp.ir_dist` and {func}`scirpy.tl.ir_query`"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "d859d027",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-08-10T14:31:40.913341Z",
+ "iopub.status.busy": "2026-08-10T14:31:40.913020Z",
+ "iopub.status.idle": "2026-08-10T14:31:41.031837Z",
+ "shell.execute_reply": "2026-08-10T14:31:41.030614Z"
+ },
+ "tags": [
+ "remove-cell"
+ ]
+ },
+ "outputs": [],
+ "source": [
+ "# Hidden documentation setup: retrieve pinned public files.\n",
+ "import os\n",
+ "import warnings\n",
+ "from pathlib import Path\n",
+ "\n",
+ "import pooch\n",
+ "\n",
+ "warnings.filterwarnings(\n",
+ " \"ignore\",\n",
+ " message=r\"`__version__` is deprecated, use `importlib\\.metadata\\.version\\('scanpy'\\)` instead\",\n",
+ " category=FutureWarning,\n",
+ ")\n",
+ "warnings.filterwarnings(\"ignore\", message=r\"Variable names are not unique.*\", category=UserWarning)\n",
+ "warnings.filterwarnings(\n",
+ " \"ignore\",\n",
+ " message=r\"Support for Awkward Arrays is currently experimental\\..*\",\n",
+ ")\n",
+ "\n",
+ "CACHE_DIR = Path(os.environ.get(\"SCIRPY_DATA_DIR\") or pooch.os_cache(\"scirpy\")) / \"tutorial-beam-t-query\"\n",
+ "BASE_URL = (\n",
+ " \"https://cf.10xgenomics.com/samples/cell-vdj/7.1.0/\"\n",
+ " \"10k_BEAM-T_Human_A1101_EBV_spikein_5pv2_10k_BEAM-T_Human_A1101_EBV_spikein_5pv2/\"\n",
+ ")\n",
+ "FILES = {\n",
+ " \"feature_matrix\": (\n",
+ " \"10k_BEAM-T_Human_A1101_EBV_spikein_5pv2_10k_BEAM-T_Human_A1101_EBV_spikein_5pv2_count_sample_filtered_feature_bc_matrix.h5\",\n",
+ " \"284b22a51ec6048d14ffd6f26db09e8769bd694623982e0e8aaa5bae69d38ed5\",\n",
+ " ),\n",
+ " \"tcr_contigs\": (\n",
+ " \"10k_BEAM-T_Human_A1101_EBV_spikein_5pv2_10k_BEAM-T_Human_A1101_EBV_spikein_5pv2_vdj_t_filtered_contig_annotations.csv\",\n",
+ " \"3113306fa032e5b3d20d109557e04240d32c3903452d5ad154a940a68f120dca\",\n",
+ " ),\n",
+ " \"antigen_scores\": (\n",
+ " \"10k_BEAM-T_Human_A1101_EBV_spikein_5pv2_10k_BEAM-T_Human_A1101_EBV_spikein_5pv2_antigen_analysis_antigen_specificity_scores.csv\",\n",
+ " \"2b3302ac64bc6049d2117095c9dbd0d301d777ca30367b9d3fd96157720c6be0\",\n",
+ " ),\n",
+ "}\n",
+ "paths = {\n",
+ " key: Path(\n",
+ " pooch.retrieve(\n",
+ " url=BASE_URL + filename,\n",
+ " known_hash=f\"sha256:{sha256}\",\n",
+ " path=CACHE_DIR,\n",
+ " fname=filename,\n",
+ " progressbar=False,\n",
+ " )\n",
+ " )\n",
+ " for key, (filename, sha256) in FILES.items()\n",
+ "}"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9ad32e8b",
+ "metadata": {},
+ "source": [
+ "## Imports and settings"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "3a9ef352",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-08-10T14:31:41.035742Z",
+ "iopub.status.busy": "2026-08-10T14:31:41.035335Z",
+ "iopub.status.idle": "2026-08-10T14:31:53.602211Z",
+ "shell.execute_reply": "2026-08-10T14:31:53.601357Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "import muon as mu\n",
+ "import numpy as np\n",
+ "import pandas as pd\n",
+ "import scanpy as sc\n",
+ "import scirpy as ir\n",
+ "\n",
+ "mu.set_options(pull_on_update=False)\n",
+ "\n",
+ "BEAM_SCORE_THRESHOLD = 90.0\n",
+ "FULL_PAIR_CATEGORIES = [\"single pair\", \"extra VJ\", \"extra VDJ\", \"two full chains\"]\n",
+ "EXACT_DISTANCE_KEY = \"ir_dist_beam_t_exact\"\n",
+ "QUERY_DISTANCE_KEY = \"ir_dist_beam_t_query_aa_identity\"\n",
+ "QUERY_KEY = \"ir_query_beam_t_query_aa_identity\"\n",
+ "RANDOM_STATE = 0"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "70276734",
+ "metadata": {},
+ "source": [
+ "## Load and organize the modalities\n",
+ "\n",
+ "The 10x feature matrix contains both Gene Expression and Antigen Capture features. We separate them so that antigen barcodes do not enter normalization, highly-variable-gene selection, PCA, or UMAP.\n",
+ "\n",
+ "The resulting objects are:\n",
+ "\n",
+ "| Object | Contents | Role |\n",
+ "|---|---|---|\n",
+ "| `mdata[\"gex\"]` | cells × genes | transcriptomic preprocessing and UMAP |\n",
+ "| `mdata[\"antigen\"]` | cells × EBV, CMV, and control features | raw Antigen Capture UMI counts |\n",
+ "| `mdata[\"airr\"]` | reconstructed TCR chains | Scirpy receptor analysis |\n",
+ "| `antigen_scores` | one row per barcode–antigen pair | Cell Ranger scores and antigen/control UMI counts |\n",
+ "\n",
+ "`reference`, `validation`, and `test` created later are ordinary MuData subsets with the same modalities."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "9e60a382",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-08-10T14:31:53.604389Z",
+ "iopub.status.busy": "2026-08-10T14:31:53.603919Z",
+ "iopub.status.idle": "2026-08-10T14:31:58.768042Z",
+ "shell.execute_reply": "2026-08-10T14:31:58.767409Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " cells | \n",
+ " variables | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | gex | \n",
+ " 9798 | \n",
+ " 36601 | \n",
+ "
\n",
+ " \n",
+ " | antigen | \n",
+ " 9798 | \n",
+ " 3 | \n",
+ "
\n",
+ " \n",
+ " | airr | \n",
+ " 5643 | \n",
+ " <NA> | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "gex = mdata.mod[\"gex\"]\n",
+ "sc.pp.filter_genes(gex, min_cells=10)\n",
+ "sc.pp.normalize_total(gex, target_sum=1e4)\n",
+ "sc.pp.log1p(gex)\n",
+ "sc.pp.highly_variable_genes(gex, n_top_genes=2_000)\n",
+ "sc.tl.pca(gex, mask_var=\"highly_variable\")\n",
+ "sc.pp.neighbors(gex, n_neighbors=15, n_pcs=30)\n",
+ "sc.tl.umap(gex, random_state=RANDOM_STATE)\n",
+ "\n",
+ "sc.pl.umap(\n",
+ " gex,\n",
+ " color=[\"CD3D\", \"CD8A\", \"EBV_score\", \"CMV_score\"],\n",
+ " ncols=2,\n",
+ " frameon=False,\n",
+ " vmax=\"p99\",\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "ed41018e",
+ "metadata": {},
+ "source": [
+ "The UMAP is descriptive: it shows the transcriptomic context of T-cell markers and continuous BEAM scores. It is not used by the receptor classifier."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "aea7f22d",
+ "metadata": {},
+ "source": [
+ "## Receptor QC and BEAM-derived group labels"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "adc7274d",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-08-10T14:32:45.711686Z",
+ "iopub.status.busy": "2026-08-10T14:32:45.711361Z",
+ "iopub.status.idle": "2026-08-10T14:32:47.680828Z",
+ "shell.execute_reply": "2026-08-10T14:32:47.679892Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " cells | \n",
+ "
\n",
+ " \n",
+ " | chain pairing | \n",
+ " | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | single pair | \n",
+ " 4310 | \n",
+ "
\n",
+ " \n",
+ " | extra VJ | \n",
+ " 526 | \n",
+ "
\n",
+ " \n",
+ " | extra VDJ | \n",
+ " 123 | \n",
+ "
\n",
+ " \n",
+ " | two full chains | \n",
+ " 119 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " cells | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | EBV reference-candidate cells | \n",
+ " 362 | \n",
+ "
\n",
+ " \n",
+ " | negative-control UMI > 0 | \n",
+ " 78 | \n",
+ "
\n",
+ " \n",
+ " | CMV UMI > 0 | \n",
+ " 112 | \n",
+ "
\n",
+ " \n",
+ " | EBV UMI <= negative-control UMI | \n",
+ " 0 | \n",
+ "
\n",
+ " \n",
+ " | EBV UMI <= CMV UMI | \n",
+ " 0 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " cells | \n",
+ " unique exact receptor groups | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | reference | \n",
+ " 110 | \n",
+ " 110 | \n",
+ "
\n",
+ " \n",
+ " | query | \n",
+ " 4968 | \n",
+ " 4409 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " reference_barcode | \n",
+ " EBV_score | \n",
+ " EBV_score_ref | \n",
+ " CMV_score | \n",
+ " CMV_score_ref | \n",
+ " exact_receptor_group | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | AACACGTCACCAGTTA-1 | \n",
+ " CTGCCTAGTCTCACCT-1 | \n",
+ " 0.042 | \n",
+ " 100.0 | \n",
+ " 0.042 | \n",
+ " 0.042 | \n",
+ " 65 | \n",
+ "
\n",
+ " \n",
+ " | AACGTTGAGCCGCCTA-1 | \n",
+ " CATATGGTCACGGTTA-1 | \n",
+ " 0.042 | \n",
+ " 100.0 | \n",
+ " 0.042 | \n",
+ " 0.042 | \n",
+ " 92 | \n",
+ "
\n",
+ " \n",
+ " | AACGTTGGTCACCTAA-1 | \n",
+ " AACACGTCAGTAAGCG-1 | \n",
+ " 100.000 | \n",
+ " 100.0 | \n",
+ " 0.042 | \n",
+ " 0.159 | \n",
+ " 66 | \n",
+ "
\n",
+ " \n",
+ " | AACGTTGGTTGGACCC-1 | \n",
+ " CATATGGTCACGGTTA-1 | \n",
+ " 0.042 | \n",
+ " 100.0 | \n",
+ " 0.042 | \n",
+ " 0.042 | \n",
+ " 92 | \n",
+ "
\n",
+ " \n",
+ " | AACTCAGGTAAACGCG-1 | \n",
+ " AACACGTCAGTAAGCG-1 | \n",
+ " 100.000 | \n",
+ " 100.0 | \n",
+ " 0.000 | \n",
+ " 0.159 | \n",
+ " 66 | \n",
+ "
\n",
+ " \n",
+ " | AAGCCGCGTGCGGTAA-1 | \n",
+ " AACACGTCAGTAAGCG-1 | \n",
+ " 100.000 | \n",
+ " 100.0 | \n",
+ " 0.042 | \n",
+ " 0.159 | \n",
+ " 66 | \n",
+ "
\n",
+ " \n",
+ " | AAGGCAGCAGAGCCAA-1 | \n",
+ " CATATGGTCACGGTTA-1 | \n",
+ " 0.376 | \n",
+ " 100.0 | \n",
+ " 0.042 | \n",
+ " 0.042 | \n",
+ " 92 | \n",
+ "
\n",
+ " \n",
+ " | AATCCAGTCATATCGG-1 | \n",
+ " AACACGTCAGTAAGCG-1 | \n",
+ " 100.000 | \n",
+ " 100.0 | \n",
+ " 0.042 | \n",
+ " 0.159 | \n",
+ " 66 | \n",
+ "
\n",
+ " \n",
+ " | ACACCAAAGGGAGTAA-1 | \n",
+ " CATATGGTCACGGTTA-1 | \n",
+ " 0.042 | \n",
+ " 100.0 | \n",
+ " 0.042 | \n",
+ " 0.042 | \n",
+ " 92 | \n",
+ "
\n",
+ " \n",
+ " | ACACCAAAGTACATGA-1 | \n",
+ " AACACGTCAGTAAGCG-1 | \n",
+ " 100.000 | \n",
+ " 100.0 | \n",
+ " 0.060 | \n",
+ " 0.159 | \n",
+ " 66 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " value | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | query-suitable cells | \n",
+ " 5078 | \n",
+ "
\n",
+ " \n",
+ " | EBV reference-candidate cells | \n",
+ " 362 | \n",
+ "
\n",
+ " \n",
+ " | remaining query-suitable cells | \n",
+ " 4716 | \n",
+ "
\n",
+ " \n",
+ " | reference cells | \n",
+ " 110 | \n",
+ "
\n",
+ " \n",
+ " | query cells | \n",
+ " 4968 | \n",
+ "
\n",
+ " \n",
+ " | match pairs | \n",
+ " 357 | \n",
+ "
\n",
+ " \n",
+ " | unique matched query cells | \n",
+ " 357 | \n",
+ "
\n",
+ " \n",
+ " | matched EBV-high query cells | \n",
+ " 252 | \n",
+ "
\n",
+ " \n",
+ " | matched remaining query cells | \n",
+ " 105 | \n",
+ "
\n",
+ " \n",
+ " | unmatched query cells | \n",
+ " 4611 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | query_score_group | \n",
+ " remaining query-suitable cells | \n",
+ " EBV score >= 90 with EBV UMI > 0 | \n",
+ "
\n",
+ " \n",
+ " | match_status | \n",
+ " | \n",
+ " | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | matched | \n",
+ " 105.0 | \n",
+ " 252.0 | \n",
+ "
\n",
+ " \n",
+ " | unmatched | \n",
+ " 4611.0 | \n",
+ " 0.0 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "