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/bcrgraph.py
ADDED
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
"""Clone-level BCR similarity graph and sequence-based clone definition.
|
|
2
|
+
|
|
3
|
+
Candidate pairs are only evaluated within (V-gene, J-gene) blocks — both the
|
|
4
|
+
biologically correct support set and the scalability fix (no all-pairs CDR3
|
|
5
|
+
alignment). Edge weights come from CDR3 similarity, optionally blended with
|
|
6
|
+
light-chain CDR3 similarity.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import warnings
|
|
12
|
+
|
|
13
|
+
import numpy as np
|
|
14
|
+
import pandas as pd
|
|
15
|
+
|
|
16
|
+
from .sequence import cdr3_similarity_pairs
|
|
17
|
+
|
|
18
|
+
_BLOCK_ALLPAIRS_MAX = 2000
|
|
19
|
+
_SENTINEL = "__threadfin_na__"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _first_call(x):
|
|
23
|
+
"""Normalize a V/J call: first call before ',', gene before allele '*'."""
|
|
24
|
+
if x is None or (isinstance(x, float) and np.isnan(x)) or x is pd.NA:
|
|
25
|
+
return None
|
|
26
|
+
s = str(x).split(",")[0].split("*")[0].strip()
|
|
27
|
+
return s or None
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def bcr_similarity_graph(
|
|
31
|
+
clone_info: pd.DataFrame,
|
|
32
|
+
*,
|
|
33
|
+
cdr3_sim_threshold: float = 0.85,
|
|
34
|
+
same_vj: bool = True,
|
|
35
|
+
include_light: bool = False,
|
|
36
|
+
max_pairs_per_clone: int = 200,
|
|
37
|
+
):
|
|
38
|
+
"""Sparse clone x clone BCR similarity adjacency.
|
|
39
|
+
|
|
40
|
+
Parameters
|
|
41
|
+
----------
|
|
42
|
+
clone_info
|
|
43
|
+
DataFrame indexed by clone id with columns ``v_call, j_call, cdr3``
|
|
44
|
+
(heavy chain; optionally ``cdr3_light, v_call_light``).
|
|
45
|
+
cdr3_sim_threshold
|
|
46
|
+
Minimum edge weight; weaker pairs are dropped.
|
|
47
|
+
same_vj
|
|
48
|
+
Restrict candidate pairs to clones sharing the (normalized) V and J
|
|
49
|
+
gene calls.
|
|
50
|
+
include_light
|
|
51
|
+
If True and both clones have ``cdr3_light``, edge weight is
|
|
52
|
+
``0.7 * heavy + 0.3 * light`` CDR3 similarity.
|
|
53
|
+
max_pairs_per_clone
|
|
54
|
+
Random-subsample cap per clone for blocks larger than 2000 clones.
|
|
55
|
+
|
|
56
|
+
Returns
|
|
57
|
+
-------
|
|
58
|
+
Symmetric ``(n_clones, n_clones)`` CSR matrix with zero diagonal, in the
|
|
59
|
+
row order of ``clone_info``.
|
|
60
|
+
"""
|
|
61
|
+
from scipy import sparse
|
|
62
|
+
|
|
63
|
+
for col in ("v_call", "j_call", "cdr3"):
|
|
64
|
+
if col not in clone_info.columns:
|
|
65
|
+
raise ValueError(f"clone_info needs a '{col}' column.")
|
|
66
|
+
|
|
67
|
+
n = len(clone_info.index)
|
|
68
|
+
info = clone_info.copy()
|
|
69
|
+
info["_v"] = info["v_call"].map(_first_call)
|
|
70
|
+
info["_j"] = info["j_call"].map(_first_call)
|
|
71
|
+
valid = info["_v"].notna() & info["_j"].notna() & info["cdr3"].notna()
|
|
72
|
+
info = info[valid]
|
|
73
|
+
info["_pos"] = pd.Series(np.arange(n), index=clone_info.index).reindex(info.index)
|
|
74
|
+
|
|
75
|
+
rows_all, cols_all, data_all = [], [], []
|
|
76
|
+
if n >= 2 and len(info) >= 2:
|
|
77
|
+
if same_vj:
|
|
78
|
+
blocks = list(info.groupby(["_v", "_j"], sort=False).indices.values())
|
|
79
|
+
else:
|
|
80
|
+
blocks = [np.arange(len(info))]
|
|
81
|
+
|
|
82
|
+
heavy = info["cdr3"].astype(str).to_numpy()
|
|
83
|
+
gpos = info["_pos"].to_numpy()
|
|
84
|
+
light = None
|
|
85
|
+
if include_light and "cdr3_light" in info.columns:
|
|
86
|
+
light = info["cdr3_light"].to_numpy()
|
|
87
|
+
|
|
88
|
+
for bidx in blocks:
|
|
89
|
+
bidx = np.asarray(bidx)
|
|
90
|
+
nb = len(bidx)
|
|
91
|
+
if nb < 2:
|
|
92
|
+
continue
|
|
93
|
+
if nb <= _BLOCK_ALLPAIRS_MAX:
|
|
94
|
+
ai, bi = np.triu_indices(nb, k=1)
|
|
95
|
+
else:
|
|
96
|
+
rng = np.random.default_rng(0)
|
|
97
|
+
src = np.repeat(np.arange(nb), max_pairs_per_clone)
|
|
98
|
+
dst = rng.integers(0, nb, size=nb * max_pairs_per_clone)
|
|
99
|
+
keep = src != dst
|
|
100
|
+
lo = np.minimum(src, dst)[keep]
|
|
101
|
+
hi = np.maximum(src, dst)[keep]
|
|
102
|
+
_, sel = np.unique(lo.astype(np.int64) * nb + hi, return_index=True)
|
|
103
|
+
ai, bi = lo[sel], hi[sel]
|
|
104
|
+
|
|
105
|
+
bseq = heavy[bidx]
|
|
106
|
+
sims = np.asarray(
|
|
107
|
+
cdr3_similarity_pairs(bseq[ai], bseq[bi]), dtype=np.float64
|
|
108
|
+
)
|
|
109
|
+
if light is not None:
|
|
110
|
+
lseq = light[bidx]
|
|
111
|
+
la, lb = lseq[ai], lseq[bi]
|
|
112
|
+
both = pd.notna(la) & pd.notna(lb)
|
|
113
|
+
if both.any():
|
|
114
|
+
lsim = np.asarray(
|
|
115
|
+
cdr3_similarity_pairs(
|
|
116
|
+
la[both].astype(str), lb[both].astype(str)
|
|
117
|
+
),
|
|
118
|
+
dtype=np.float64,
|
|
119
|
+
)
|
|
120
|
+
sims[both] = 0.7 * sims[both] + 0.3 * lsim
|
|
121
|
+
|
|
122
|
+
keep = sims >= cdr3_sim_threshold
|
|
123
|
+
rows_all.append(gpos[bidx][ai[keep]])
|
|
124
|
+
cols_all.append(gpos[bidx][bi[keep]])
|
|
125
|
+
data_all.append(sims[keep])
|
|
126
|
+
|
|
127
|
+
if data_all:
|
|
128
|
+
rows = np.concatenate(rows_all)
|
|
129
|
+
cols = np.concatenate(cols_all)
|
|
130
|
+
data = np.concatenate(data_all)
|
|
131
|
+
w = sparse.coo_matrix((data, (rows, cols)), shape=(n, n))
|
|
132
|
+
w = w.maximum(w.T).tocsr()
|
|
133
|
+
w.setdiag(0)
|
|
134
|
+
w.eliminate_zeros()
|
|
135
|
+
else:
|
|
136
|
+
w = sparse.csr_matrix((n, n))
|
|
137
|
+
|
|
138
|
+
print(
|
|
139
|
+
f"[threadfin] bcr_similarity_graph: {n} clones, {w.nnz // 2} edges "
|
|
140
|
+
f"(threshold={cdr3_sim_threshold}, same_vj={same_vj}).",
|
|
141
|
+
flush=True,
|
|
142
|
+
)
|
|
143
|
+
return w
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def _row_key(df: pd.DataFrame, cols: list[str]) -> pd.Series:
|
|
147
|
+
key = df[cols[0]].astype("string").fillna(_SENTINEL)
|
|
148
|
+
for c in cols[1:]:
|
|
149
|
+
key = key + "\x1f" + df[c].astype("string").fillna(_SENTINEL)
|
|
150
|
+
return key
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def define_clones(
|
|
154
|
+
bcr: pd.DataFrame,
|
|
155
|
+
*,
|
|
156
|
+
cdr3_sim_threshold: float = 0.85,
|
|
157
|
+
same_vj: bool = True,
|
|
158
|
+
method: str = "leiden",
|
|
159
|
+
resolution: float = 0.5,
|
|
160
|
+
out_col: str = "clone_id_seq",
|
|
161
|
+
) -> pd.Series:
|
|
162
|
+
"""Sequence-similarity clone (re)definition over a per-cell BCR table.
|
|
163
|
+
|
|
164
|
+
Unique ``(v_call, j_call, cdr3[, clone_id])`` rows are clustered via the
|
|
165
|
+
BCR similarity graph (connected components or Leiden), and the labels are
|
|
166
|
+
mapped back to cells. Cells lacking v/cdr3 get NA.
|
|
167
|
+
|
|
168
|
+
Parameters
|
|
169
|
+
----------
|
|
170
|
+
bcr
|
|
171
|
+
Per-cell table indexed by barcode with ``v_call, j_call, cdr3`` and
|
|
172
|
+
optionally ``clone_id``.
|
|
173
|
+
cdr3_sim_threshold, same_vj
|
|
174
|
+
Passed to :func:`bcr_similarity_graph`.
|
|
175
|
+
method
|
|
176
|
+
``"connected"`` (scipy connected components) or ``"leiden"``
|
|
177
|
+
(requires igraph + leidenalg).
|
|
178
|
+
resolution
|
|
179
|
+
Leiden resolution parameter.
|
|
180
|
+
out_col
|
|
181
|
+
Name of the returned Series.
|
|
182
|
+
|
|
183
|
+
Returns
|
|
184
|
+
-------
|
|
185
|
+
Series indexed by barcode named ``out_col``.
|
|
186
|
+
|
|
187
|
+
.. deprecated::
|
|
188
|
+
Sequence-based redefinition is superseded by Dandelion's paired
|
|
189
|
+
heavy + light clone definition (:func:`threadfin.define_clones_dandelion`).
|
|
190
|
+
"""
|
|
191
|
+
warnings.warn(
|
|
192
|
+
"threadfin.bcrgraph.define_clones is deprecated; Threadfin's clone definition is "
|
|
193
|
+
"Dandelion's paired heavy + light definition — use threadfin.define_clones_dandelion.",
|
|
194
|
+
DeprecationWarning, stacklevel=2,
|
|
195
|
+
)
|
|
196
|
+
for col in ("v_call", "j_call", "cdr3"):
|
|
197
|
+
if col not in bcr.columns:
|
|
198
|
+
raise ValueError(f"bcr needs a '{col}' column.")
|
|
199
|
+
if method not in ("connected", "leiden"):
|
|
200
|
+
raise ValueError(f"Unknown method: {method!r}")
|
|
201
|
+
|
|
202
|
+
out = pd.Series(pd.NA, index=bcr.index, name=out_col, dtype="object")
|
|
203
|
+
sub = bcr.dropna(subset=["v_call", "j_call", "cdr3"])
|
|
204
|
+
if len(sub) == 0:
|
|
205
|
+
return out
|
|
206
|
+
|
|
207
|
+
key_cols = ["v_call", "j_call", "cdr3"]
|
|
208
|
+
if "clone_id" in bcr.columns:
|
|
209
|
+
key_cols = key_cols + ["clone_id"]
|
|
210
|
+
uniq = sub[key_cols].drop_duplicates().reset_index(drop=True)
|
|
211
|
+
uniq.index = pd.Index([f"__grp{i}" for i in range(len(uniq))], name="group")
|
|
212
|
+
|
|
213
|
+
graph = bcr_similarity_graph(
|
|
214
|
+
uniq, cdr3_sim_threshold=cdr3_sim_threshold, same_vj=same_vj
|
|
215
|
+
)
|
|
216
|
+
|
|
217
|
+
if method == "connected":
|
|
218
|
+
from scipy.sparse import csgraph
|
|
219
|
+
|
|
220
|
+
_, labels = csgraph.connected_components(graph, directed=False)
|
|
221
|
+
else:
|
|
222
|
+
try:
|
|
223
|
+
import igraph as ig
|
|
224
|
+
import leidenalg
|
|
225
|
+
except ImportError as e:
|
|
226
|
+
raise ImportError(
|
|
227
|
+
"method='leiden' requires igraph and leidenalg "
|
|
228
|
+
"(pip install igraph leidenalg); use method='connected' "
|
|
229
|
+
"as a dependency-free fallback."
|
|
230
|
+
) from e
|
|
231
|
+
from scipy import sparse
|
|
232
|
+
|
|
233
|
+
tri = sparse.triu(graph).tocoo()
|
|
234
|
+
g = ig.Graph(
|
|
235
|
+
n=graph.shape[0],
|
|
236
|
+
edges=list(zip(tri.row.tolist(), tri.col.tolist())),
|
|
237
|
+
edge_attrs={"weight": tri.data.tolist()},
|
|
238
|
+
)
|
|
239
|
+
part = leidenalg.find_partition(
|
|
240
|
+
g,
|
|
241
|
+
leidenalg.RBConfigurationVertexPartition,
|
|
242
|
+
weights="weight",
|
|
243
|
+
resolution_parameter=resolution,
|
|
244
|
+
seed=0,
|
|
245
|
+
)
|
|
246
|
+
labels = np.asarray(part.membership)
|
|
247
|
+
|
|
248
|
+
# deterministic labels: component 0 = largest
|
|
249
|
+
sizes = pd.Series(labels).value_counts()
|
|
250
|
+
remap = {lab: f"{out_col}_{i}" for i, lab in enumerate(sizes.index)}
|
|
251
|
+
uniq_labels = pd.Series([remap[l] for l in labels], index=uniq.index)
|
|
252
|
+
|
|
253
|
+
lut = pd.Series(uniq_labels.to_numpy(), index=_row_key(uniq, key_cols))
|
|
254
|
+
out.loc[sub.index] = _row_key(sub, key_cols).map(lut).to_numpy()
|
|
255
|
+
return out
|