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