threadfin 4.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
threadfin/simulate.py ADDED
@@ -0,0 +1,206 @@
1
+ """Simulate paired expression + clone data with known clonal programmes.
2
+
3
+ The generative model mirrors the structure Threadfin is meant to recover:
4
+
5
+ 1. ``n_states`` cell states are points (centres) in a ``dim``-dimensional
6
+ expression embedding.
7
+ 2. Each clonal programme ``g`` has a state composition ``theta_g`` (for
8
+ example "mostly plasmablast" or "half germinal centre, half memory").
9
+ 3. Each clone belongs to one donor and one programme; its own composition is
10
+ ``theta_c ~ Dirichlet(concentration * theta_g)``, so clones of a programme
11
+ are similar but not identical, and it carries a small heritable offset
12
+ ``u_c`` (clonal memory within a state).
13
+ 4. Clone sizes follow a truncated Zipf law, so most clones are singletons,
14
+ as in real repertoires.
15
+ 5. Cells are sampled in contexts (libraries / samples) that add a technical
16
+ mean shift. By default every clone is captured in a single context of its
17
+ donor (``clone_nesting="nested"``), so context effects masquerade as clone
18
+ effects unless they are removed.
19
+
20
+ Each cell: ``x = centre[state] + u_clone + shift[context] + noise``.
21
+
22
+ Scenarios
23
+ ---------
24
+ ``"default"``
25
+ As above.
26
+ ``"null"``
27
+ One programme and no clonal offsets: clone identity carries no state
28
+ information beyond sampling context (for type-I error checks).
29
+ ``"bifurcation"``
30
+ Programme A splits its cells between states 1 and 2, programme B sits in
31
+ a state placed exactly at their midpoint: the two programmes have the
32
+ same centroid but different distributions.
33
+
34
+ Time courses
35
+ ------------
36
+ With ``n_timepoints > 1`` every cell is sampled at a random time point and
37
+ each sample (donor x time point) is its own context. Between consecutive time
38
+ points a clone keeps its programme with probability ``memory`` and otherwise
39
+ switches to a different one, so ``memory`` is the ground truth for
40
+ :func:`threadfin.tl.clonal_memory`.
41
+ """
42
+
43
+ from __future__ import annotations
44
+
45
+ import numpy as np
46
+ import pandas as pd
47
+
48
+ __all__ = ["simulate_repertoire"]
49
+
50
+
51
+ def _distinct_compositions(rng, n_programmes, n_states, alpha, min_dist=0.35, tries=200):
52
+ """Programme state compositions that are pairwise distinct (Hellinger)."""
53
+ best = None
54
+ for _ in range(tries):
55
+ theta = rng.dirichlet(np.full(n_states, alpha), size=n_programmes)
56
+ h = np.sqrt(0.5 * ((np.sqrt(theta)[:, None, :] - np.sqrt(theta)[None, :, :]) ** 2).sum(-1))
57
+ np.fill_diagonal(h, np.inf)
58
+ if best is None or h.min() > best[0]:
59
+ best = (h.min(), theta)
60
+ if h.min() >= min_dist:
61
+ return theta
62
+ return best[1]
63
+
64
+
65
+ def simulate_repertoire(
66
+ *,
67
+ scenario: str = "default",
68
+ n_donors: int = 4,
69
+ contexts_per_donor: int = 3,
70
+ n_programmes: int = 4,
71
+ n_states: int = 6,
72
+ n_clones: int = 3000,
73
+ clone_size_exponent: float = 2.2,
74
+ max_clone_size: int = 300,
75
+ dim: int = 20,
76
+ state_separation: float = 1.5,
77
+ programme_sparsity: float = 0.4,
78
+ clone_concentration: float | None = 15.0,
79
+ clonal_offset: float = 0.4,
80
+ noise: float = 1.0,
81
+ context_shift: float = 1.0,
82
+ clone_nesting: str = "nested",
83
+ n_timepoints: int = 1,
84
+ memory: float = 1.0,
85
+ random_state: int = 0,
86
+ ):
87
+ """Simulate an AnnData with ground-truth clones, programmes and states.
88
+
89
+ Parameters
90
+ ----------
91
+ scenario
92
+ ``"default"``, ``"null"`` or ``"bifurcation"`` (see module docstring).
93
+ clone_size_exponent
94
+ Zipf exponent (larger = more singletons).
95
+ state_separation
96
+ Standard deviation of state centres (larger = more distinct states).
97
+ programme_sparsity
98
+ Dirichlet concentration of programme compositions (smaller = each
99
+ programme dominated by fewer states).
100
+ clone_concentration
101
+ How closely clones follow their programme (``None`` = exactly).
102
+ clonal_offset
103
+ SD of the clone-specific continuous offset.
104
+ noise, context_shift
105
+ SD of cell noise and of context mean shifts.
106
+ clone_nesting
107
+ ``"nested"`` (each clone sampled in one context) or ``"spread"``.
108
+ n_timepoints, memory
109
+ Number of sampling time points and the probability that a clone keeps
110
+ its programme from one time point to the next (see module docstring).
111
+
112
+ Returns
113
+ -------
114
+ AnnData with ``X`` = ``obsm['X_pca']`` = the embedding and ``obs`` columns
115
+ ``clone_id``, ``donor``, ``context``, ``true_programme``, ``true_state``
116
+ and ``clone_size``; parameters in ``uns['simulation']``.
117
+ """
118
+ from anndata import AnnData
119
+
120
+ rng = np.random.default_rng(random_state)
121
+ if scenario not in ("default", "null", "bifurcation"):
122
+ raise ValueError("scenario must be 'default', 'null' or 'bifurcation'.")
123
+ if scenario == "null":
124
+ n_programmes, clonal_offset, clone_concentration = 1, 0.0, None
125
+
126
+ # 1) states and programme compositions
127
+ centres = rng.normal(0.0, state_separation, size=(n_states, dim))
128
+ theta = _distinct_compositions(rng, n_programmes, n_states, programme_sparsity)
129
+ if scenario == "bifurcation":
130
+ if n_states < 3 or n_programmes < 2:
131
+ raise ValueError("bifurcation needs >= 3 states and >= 2 programmes.")
132
+ centres[2] = 0.5 * (centres[0] + centres[1]) # state 2 = midpoint of states 0 and 1
133
+ theta[0] = np.eye(n_states)[0] * 0.5 + np.eye(n_states)[1] * 0.5
134
+ theta[1] = np.eye(n_states)[2]
135
+
136
+ # 2) clones: donor, programme (per time point), composition, offset, size
137
+ donor = rng.integers(0, n_donors, size=n_clones)
138
+ n_t = max(1, int(n_timepoints))
139
+ programme_t = np.empty((n_clones, n_t), dtype=np.int64)
140
+ programme_t[:, 0] = rng.integers(0, n_programmes, size=n_clones)
141
+ for t in range(1, n_t):
142
+ keep = rng.random(n_clones) < memory
143
+ other = (programme_t[:, t - 1] + rng.integers(1, max(n_programmes, 2), size=n_clones)) % max(n_programmes, 1)
144
+ programme_t[:, t] = np.where(keep | (n_programmes == 1), programme_t[:, t - 1], other)
145
+ theta_ct = np.empty((n_clones, n_t, n_states))
146
+ for t in range(n_t):
147
+ for c in range(n_clones):
148
+ g = programme_t[c, t]
149
+ if t > 0 and g == programme_t[c, t - 1]:
150
+ theta_ct[c, t] = theta_ct[c, t - 1] # same programme -> same composition
151
+ elif clone_concentration is None:
152
+ theta_ct[c, t] = theta[g]
153
+ else:
154
+ theta_ct[c, t] = rng.dirichlet(clone_concentration * theta[g] + 1e-3)
155
+ offset = rng.normal(0.0, clonal_offset, size=(n_clones, dim)) if clonal_offset > 0 else np.zeros((n_clones, dim))
156
+ sizes = np.minimum(rng.zipf(clone_size_exponent, size=n_clones), max_clone_size)
157
+
158
+ # 3) cells: time point, state, context
159
+ clone_of_cell = np.repeat(np.arange(n_clones), sizes)
160
+ n_cells = clone_of_cell.size
161
+ tp = rng.integers(0, n_t, size=n_cells) if n_t > 1 else np.zeros(n_cells, dtype=np.int64)
162
+ u = rng.random(n_cells)
163
+ cdf = np.cumsum(theta_ct[clone_of_cell, tp], axis=1)
164
+ state = (u[:, None] > cdf).sum(axis=1).clip(max=n_states - 1)
165
+ d = donor[clone_of_cell]
166
+ if n_t > 1:
167
+ ctx = tp # one sample per donor x time point
168
+ shifts = rng.normal(0.0, context_shift, size=(n_donors, n_t, dim))
169
+ else:
170
+ shifts = rng.normal(0.0, context_shift, size=(n_donors, contexts_per_donor, dim))
171
+ if clone_nesting == "nested":
172
+ ctx = rng.integers(0, contexts_per_donor, size=n_clones)[clone_of_cell]
173
+ elif clone_nesting == "spread":
174
+ ctx = rng.integers(0, contexts_per_donor, size=n_cells)
175
+ else:
176
+ raise ValueError("clone_nesting must be 'nested' or 'spread'.")
177
+ x = (centres[state] + offset[clone_of_cell] + shifts[d, ctx]
178
+ + rng.normal(0.0, noise, size=(n_cells, dim)))
179
+ programme = programme_t[:, 0]
180
+
181
+ obs = pd.DataFrame({
182
+ "clone_id": [f"D{di}|C{ci:05d}" for di, ci in zip(d, clone_of_cell)],
183
+ "donor": [f"D{di}" for di in d],
184
+ "context": [f"D{di}_S{ci}" for di, ci in zip(d, ctx)],
185
+ "true_programme": [f"G{g}" for g in programme_t[clone_of_cell, tp]],
186
+ "true_state": [f"S{s}" for s in state],
187
+ "clone_size": sizes[clone_of_cell],
188
+ }, index=[f"cell{i}" for i in range(n_cells)])
189
+ if n_t > 1:
190
+ obs["timepoint"] = [f"t{t}" for t in tp]
191
+ obs["context"] = [f"D{di}_t{t}" for di, t in zip(d, tp)]
192
+ obs["programme_at_start"] = [f"G{g}" for g in programme[clone_of_cell]]
193
+ adata = AnnData(X=x.astype(np.float32), obs=obs)
194
+ adata.obsm["X_pca"] = x.astype(np.float32)
195
+ adata.uns["simulation"] = {
196
+ "scenario": scenario, "n_donors": n_donors, "contexts_per_donor": contexts_per_donor,
197
+ "n_programmes": n_programmes, "n_states": n_states, "n_clones": n_clones,
198
+ "clone_size_exponent": clone_size_exponent, "dim": dim,
199
+ "state_separation": state_separation, "programme_sparsity": programme_sparsity,
200
+ "clone_concentration": -1.0 if clone_concentration is None else float(clone_concentration),
201
+ "clonal_offset": clonal_offset, "noise": noise, "context_shift": context_shift,
202
+ "clone_nesting": clone_nesting, "random_state": random_state,
203
+ "n_timepoints": n_t, "memory": float(memory),
204
+ "programme_composition": theta,
205
+ }
206
+ return adata
@@ -0,0 +1,355 @@
1
+ """Antigen-specificity discovery: label mapping and reference-database matching.
2
+
3
+ Two routes to per-clone specificity annotation:
4
+
5
+ * :func:`annotate_specificity` — map author/experimental labels onto clones,
6
+ or match clones against an antibody database (e.g. CoV-AbDab) by heavy V
7
+ gene + CDRH3 similarity.
8
+ * :func:`specificity_enrichment` — Fisher-exact enrichment of specificities
9
+ in clone communities with BH FDR.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from pathlib import Path
15
+
16
+ import numpy as np
17
+ import pandas as pd
18
+
19
+ from .sequence import _gene, cdr3_similarity
20
+
21
+ # CoV-AbDab (https://opig.stats.ox.ac.uk/webapps/covabdab/) column names.
22
+ # Users with differently-named tables pass ``ref_cols`` overrides; any key
23
+ # not given falls back to these defaults.
24
+ _REF_COLS = {
25
+ "v": "Heavy V Gene",
26
+ "j": "Heavy J Gene",
27
+ "cdr3": "CDRH3",
28
+ "specificity": "Binds to",
29
+ "name": "Name",
30
+ }
31
+
32
+ # sequence.cdr3_similarity(mode="auto") returns 0.0 beyond this length gap;
33
+ # used to pre-filter reference entries before any alignment is attempted.
34
+ _MAX_LEN_DIFF = 4
35
+
36
+
37
+ def _norm_gene(call, prefix: str) -> str:
38
+ """Normalize a gene call to allele-free form.
39
+
40
+ Handles multi-calls ('IGHV3-23*01,IGHV3-23*02' -> 'IGHV3-23'), the
41
+ bare '3-23' style seen in some CoV-AbDab rows (bare '3-23' with
42
+ ``prefix='IGHV'`` -> 'IGHV3-23'), and CoV-AbDab's species suffix
43
+ ('IGHV4-31 (Human)' -> 'IGHV4-31').
44
+ """
45
+ g = _gene(str(call).split("(")[0].strip()).upper()
46
+ if g and not g.startswith("IG") and g[0].isdigit():
47
+ g = prefix + g
48
+ return g
49
+
50
+
51
+ def _clean_seq(seq) -> str | None:
52
+ if not isinstance(seq, str):
53
+ return None
54
+ s = seq.strip().upper().replace("-", "").replace(".", "")
55
+ return s or None
56
+
57
+
58
+ def _clean_specificity(val) -> str | None:
59
+ """First antigen of a (possibly ';'-separated) 'Binds to' field."""
60
+ if not isinstance(val, str):
61
+ return None
62
+ first = val.split(";")[0].strip()
63
+ return first or None
64
+
65
+
66
+ def _modal(series: pd.Series):
67
+ """Deterministic modal value: lexicographically smallest mode."""
68
+ s = series.dropna()
69
+ if len(s) == 0:
70
+ return None
71
+ m = s.astype(str).mode()
72
+ return m.sort_values(kind="stable").iloc[0] if len(m) else None
73
+
74
+
75
+ def _check_obs(adata, cols, context: str) -> None:
76
+ for col in cols:
77
+ if col not in adata.obs.columns:
78
+ raise KeyError(
79
+ f"'{col}' not found in adata.obs (needed for {context}). "
80
+ "Attach BCR annotations first (threadfin.attach_bcr) or pass "
81
+ "the matching column name explicitly."
82
+ )
83
+
84
+
85
+ def _clone_table(adata, clone_key, v_col, j_col, cdr3_col) -> pd.DataFrame:
86
+ """One row per clone: modal (v, j, cdr3) and cell count."""
87
+ df = adata.obs[[clone_key, v_col, j_col, cdr3_col]].dropna(subset=[clone_key])
88
+ rows = []
89
+ for clone, grp in df.groupby(clone_key, observed=True, sort=True):
90
+ rows.append(
91
+ {
92
+ "clone": clone,
93
+ "n_cells": int(len(grp)),
94
+ "v": _norm_gene(_modal(grp[v_col]), "IGHV"),
95
+ "j": _norm_gene(_modal(grp[j_col]), "IGHJ"),
96
+ "cdr3": _clean_seq(_modal(grp[cdr3_col])),
97
+ }
98
+ )
99
+ return pd.DataFrame(rows)
100
+
101
+
102
+ def annotate_specificity(
103
+ adata,
104
+ *,
105
+ clone_key: str = "clone_id",
106
+ labels: pd.DataFrame | None = None,
107
+ label_col: str | None = None,
108
+ reference=None,
109
+ ref_cols: dict | None = None,
110
+ cdr3_col: str = "bcr_cdr3",
111
+ v_col: str = "bcr_v_call",
112
+ j_col: str = "bcr_j_call",
113
+ identity: float = 0.85,
114
+ key_added: str = "specificity",
115
+ ):
116
+ """Annotate clones with antigen specificity.
117
+
118
+ Exactly one of ``labels`` / ``reference`` must be given.
119
+
120
+ **Label mode** (``labels`` DataFrame with columns ``clone_key`` and
121
+ ``label_col``): per-clone specificity labels (e.g. LIBRA-seq
122
+ ``s_pos_clone`` calls or author-validated mAb panels) are mapped onto
123
+ ``obs[key_added]`` by clone identity. Cells whose clone has no label get
124
+ NA; on duplicate label rows for one clone the first is kept.
125
+
126
+ **Reference-matching mode** (``reference``: path or DataFrame of an
127
+ antibody database such as CoV-AbDab): per clone, the modal heavy-chain
128
+ (v_call, j_call, cdr3_aa) is taken over its cells; reference entries are
129
+ bucketed by normalized V gene (no all-pairs comparison) and, within the
130
+ clone's bucket, pre-filtered to CDR3 length difference <= 4 before
131
+ :func:`threadfin.sequence.cdr3_similarity` is computed. The best hit with
132
+ similarity >= ``identity`` assigns its specificity; ties are broken by
133
+ shared J gene, then reference order. A per-clone match table is stored in
134
+ ``adata.uns[key_added + "_clones"]``.
135
+
136
+ Null model / limitations: a reference hit is *evidence*, not proof, of
137
+ specificity — matching uses the heavy chain only (no light chain, no SHM
138
+ profile) and convergent public CDR3s can collide across antigens. The
139
+ ``identity`` threshold is a heuristic, not a calibrated error rate;
140
+ validate key hits experimentally (e.g. with the clone's recombinant mAb).
141
+ Label mode carries no model at all — labels are trusted as given.
142
+
143
+ Parameters
144
+ ----------
145
+ adata
146
+ AnnData with ``obs[clone_key]`` (and ``obs[v_col]``, ``obs[j_col]``,
147
+ ``obs[cdr3_col]`` in reference mode).
148
+ clone_key
149
+ Column of ``obs`` holding clone identities.
150
+ labels
151
+ DataFrame with columns ``clone_key`` and ``label_col``.
152
+ label_col
153
+ Column of ``labels`` holding the specificity label.
154
+ reference
155
+ Path to a CSV or a DataFrame of an antibody database.
156
+ ref_cols
157
+ Explicit mapping of logical names (``"v"``, ``"j"``, ``"cdr3"``,
158
+ ``"specificity"``, ``"name"``) to reference columns. Unspecified
159
+ keys default to CoV-AbDab column names.
160
+ cdr3_col, v_col, j_col
161
+ Columns of ``obs`` with heavy-chain CDR3 amino acids and V/J calls.
162
+ identity
163
+ Minimum CDR3 similarity (0-1) for a reference hit.
164
+ key_added
165
+ Name of the added ``obs`` column; the reference-mode clone match
166
+ table goes to ``uns[key_added + "_clones"]``.
167
+
168
+ Returns
169
+ -------
170
+ The modified ``adata`` (in place and returned), with
171
+ ``obs[key_added]`` (categorical; NA where unannotated). In reference
172
+ mode, ``adata.uns[key_added + "_clones"]`` holds a DataFrame with
173
+ columns ``[clone_key, n_cells, best_score, hit_name, specificity]``,
174
+ one row per matched clone.
175
+ """
176
+ if (labels is None) == (reference is None):
177
+ raise ValueError("Pass exactly one of `labels` or `reference`.")
178
+ _check_obs(adata, [clone_key], "specificity annotation")
179
+
180
+ if labels is not None:
181
+ if label_col is None:
182
+ raise ValueError("Label mode requires `label_col`.")
183
+ for col in (clone_key, label_col):
184
+ if col not in labels.columns:
185
+ raise KeyError(
186
+ f"'{col}' not found in the labels table. Label mode needs "
187
+ f"a DataFrame with columns {clone_key!r} and {label_col!r}."
188
+ )
189
+ lab = labels[[clone_key, label_col]].dropna(subset=[clone_key])
190
+ lab = lab.drop_duplicates(subset=[clone_key], keep="first")
191
+ mapping = dict(zip(lab[clone_key], lab[label_col]))
192
+ adata.obs[key_added] = adata.obs[clone_key].map(mapping).astype("category")
193
+ return adata
194
+
195
+ # ---- reference-matching mode ----
196
+ if not (0.0 < identity <= 1.0):
197
+ raise ValueError("`identity` must be in (0, 1].")
198
+ _check_obs(adata, [v_col, j_col, cdr3_col], "reference matching")
199
+
200
+ ref = pd.read_csv(reference) if isinstance(reference, (str, Path)) else reference
201
+ if not isinstance(ref, pd.DataFrame):
202
+ raise TypeError("`reference` must be a path to a CSV or a pandas DataFrame.")
203
+ cols = {**_REF_COLS, **(ref_cols or {})}
204
+ for logical in ("v", "cdr3", "specificity"):
205
+ if cols[logical] not in ref.columns:
206
+ raise KeyError(
207
+ f"Reference table has no column {cols[logical]!r} (logical name "
208
+ f"{logical!r}). Available columns: {list(ref.columns)}. Pass "
209
+ "`ref_cols` to map logical names onto your table's columns."
210
+ )
211
+ name_col = cols.get("name")
212
+ if name_col is None or name_col not in ref.columns:
213
+ ref = ref.assign(**{"_ref_name": [f"ref_{i}" for i in range(len(ref))]})
214
+ name_col = "_ref_name"
215
+
216
+ # bucket reference entries by normalized heavy V gene; within a bucket,
217
+ # group by CDR3 length so only near-equal lengths are ever aligned
218
+ v_arr = ref[cols["v"]].tolist()
219
+ cdr3_arr = ref[cols["cdr3"]].tolist()
220
+ spec_arr = ref[cols["specificity"]].tolist()
221
+ name_arr = ref[name_col].tolist()
222
+ j_col_ref = cols.get("j")
223
+ j_arr = ref[j_col_ref].tolist() if j_col_ref in ref.columns else [None] * len(ref)
224
+ buckets: dict[str, dict[int, list[tuple]]] = {}
225
+ for order in range(len(ref)):
226
+ vg = _norm_gene(v_arr[order], "IGHV")
227
+ cdr3 = _clean_seq(cdr3_arr[order])
228
+ spec = _clean_specificity(spec_arr[order])
229
+ if not vg or cdr3 is None or spec is None:
230
+ continue
231
+ entry = (cdr3, str(name_arr[order]), spec, _norm_gene(j_arr[order], "IGHJ"), order)
232
+ buckets.setdefault(vg, {}).setdefault(len(cdr3), []).append(entry)
233
+
234
+ clones = _clone_table(adata, clone_key, v_col, j_col, cdr3_col)
235
+ matches: dict = {}
236
+ rows = []
237
+ for rec in clones.itertuples(index=False):
238
+ if not rec.v or rec.cdr3 is None:
239
+ continue
240
+ by_len = buckets.get(rec.v)
241
+ if not by_len:
242
+ continue
243
+ best = None # (score, same_j, -order, entry)
244
+ for length, entries in by_len.items():
245
+ if abs(length - len(rec.cdr3)) > _MAX_LEN_DIFF:
246
+ continue
247
+ for cdr3_r, name, spec, j_r, order in entries:
248
+ score = cdr3_similarity(rec.cdr3, cdr3_r)
249
+ if score < identity:
250
+ continue
251
+ same_j = bool(rec.j) and bool(j_r) and rec.j == j_r
252
+ cand = (score, same_j, -order, (name, spec))
253
+ if best is None or cand[:3] > best[:3]:
254
+ best = cand
255
+ if best is not None:
256
+ name, spec = best[3]
257
+ matches[rec.clone] = spec
258
+ rows.append(
259
+ {
260
+ clone_key: rec.clone,
261
+ "n_cells": rec.n_cells,
262
+ "best_score": float(best[0]),
263
+ "hit_name": name,
264
+ "specificity": spec,
265
+ }
266
+ )
267
+
268
+ adata.obs[key_added] = adata.obs[clone_key].map(matches).astype("category")
269
+ adata.uns[key_added + "_clones"] = pd.DataFrame(
270
+ rows, columns=[clone_key, "n_cells", "best_score", "hit_name", "specificity"]
271
+ )
272
+ return adata
273
+
274
+
275
+ def specificity_enrichment(
276
+ adata,
277
+ *,
278
+ cluster_key: str = "clone_cluster",
279
+ specificity_key: str = "specificity",
280
+ ) -> pd.DataFrame:
281
+ """Fisher-exact enrichment of specificities in clone communities.
282
+
283
+ For every (community, specificity) pair, tests whether cells annotated
284
+ with that specificity are over-represented in the community
285
+ (one-sided Fisher exact, ``alternative="greater"``), with
286
+ Benjamini-Hochberg FDR over all tested pairs.
287
+
288
+ Null model / limitations: the null is independence between community and
289
+ specificity *at cell level*. Clonal expansion violates cell independence
290
+ (cells of one clone share both), so p-values are anti-conservative for
291
+ expanded clones — treat them as a ranking device and confirm key
292
+ enrichments with a clone-level sensitivity analysis (e.g. counting
293
+ clones instead of cells).
294
+
295
+ Parameters
296
+ ----------
297
+ adata
298
+ AnnData with ``obs[cluster_key]`` and ``obs[specificity_key]``
299
+ (the latter typically from :func:`annotate_specificity`).
300
+ cluster_key
301
+ Column of ``obs`` holding clone-community labels.
302
+ specificity_key
303
+ Column of ``obs`` holding specificity annotations.
304
+
305
+ Returns
306
+ -------
307
+ Tidy DataFrame, one row per (community, specificity) pair, sorted by
308
+ p-value, with columns ``[cluster_key, specificity, n_cells, fraction,
309
+ odds_ratio, pvalue, fdr]``. ``n_cells`` is the number of cells with
310
+ that specificity in the community; ``fraction`` is that count over all
311
+ specificity-annotated cells of the community.
312
+ """
313
+ from scipy.stats import fisher_exact
314
+
315
+ _check_obs(adata, [cluster_key, specificity_key], "specificity enrichment")
316
+
317
+ obs = adata.obs[[cluster_key, specificity_key]].dropna()
318
+ if len(obs) == 0:
319
+ raise ValueError(
320
+ f"No cells with both '{cluster_key}' and '{specificity_key}' present."
321
+ )
322
+ obs = obs.astype(str)
323
+ clusters = pd.Categorical(obs[cluster_key]).categories
324
+ specs = pd.Categorical(obs[specificity_key]).categories
325
+
326
+ rows = []
327
+ n = len(obs)
328
+ for cl in clusters:
329
+ in_cl = (obs[cluster_key] == cl).to_numpy()
330
+ n_cl = int(in_cl.sum())
331
+ for sp in specs:
332
+ in_sp = (obs[specificity_key] == sp).to_numpy()
333
+ a = int((in_cl & in_sp).sum())
334
+ b = n_cl - a
335
+ c = int(in_sp.sum()) - a
336
+ d = n - a - b - c
337
+ odds, p = fisher_exact([[a, b], [c, d]], alternative="greater")
338
+ rows.append(
339
+ {
340
+ cluster_key: cl,
341
+ "specificity": sp,
342
+ "n_cells": a,
343
+ "fraction": float(a / n_cl) if n_cl else 0.0,
344
+ "odds_ratio": float(odds),
345
+ "pvalue": float(p),
346
+ }
347
+ )
348
+
349
+ out = pd.DataFrame(rows).sort_values("pvalue").reset_index(drop=True)
350
+ # Benjamini-Hochberg FDR (monotone in the sorted p-values)
351
+ m = len(out)
352
+ ranks = np.arange(1, m + 1)
353
+ fdr = out["pvalue"] * m / ranks
354
+ out["fdr"] = np.minimum.accumulate(fdr.to_numpy()[::-1])[::-1].clip(max=1.0)
355
+ return out