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/__init__.py +86 -0
- threadfin/_utils.py +260 -0
- threadfin/api.py +658 -0
- threadfin/bcrgraph.py +255 -0
- threadfin/clones.py +653 -0
- threadfin/core.py +531 -0
- threadfin/dandelion.py +458 -0
- threadfin/density.py +409 -0
- threadfin/dynamics.py +275 -0
- threadfin/export.py +215 -0
- threadfin/expression.py +121 -0
- threadfin/heritability.py +224 -0
- threadfin/integrate.py +350 -0
- threadfin/io.py +280 -0
- threadfin/maptune.py +743 -0
- threadfin/metrics.py +137 -0
- threadfin/migration.py +165 -0
- threadfin/phylo.py +834 -0
- threadfin/plotting.py +535 -0
- threadfin/pp.py +253 -0
- threadfin/profiles.py +603 -0
- threadfin/programmes.py +1028 -0
- threadfin/programs.py +133 -0
- threadfin/reclustering.py +68 -0
- threadfin/sequence.py +379 -0
- threadfin/simulate.py +206 -0
- threadfin/specificity.py +355 -0
- threadfin/stats.py +476 -0
- threadfin/tl.py +62 -0
- threadfin-4.5.0.dist-info/METADATA +288 -0
- threadfin-4.5.0.dist-info/RECORD +34 -0
- threadfin-4.5.0.dist-info/WHEEL +5 -0
- threadfin-4.5.0.dist-info/licenses/LICENSE +21 -0
- threadfin-4.5.0.dist-info/top_level.txt +1 -0
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
|
threadfin/specificity.py
ADDED
|
@@ -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
|