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/core.py
ADDED
|
@@ -0,0 +1,531 @@
|
|
|
1
|
+
"""Core Threadfin algorithm: transcriptional-state-aware clonotype reclustering.
|
|
2
|
+
|
|
3
|
+
Idea
|
|
4
|
+
----
|
|
5
|
+
Single-cell BCR sequencing defines *clonotypes* from rearranged V(D)J
|
|
6
|
+
sequences, while scRNA-seq defines *transcriptional states* from gene
|
|
7
|
+
expression. Threadfin links the two: it places every clonotype at the
|
|
8
|
+
centroid of its member cells in a transcriptional embedding and clusters
|
|
9
|
+
clonotypes in that space. The resulting ``clone_cluster`` labels group
|
|
10
|
+
clonotypes whose cells share a transcriptional state (e.g. germinal-center
|
|
11
|
+
light-zone vs dark-zone B cells, plasmablasts, memory), turning the
|
|
12
|
+
repertoire from a list of sequences into a map of clone behaviour.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import warnings
|
|
18
|
+
|
|
19
|
+
import numpy as np
|
|
20
|
+
import pandas as pd
|
|
21
|
+
|
|
22
|
+
from ._utils import get_basis, require_positive_int
|
|
23
|
+
from .reclustering import _resolve_parameters
|
|
24
|
+
|
|
25
|
+
_CLONE_INFO_KEY = "threadfin_clones"
|
|
26
|
+
_CLONE_MAP_KEY = "threadfin"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _get_matrix(adata, basis: str) -> np.ndarray:
|
|
30
|
+
return get_basis(adata, basis)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def clone_centroids(
|
|
34
|
+
adata,
|
|
35
|
+
clone_key: str = "clone_id",
|
|
36
|
+
basis: str = "X_umap",
|
|
37
|
+
min_clone_size: int = 1,
|
|
38
|
+
weight_col: str | None = None,
|
|
39
|
+
) -> pd.DataFrame:
|
|
40
|
+
"""Compute the centroid of every clonotype in a transcriptional embedding.
|
|
41
|
+
|
|
42
|
+
Parameters
|
|
43
|
+
----------
|
|
44
|
+
adata
|
|
45
|
+
AnnData with ``adata.obs[clone_key]`` and ``adata.obsm[basis]``.
|
|
46
|
+
clone_key
|
|
47
|
+
``obs`` column holding the clonotype id. Cells with a missing value
|
|
48
|
+
(no BCR) are ignored.
|
|
49
|
+
basis
|
|
50
|
+
``obsm`` key of the embedding to average, or ``"X"`` for the full
|
|
51
|
+
expression matrix.
|
|
52
|
+
min_clone_size
|
|
53
|
+
Clonotypes with fewer cells are dropped from the centroid table.
|
|
54
|
+
weight_col
|
|
55
|
+
Optional ``obs`` column of per-cell weights; centroids become
|
|
56
|
+
weighted means (NaN weights count as 0).
|
|
57
|
+
|
|
58
|
+
Returns
|
|
59
|
+
-------
|
|
60
|
+
DataFrame indexed by clone id with one column per embedding dimension and
|
|
61
|
+
an ``n_cells`` column.
|
|
62
|
+
"""
|
|
63
|
+
if clone_key not in adata.obs.columns:
|
|
64
|
+
raise KeyError(
|
|
65
|
+
f"'{clone_key}' not found in adata.obs. Attach BCR annotations "
|
|
66
|
+
"first (threadfin.attach_bcr) or provide your own clone column."
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
require_positive_int(min_clone_size, "min_clone_size")
|
|
70
|
+
coords = _get_matrix(adata, basis)
|
|
71
|
+
clones = adata.obs[clone_key]
|
|
72
|
+
placeholders = clones.astype("string").str.strip().str.lower().isin(["", "nan", "none", "<na>"])
|
|
73
|
+
valid = clones.notna() & ~placeholders
|
|
74
|
+
if valid.sum() == 0:
|
|
75
|
+
raise ValueError(f"All values in adata.obs['{clone_key}'] are missing.")
|
|
76
|
+
|
|
77
|
+
df = pd.DataFrame(coords[valid.to_numpy()], index=None)
|
|
78
|
+
df["clone"] = clones[valid].to_numpy()
|
|
79
|
+
|
|
80
|
+
sizes = df.groupby("clone").size().rename("n_cells")
|
|
81
|
+
if weight_col is not None:
|
|
82
|
+
if weight_col not in adata.obs.columns:
|
|
83
|
+
raise KeyError(f"'{weight_col}' not found in adata.obs.")
|
|
84
|
+
w = pd.to_numeric(adata.obs[weight_col], errors="coerce").to_numpy(dtype=float)[valid.to_numpy()]
|
|
85
|
+
w = np.where(np.isnan(w), 0.0, w)
|
|
86
|
+
if not np.isfinite(w).all() or (w < 0).any():
|
|
87
|
+
raise ValueError("Cell weights must be non-negative and finite (missing weights count as zero).")
|
|
88
|
+
coord_cols = [c for c in df.columns if c != "clone"]
|
|
89
|
+
weighted = df[coord_cols].multiply(w, axis=0)
|
|
90
|
+
weighted["clone"] = df["clone"]
|
|
91
|
+
denom = pd.Series(w).groupby(df["clone"].to_numpy()).sum()
|
|
92
|
+
centroids = weighted.groupby("clone").sum().div(
|
|
93
|
+
denom.replace(0, np.nan), axis=0
|
|
94
|
+
)
|
|
95
|
+
else:
|
|
96
|
+
centroids = df.groupby("clone").mean()
|
|
97
|
+
centroids.columns = [f"{basis}_{i}" for i in range(centroids.shape[1])]
|
|
98
|
+
centroids = centroids.join(sizes)
|
|
99
|
+
centroids = centroids[(centroids["n_cells"] >= min_clone_size) & centroids.notna().all(axis=1)]
|
|
100
|
+
if len(centroids) == 0:
|
|
101
|
+
raise ValueError(
|
|
102
|
+
f"No clones with >= {min_clone_size} cells. Lower min_clone_size."
|
|
103
|
+
)
|
|
104
|
+
return centroids
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _leiden_on_distances(
|
|
108
|
+
dist: np.ndarray,
|
|
109
|
+
n_neighbors: int,
|
|
110
|
+
resolution: float,
|
|
111
|
+
random_state: int,
|
|
112
|
+
) -> np.ndarray:
|
|
113
|
+
"""Leiden-cluster a precomputed distance matrix.
|
|
114
|
+
|
|
115
|
+
Builds a kNN graph with self-scaled Gaussian edge weights (the standard
|
|
116
|
+
UMAP/scanpy kernel) and partitions it with leidenalg directly, so the
|
|
117
|
+
result does not depend on scanpy's (changing) neighbors API.
|
|
118
|
+
"""
|
|
119
|
+
import igraph as ig
|
|
120
|
+
import leidenalg
|
|
121
|
+
from sklearn.neighbors import NearestNeighbors
|
|
122
|
+
|
|
123
|
+
n = dist.shape[0]
|
|
124
|
+
k = int(min(n_neighbors, n - 1))
|
|
125
|
+
if k < 1:
|
|
126
|
+
raise ValueError("Need at least 2 clones to cluster.")
|
|
127
|
+
|
|
128
|
+
nn = NearestNeighbors(n_neighbors=k + 1, metric="precomputed").fit(dist)
|
|
129
|
+
d_knn, idx = nn.kneighbors(dist)
|
|
130
|
+
d_knn, idx = d_knn[:, 1:], idx[:, 1:] # drop self
|
|
131
|
+
|
|
132
|
+
# self-scaled Gaussian kernel (sigma = distance to k-th neighbor)
|
|
133
|
+
sigma = np.maximum(d_knn[:, -1:], 1e-10)
|
|
134
|
+
w = np.exp(-(d_knn**2) / (sigma**2))
|
|
135
|
+
|
|
136
|
+
edges = [(i, j) for i in range(n) for j in idx[i]]
|
|
137
|
+
weights = [float(x) for x in w.ravel()]
|
|
138
|
+
g = ig.Graph(n=n, edges=edges, directed=True, edge_attrs={"weight": weights})
|
|
139
|
+
g_und = g.to_undirected(combine_edges="max") # igraph>=1.0 does this in place
|
|
140
|
+
if g_und is not None:
|
|
141
|
+
g = g_und
|
|
142
|
+
|
|
143
|
+
part = leidenalg.find_partition(
|
|
144
|
+
g,
|
|
145
|
+
leidenalg.RBConfigurationVertexPartition,
|
|
146
|
+
weights="weight",
|
|
147
|
+
resolution_parameter=resolution,
|
|
148
|
+
seed=random_state,
|
|
149
|
+
)
|
|
150
|
+
return np.array([str(m) for m in part.membership])
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def clonotype_recluster(
|
|
154
|
+
adata,
|
|
155
|
+
clone_key: str = "clone_id",
|
|
156
|
+
basis: str = "X_umap",
|
|
157
|
+
min_clone_size: int = 3,
|
|
158
|
+
n_neighbors: int | None = None,
|
|
159
|
+
resolution: float | None = None,
|
|
160
|
+
cdr3_weight: float = 0.0,
|
|
161
|
+
distances: np.ndarray | None = None,
|
|
162
|
+
embed_clones: bool = True,
|
|
163
|
+
random_state: int = 0,
|
|
164
|
+
key_added: str = "clone_cluster",
|
|
165
|
+
copy: bool = False,
|
|
166
|
+
*,
|
|
167
|
+
preset: str = "cohesive",
|
|
168
|
+
min_dist: float | None = None,
|
|
169
|
+
spread: float | None = None,
|
|
170
|
+
learning_rate: float | None = None,
|
|
171
|
+
umap_n_neighbors: int | None = None,
|
|
172
|
+
embedding_mode: str = "precomputed",
|
|
173
|
+
cluster_on: str = "distances",
|
|
174
|
+
cluster_random_state: int | None = None,
|
|
175
|
+
):
|
|
176
|
+
"""Cluster clonotypes by the transcriptional state of their member cells.
|
|
177
|
+
|
|
178
|
+
Steps: (1) place each clonotype at the centroid of its cells in
|
|
179
|
+
``basis``; (2) optionally blend in heavy-chain CDR3 sequence distance
|
|
180
|
+
(``cdr3_weight``); (3) build a kNN graph over clonotypes and Leiden-
|
|
181
|
+
cluster it; (4) map the resulting ``clone_cluster`` label back to cells.
|
|
182
|
+
|
|
183
|
+
Parameters
|
|
184
|
+
----------
|
|
185
|
+
adata
|
|
186
|
+
AnnData with ``obs[clone_key]`` and ``obsm[basis]``.
|
|
187
|
+
clone_key
|
|
188
|
+
``obs`` column holding the clonotype id.
|
|
189
|
+
basis
|
|
190
|
+
Embedding used for centroids (``"X_umap"`` uses cell-map coordinates;
|
|
191
|
+
``"X_pca"`` avoids averaging a nonlinear display). This alone does
|
|
192
|
+
not reproduce the historical notebook pipeline. ``"joint"``
|
|
193
|
+
uses the coupled GEX+BCR embedding in
|
|
194
|
+
``adata.uns['threadfin']['joint']``, computing it with default
|
|
195
|
+
parameters via :func:`threadfin.integrate.joint_embedding` if absent.
|
|
196
|
+
min_clone_size
|
|
197
|
+
Clonotypes with fewer cells are excluded from clustering (their cells
|
|
198
|
+
receive ``NaN``). Singletons are mostly uninformative.
|
|
199
|
+
n_neighbors
|
|
200
|
+
k for the clonotype kNN graph and, unless overridden, UMAP.
|
|
201
|
+
``None`` uses the preset. Counts are capped at the number of clones
|
|
202
|
+
minus one; requested and effective settings are saved.
|
|
203
|
+
resolution
|
|
204
|
+
Leiden resolution (higher = more clone clusters); ``None`` uses the preset.
|
|
205
|
+
cdr3_weight
|
|
206
|
+
In ``[0, 1]``. If > 0, the transcriptional distance between clones is
|
|
207
|
+
blended with their consensus-CDR3 Hamming distance:
|
|
208
|
+
``D = (1 - w) * z(D_gex) + w * z(D_cdr3)``. Requires clone-level CDR3
|
|
209
|
+
information stored by :func:`threadfin.attach_bcr`. Mutually exclusive
|
|
210
|
+
with ``distances``.
|
|
211
|
+
distances
|
|
212
|
+
Optional precomputed clone-level distances (condensed pdist vector or
|
|
213
|
+
square matrix, ordered like the centroid table), used instead of
|
|
214
|
+
distances computed on ``basis``.
|
|
215
|
+
embed_clones
|
|
216
|
+
If ``True``, compute a UMAP of the clonotype centroids (stored in the
|
|
217
|
+
clone map as ``x``/``y``) for visualization.
|
|
218
|
+
random_state
|
|
219
|
+
UMAP seed and, unless overridden, neighbour-graph/Leiden seed.
|
|
220
|
+
key_added
|
|
221
|
+
Name of the ``obs`` column receiving the clone cluster label.
|
|
222
|
+
copy
|
|
223
|
+
Return a copy of ``adata`` instead of modifying in place.
|
|
224
|
+
preset
|
|
225
|
+
``"cohesive"`` (legacy defaults), ``"continuous"`` (report-style
|
|
226
|
+
starting point) or ``"discrete"`` (finer local partitions).
|
|
227
|
+
These are exploratory settings, not learned biological categories.
|
|
228
|
+
min_dist, spread, learning_rate
|
|
229
|
+
UMAP controls; explicit values override the preset. They change only
|
|
230
|
+
the display when ``cluster_on="distances"`` (the default).
|
|
231
|
+
umap_n_neighbors
|
|
232
|
+
Optional UMAP neighbour count independent of the clustering graph.
|
|
233
|
+
embedding_mode
|
|
234
|
+
``"precomputed"`` embeds clone distances directly (default).
|
|
235
|
+
``"distance_profiles"`` treats each distance-matrix row as Euclidean
|
|
236
|
+
features, as in the old notebook.
|
|
237
|
+
cluster_on
|
|
238
|
+
``"distances"`` builds the existing graph on original clone distances.
|
|
239
|
+
``"embedding"`` builds a Scanpy neighbour graph on the resulting
|
|
240
|
+
two-dimensional clone UMAP, then applies Leiden, as in the historical
|
|
241
|
+
notebook. In this explicit mode UMAP parameters can change clusters;
|
|
242
|
+
``embed_clones=True`` is required. Use ``n_neighbors=15`` and
|
|
243
|
+
``umap_n_neighbors=20`` for the notebook's separate neighbour counts.
|
|
244
|
+
cluster_random_state
|
|
245
|
+
Optional independent graph/Leiden seed. ``None`` uses ``random_state``.
|
|
246
|
+
The historical notebook uses UMAP seed 123 and Scanpy's default seed 0.
|
|
247
|
+
|
|
248
|
+
Returns
|
|
249
|
+
-------
|
|
250
|
+
``adata`` with ``obs[key_added]`` (categorical) and a clone-level table in
|
|
251
|
+
``adata.uns['threadfin']['clone_map']`` (one row per clonotype: size,
|
|
252
|
+
centroid, clone-cluster label, and embedding coordinates).
|
|
253
|
+
"""
|
|
254
|
+
settings = _resolve_parameters(
|
|
255
|
+
preset, n_neighbors=n_neighbors, resolution=resolution, min_dist=min_dist,
|
|
256
|
+
spread=spread, learning_rate=learning_rate,
|
|
257
|
+
)
|
|
258
|
+
n_neighbors, resolution = settings["n_neighbors"], settings["resolution"]
|
|
259
|
+
require_positive_int(min_clone_size, "min_clone_size")
|
|
260
|
+
if umap_n_neighbors is None:
|
|
261
|
+
umap_n_neighbors = n_neighbors
|
|
262
|
+
require_positive_int(umap_n_neighbors, "umap_n_neighbors")
|
|
263
|
+
if umap_n_neighbors < 2:
|
|
264
|
+
raise ValueError("umap_n_neighbors must be at least 2.")
|
|
265
|
+
if embedding_mode not in {"precomputed", "distance_profiles"}:
|
|
266
|
+
raise ValueError("embedding_mode must be 'precomputed' or 'distance_profiles'.")
|
|
267
|
+
if cluster_on not in {"distances", "embedding"}:
|
|
268
|
+
raise ValueError("cluster_on must be 'distances' or 'embedding'.")
|
|
269
|
+
if cluster_on == "embedding" and not embed_clones:
|
|
270
|
+
raise ValueError("cluster_on='embedding' requires embed_clones=True.")
|
|
271
|
+
if cluster_random_state is None:
|
|
272
|
+
cluster_random_state = random_state
|
|
273
|
+
elif (isinstance(cluster_random_state, (bool, np.bool_))
|
|
274
|
+
or not isinstance(cluster_random_state, (int, np.integer))
|
|
275
|
+
or cluster_random_state < 0):
|
|
276
|
+
raise ValueError("cluster_random_state must be a non-negative integer.")
|
|
277
|
+
if not np.isfinite(cdr3_weight) or not 0 <= cdr3_weight <= 1:
|
|
278
|
+
raise ValueError("cdr3_weight must be in [0, 1].")
|
|
279
|
+
if copy:
|
|
280
|
+
adata = adata.copy()
|
|
281
|
+
|
|
282
|
+
if basis == "joint":
|
|
283
|
+
joint = adata.uns.get(_CLONE_MAP_KEY, {}).get("joint")
|
|
284
|
+
if joint is None:
|
|
285
|
+
from .integrate import joint_embedding
|
|
286
|
+
|
|
287
|
+
joint = joint_embedding(adata, clone_key=clone_key)
|
|
288
|
+
centroids = joint[joint["n_cells"] >= min_clone_size].copy()
|
|
289
|
+
else:
|
|
290
|
+
centroids = clone_centroids(adata, clone_key=clone_key, basis=basis,
|
|
291
|
+
min_clone_size=min_clone_size)
|
|
292
|
+
n_clones = centroids.shape[0]
|
|
293
|
+
if n_clones < 5:
|
|
294
|
+
raise ValueError(
|
|
295
|
+
f"Only {n_clones} clones pass min_clone_size={min_clone_size}; "
|
|
296
|
+
"too few to cluster."
|
|
297
|
+
)
|
|
298
|
+
|
|
299
|
+
from scipy.spatial.distance import pdist, squareform
|
|
300
|
+
|
|
301
|
+
coord_cols = [c for c in centroids.columns if c != "n_cells"]
|
|
302
|
+
d_gex = squareform(pdist(centroids[coord_cols].to_numpy(), metric="euclidean"))
|
|
303
|
+
|
|
304
|
+
if distances is not None:
|
|
305
|
+
if cdr3_weight > 0:
|
|
306
|
+
raise ValueError("distances and cdr3_weight are mutually exclusive.")
|
|
307
|
+
d = np.asarray(distances, dtype=float)
|
|
308
|
+
dist = squareform(d) if d.ndim == 1 else d
|
|
309
|
+
if dist.shape != (n_clones, n_clones):
|
|
310
|
+
raise ValueError(
|
|
311
|
+
f"distances has shape {dist.shape}; expected ({n_clones}, "
|
|
312
|
+
f"{n_clones}) (or a condensed vector) matching the "
|
|
313
|
+
f"{n_clones} centroid clones."
|
|
314
|
+
)
|
|
315
|
+
elif cdr3_weight > 0:
|
|
316
|
+
if not 0 <= cdr3_weight <= 1:
|
|
317
|
+
raise ValueError("cdr3_weight must be in [0, 1].")
|
|
318
|
+
clone_info = adata.uns.get(_CLONE_INFO_KEY)
|
|
319
|
+
if clone_info is None or "cdr3" not in clone_info.columns:
|
|
320
|
+
raise ValueError(
|
|
321
|
+
"cdr3_weight > 0 requires clone-level CDR3 info. Run "
|
|
322
|
+
"threadfin.attach_bcr() first so adata.uns['threadfin_clones'] "
|
|
323
|
+
"exists."
|
|
324
|
+
)
|
|
325
|
+
from .sequence import blend_distances, cdr3_distance_matrix
|
|
326
|
+
|
|
327
|
+
cdr3 = clone_info["cdr3"].reindex(centroids.index)
|
|
328
|
+
d_seq = cdr3_distance_matrix(cdr3.tolist())
|
|
329
|
+
dist = blend_distances(d_gex, d_seq, weight=cdr3_weight)
|
|
330
|
+
else:
|
|
331
|
+
dist = d_gex
|
|
332
|
+
|
|
333
|
+
if (not np.isfinite(dist).all() or (dist < 0).any()
|
|
334
|
+
or not np.allclose(dist, dist.T) or not np.allclose(np.diag(dist), 0)):
|
|
335
|
+
raise ValueError("Clone distances must be finite, non-negative, symmetric, with a zero diagonal.")
|
|
336
|
+
|
|
337
|
+
graph_k = int(min(n_neighbors, n_clones - 1))
|
|
338
|
+
umap_k = int(min(umap_n_neighbors, n_clones - 1))
|
|
339
|
+
|
|
340
|
+
clone_map = centroids.copy()
|
|
341
|
+
clone_map.index.name = clone_key
|
|
342
|
+
|
|
343
|
+
if embed_clones:
|
|
344
|
+
import umap
|
|
345
|
+
|
|
346
|
+
reducer = umap.UMAP(
|
|
347
|
+
n_neighbors=umap_k,
|
|
348
|
+
metric="precomputed" if embedding_mode == "precomputed" else "euclidean",
|
|
349
|
+
min_dist=settings["min_dist"], spread=settings["spread"],
|
|
350
|
+
learning_rate=settings["learning_rate"], random_state=random_state,
|
|
351
|
+
)
|
|
352
|
+
clone_xy = reducer.fit_transform(dist)
|
|
353
|
+
clone_map["x"] = clone_xy[:, 0]
|
|
354
|
+
clone_map["y"] = clone_xy[:, 1]
|
|
355
|
+
|
|
356
|
+
if cluster_on == "embedding":
|
|
357
|
+
import scanpy as sc
|
|
358
|
+
from anndata import AnnData
|
|
359
|
+
|
|
360
|
+
clone_adata = AnnData(clone_xy)
|
|
361
|
+
sc.pp.neighbors(clone_adata, n_neighbors=graph_k, use_rep="X",
|
|
362
|
+
metric="euclidean", random_state=cluster_random_state)
|
|
363
|
+
sc.tl.leiden(clone_adata, resolution=resolution, random_state=cluster_random_state,
|
|
364
|
+
flavor="leidenalg", directed=True, n_iterations=-1)
|
|
365
|
+
labels = clone_adata.obs["leiden"].astype(str).to_numpy()
|
|
366
|
+
else:
|
|
367
|
+
labels = _leiden_on_distances(
|
|
368
|
+
dist, n_neighbors=graph_k, resolution=resolution, random_state=cluster_random_state
|
|
369
|
+
)
|
|
370
|
+
clone_map[key_added] = pd.Categorical(labels)
|
|
371
|
+
|
|
372
|
+
# map back to cells (vectorized)
|
|
373
|
+
mapping = clone_map[key_added]
|
|
374
|
+
adata.obs[key_added] = adata.obs[clone_key].map(mapping).astype("category")
|
|
375
|
+
|
|
376
|
+
adata.uns.setdefault(_CLONE_MAP_KEY, {})["clone_map"] = clone_map
|
|
377
|
+
adata.uns[_CLONE_MAP_KEY]["clone_distances"] = dist
|
|
378
|
+
adata.uns[_CLONE_MAP_KEY]["clonotype_recluster"] = {
|
|
379
|
+
"basis": basis,
|
|
380
|
+
"min_clone_size": min_clone_size,
|
|
381
|
+
"n_neighbors": n_neighbors,
|
|
382
|
+
"effective_n_neighbors": graph_k,
|
|
383
|
+
"resolution": resolution,
|
|
384
|
+
"preset": preset,
|
|
385
|
+
"min_dist": settings["min_dist"],
|
|
386
|
+
"spread": settings["spread"],
|
|
387
|
+
"learning_rate": settings["learning_rate"],
|
|
388
|
+
"umap_n_neighbors": umap_n_neighbors,
|
|
389
|
+
"effective_umap_n_neighbors": umap_k,
|
|
390
|
+
"embedding_mode": embedding_mode,
|
|
391
|
+
"cluster_on": cluster_on,
|
|
392
|
+
"graph_method": "scanpy_umap_connectivities" if cluster_on == "embedding" else "self_scaled_gaussian",
|
|
393
|
+
"embed_clones": bool(embed_clones),
|
|
394
|
+
"cdr3_weight": cdr3_weight,
|
|
395
|
+
"random_state": random_state,
|
|
396
|
+
"cluster_random_state": cluster_random_state,
|
|
397
|
+
"n_clones_clustered": int(n_clones),
|
|
398
|
+
"n_clone_clusters": int(len(set(labels))),
|
|
399
|
+
}
|
|
400
|
+
print(
|
|
401
|
+
f"[threadfin] {n_clones} clones -> {len(set(labels))} clone clusters "
|
|
402
|
+
f"({key_added!r} added to obs, clone map in uns['threadfin'])."
|
|
403
|
+
)
|
|
404
|
+
return adata
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
def clonal_pseudotime(
|
|
408
|
+
adata,
|
|
409
|
+
clone_key: str = "clone_id",
|
|
410
|
+
root: str | None = None,
|
|
411
|
+
key_added: str = "clonal_pseudotime",
|
|
412
|
+
random_state: int = 0,
|
|
413
|
+
use_clone_graph: bool = False,
|
|
414
|
+
):
|
|
415
|
+
"""Diffusion pseudotime over the clonotype graph.
|
|
416
|
+
|
|
417
|
+
Runs scanpy's diffusion pseudotime (Haghverdi et al., 2016) on the
|
|
418
|
+
clonotype kNN graph built by :func:`clonotype_recluster`, then maps the
|
|
419
|
+
value back to cells. Requires a prior :func:`clonotype_recluster` call.
|
|
420
|
+
|
|
421
|
+
Parameters
|
|
422
|
+
----------
|
|
423
|
+
adata
|
|
424
|
+
AnnData after :func:`clonotype_recluster`.
|
|
425
|
+
clone_key
|
|
426
|
+
``obs`` column holding the clonotype id.
|
|
427
|
+
root
|
|
428
|
+
Root clonotype id. If ``None``, the clone with the minimal first
|
|
429
|
+
centroid coordinate is used (deterministic default; pass an explicit
|
|
430
|
+
clone id of a known naive/early state for interpretable direction).
|
|
431
|
+
key_added
|
|
432
|
+
Name of the ``obs`` column receiving the pseudotime.
|
|
433
|
+
random_state
|
|
434
|
+
Seed.
|
|
435
|
+
use_clone_graph
|
|
436
|
+
If ``True``, run DPT on the kNN graph implied by the clone distances
|
|
437
|
+
stored by :func:`clonotype_recluster` (adaptive-Gaussian kernel over
|
|
438
|
+
the stored distance matrix) instead of recomputing neighbors on the
|
|
439
|
+
centroid coordinates. Falls back to the default behavior with a
|
|
440
|
+
warning when no stored distances are available.
|
|
441
|
+
|
|
442
|
+
Returns
|
|
443
|
+
-------
|
|
444
|
+
``adata`` with ``obs[key_added]``; clone-level values are added to the
|
|
445
|
+
clone map in ``adata.uns['threadfin']['clone_map']``.
|
|
446
|
+
"""
|
|
447
|
+
import scanpy as sc
|
|
448
|
+
from anndata import AnnData
|
|
449
|
+
|
|
450
|
+
clone_map = adata.uns.get(_CLONE_MAP_KEY, {}).get("clone_map")
|
|
451
|
+
if clone_map is None:
|
|
452
|
+
raise ValueError("Run threadfin.clonotype_recluster() first.")
|
|
453
|
+
|
|
454
|
+
coord_cols = [c for c in clone_map.columns if c not in ("n_cells",) and clone_map[c].dtype != "category" and c not in ("x", "y")]
|
|
455
|
+
coords = clone_map[coord_cols].to_numpy()
|
|
456
|
+
|
|
457
|
+
ad = AnnData(coords)
|
|
458
|
+
n_neighbors = int(min(15, ad.n_obs - 1))
|
|
459
|
+
stored = adata.uns.get(_CLONE_MAP_KEY, {}).get("clone_distances")
|
|
460
|
+
if use_clone_graph and stored is not None and stored.shape == (ad.n_obs, ad.n_obs):
|
|
461
|
+
import scipy.sparse as sp
|
|
462
|
+
from sklearn.neighbors import NearestNeighbors
|
|
463
|
+
|
|
464
|
+
nn = NearestNeighbors(
|
|
465
|
+
n_neighbors=n_neighbors + 1, metric="precomputed"
|
|
466
|
+
).fit(stored)
|
|
467
|
+
d_knn, idx = nn.kneighbors(stored)
|
|
468
|
+
d_knn, idx = d_knn[:, 1:], idx[:, 1:] # drop self
|
|
469
|
+
sigma = np.maximum(d_knn[:, -1:], 1e-10)
|
|
470
|
+
w = np.exp(-(d_knn**2) / (sigma**2))
|
|
471
|
+
rows = np.repeat(np.arange(ad.n_obs), n_neighbors)
|
|
472
|
+
conn = sp.csr_matrix(
|
|
473
|
+
(w.ravel(), (rows, idx.ravel())), shape=(ad.n_obs, ad.n_obs)
|
|
474
|
+
)
|
|
475
|
+
conn = conn.maximum(conn.T)
|
|
476
|
+
dmat = sp.csr_matrix(
|
|
477
|
+
(d_knn.ravel(), (rows, idx.ravel())), shape=(ad.n_obs, ad.n_obs)
|
|
478
|
+
)
|
|
479
|
+
ad.uns["neighbors"] = {
|
|
480
|
+
"connectivities": conn,
|
|
481
|
+
"distances": dmat.maximum(dmat.T),
|
|
482
|
+
"params": {"n_neighbors": n_neighbors, "method": "umap",
|
|
483
|
+
"metric": "precomputed"},
|
|
484
|
+
}
|
|
485
|
+
else:
|
|
486
|
+
if use_clone_graph:
|
|
487
|
+
warnings.warn(
|
|
488
|
+
"use_clone_graph=True but no stored clone distances found; "
|
|
489
|
+
"falling back to centroid-coordinate neighbors.",
|
|
490
|
+
stacklevel=2,
|
|
491
|
+
)
|
|
492
|
+
sc.pp.neighbors(ad, n_neighbors=n_neighbors)
|
|
493
|
+
if root is None:
|
|
494
|
+
ad.uns["iroot"] = int(np.argmin(coords[:, 0]))
|
|
495
|
+
else:
|
|
496
|
+
if root not in clone_map.index:
|
|
497
|
+
raise KeyError(f"root clone {root!r} not found in clone map.")
|
|
498
|
+
ad.uns["iroot"] = int(clone_map.index.get_loc(root))
|
|
499
|
+
sc.tl.dpt(ad)
|
|
500
|
+
|
|
501
|
+
pt = ad.obs["dpt_pseudotime"].replace([np.inf], np.nan)
|
|
502
|
+
clone_map = clone_map.copy()
|
|
503
|
+
clone_map[key_added] = pt.to_numpy()
|
|
504
|
+
|
|
505
|
+
adata.obs[key_added] = pd.to_numeric(
|
|
506
|
+
adata.obs[clone_key].map(clone_map[key_added]), errors="coerce"
|
|
507
|
+
)
|
|
508
|
+
adata.uns[_CLONE_MAP_KEY]["clone_map"] = clone_map
|
|
509
|
+
print(f"[threadfin] clonal pseudotime added to obs[{key_added!r}].")
|
|
510
|
+
return adata
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
def bcr_reclustering(adata, bcr_table=None, **kwargs):
|
|
514
|
+
"""Backward-compatible alias for the original Threadfin API.
|
|
515
|
+
|
|
516
|
+
.. deprecated:: 1.0.0
|
|
517
|
+
Use :func:`threadfin.attach_bcr` + :func:`threadfin.clonotype_recluster`.
|
|
518
|
+
"""
|
|
519
|
+
warnings.warn(
|
|
520
|
+
"bcr_reclustering() is deprecated; use threadfin.attach_bcr() followed "
|
|
521
|
+
"by threadfin.clonotype_recluster().",
|
|
522
|
+
DeprecationWarning,
|
|
523
|
+
stacklevel=2,
|
|
524
|
+
)
|
|
525
|
+
from .io import attach_bcr, build_clone_key
|
|
526
|
+
|
|
527
|
+
if bcr_table is not None and "clone_id" not in adata.obs.columns:
|
|
528
|
+
if "clone_id" not in bcr_table.columns:
|
|
529
|
+
bcr_table = build_clone_key(bcr_table)
|
|
530
|
+
attach_bcr(adata, bcr_table)
|
|
531
|
+
return clonotype_recluster(adata, **kwargs)
|