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/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)