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/dandelion.py ADDED
@@ -0,0 +1,458 @@
1
+ """Clone definition delegated to Dandelion, so heavy **and** light chains are used.
2
+
3
+ This is Threadfin's clone definition. A B-cell clone is one V(D)J rearrangement of *both*
4
+ chains, and two cells whose heavy chains are similar but whose light chains are unrelated are
5
+ not the same clone. Dandelion implements the paired definition and is a maintained, cited
6
+ package, so Threadfin calls it rather than re-implementing clone calling:
7
+ :func:`define_clones_dandelion` is the entry point, :func:`read_contigs` normalises a 10x
8
+ CSV / AIRR TSV / contig-level DataFrame for it. (Threadfin's earlier heavy-chain-only caller,
9
+ :func:`threadfin.clones.define_clones`, is deprecated.)
10
+
11
+ Dandelion's clone id is composite — ``B_VDJ_105_9_7_VJ_261_2_1`` — the heavy (VDJ) V/J/junction group and
12
+ the light (VJ) group, so the pairing is visible in the label.
13
+
14
+ What changes when the light chain is used. Measured on GSE286215 experiment 1 (23,259 cells):
15
+
16
+ =========================== =========== ===========
17
+ quantity heavy only heavy+light
18
+ =========================== =========== ===========
19
+ clones 20,100 22,351
20
+ clones with >= 2 cells 801 616
21
+ largest clone 8 cells 33 cells
22
+ =========================== =========== ===========
23
+
24
+ Roughly a quarter of the analysable clone population is lost, because a clone now has to agree on both
25
+ chains. That is the price of the stricter definition and it is reported, not hidden.
26
+
27
+ Not every deposit carries a light chain — GSE175522 (influenza vaccine) is heavy only — so
28
+ ``use_light_chain`` is a parameter rather than an assumption, and the setting is recorded in the result so
29
+ a figure can state which definition produced it.
30
+
31
+ Dandelion is an optional dependency::
32
+
33
+ pip install "threadfin[dandelion]" # or: pip install sc-dandelion "matplotlib<3.9"
34
+
35
+ Dandelion 0.5.7 imports ``matplotlib.cm.get_cmap``, which matplotlib 3.9 removed, but its package metadata
36
+ does not pin matplotlib, so the extra pins ``matplotlib < 3.9`` for it.
37
+
38
+ Dandelion's clone assignment depends on the order in which Python iterates over sets of sequences, which is
39
+ randomised in every new Python session unless the environment variable ``PYTHONHASHSEED`` is fixed before
40
+ Python starts. Repeated runs therefore differ by a few clones (GSE287123: 8,729 or 8,731 clones from the same
41
+ contigs). Set ``PYTHONHASHSEED=0`` (for a Jupyter kernel: ``python -m ipykernel install ... --env
42
+ PYTHONHASHSEED 0``) when clone ids must be reproducible; the value in use is recorded in the result.
43
+ """
44
+
45
+ from __future__ import annotations
46
+
47
+ import contextlib
48
+ import io
49
+ import os
50
+ import warnings
51
+ from pathlib import Path
52
+
53
+ import pandas as pd
54
+
55
+ from ._utils import log
56
+
57
+ __all__ = ["define_clones_dandelion", "read_contigs"]
58
+
59
+ REQUIRED = ("cell_id", "v_call", "j_call", "junction")
60
+
61
+ TENX_TO_AIRR = {"barcode": "cell_id", "chain": "locus", "v_gene": "v_call", "d_gene": "d_call",
62
+ "j_gene": "j_call", "c_gene": "c_call", "cdr3_nt": "junction", "cdr3": "junction_aa",
63
+ "contig_id": "sequence_id", "umis": "umi_count", "reads": "consensus_count"}
64
+
65
+
66
+ def _contigs_from_scirpy(obj, airr_mod: str = "airr", airr_key: str = "airr") -> pd.DataFrame:
67
+ """One row per receptor chain from a scirpy AnnData or MuData (``obsm['airr']``)."""
68
+ try:
69
+ import scirpy as ir
70
+ except ImportError as exc: # pragma: no cover - only without the optional dependency
71
+ raise ImportError("Reading receptor data from a scirpy AnnData/MuData needs scirpy: pip install scirpy") from exc
72
+ try:
73
+ cells = ir.io.to_airr_cells(obj, airr_mod=airr_mod, airr_key=airr_key)
74
+ except (KeyError, ValueError) as exc:
75
+ raise ValueError("This AnnData/MuData holds no receptor data where scirpy keeps it (obsm['airr'] of the "
76
+ "'airr' modality). Pass the object returned by scirpy.io.read_10x_vdj / read_airr, or the "
77
+ "contig table itself.") from exc
78
+ rows = [{**chain, "cell_id": cell.cell_id} for cell in cells for chain in cell.chains]
79
+ if not rows:
80
+ raise ValueError("The scirpy object holds no receptor chains.")
81
+ return pd.DataFrame(rows)
82
+
83
+
84
+ def read_contigs(bcr, obs_names=None) -> pd.DataFrame:
85
+ """Contig-level AIRR table from a path or a DataFrame, for :func:`define_clones_dandelion`.
86
+
87
+ Accepts a Cell Ranger ``filtered_contig_annotations.csv`` (``.csv`` / ``.csv.gz``), an AIRR
88
+ rearrangement ``.tsv`` / ``.tsv.gz``, a scirpy AnnData or MuData (receptor data in ``obsm['airr']``),
89
+ or an already contig-level DataFrame (one row per chain,
90
+ with ``cell_id``/``barcode``, ``v_call``/``v_gene``, ``j_call``/``j_gene`` and
91
+ ``junction``/``cdr3_nt``). A per-cell table (one row per cell, e.g. the output of
92
+ :func:`threadfin.read_bcr`) is refused: the paired heavy + light clone definition needs the
93
+ individual chains. When a table has both a 10x ``barcode`` and an AIRR ``cell_id`` column, the one that
94
+ matches more of ``obs_names`` (by default ``cell_id``) names the cells.
95
+ """
96
+ if not isinstance(bcr, (pd.DataFrame, str, Path)) and (hasattr(bcr, "mod") or hasattr(bcr, "obsm")):
97
+ bcr = _contigs_from_scirpy(bcr) # scirpy AnnData / MuData
98
+ if isinstance(bcr, pd.DataFrame):
99
+ t = bcr.copy()
100
+ if "cell_id" not in t.columns and "barcode" not in t.columns:
101
+ raise ValueError(
102
+ "A per-cell BCR table cannot be used for clone definition: Threadfin's clone "
103
+ "definition is Dandelion's paired heavy + light definition, which needs the "
104
+ "contig-level table (one row per chain, with a cell_id/barcode column). Pass the "
105
+ "path to filtered_contig_annotations.csv or airr_rearrangement.tsv, or precompute "
106
+ "clone ids with threadfin.define_clones_dandelion and put them in "
107
+ "adata.obs['clone_id'].")
108
+ else:
109
+ path = str(bcr)
110
+ if path.endswith((".tsv", ".tsv.gz")):
111
+ t = pd.read_csv(path, sep="\t", low_memory=False)
112
+ else:
113
+ t = pd.read_csv(path, low_memory=False)
114
+ if "barcode" in t.columns and "cell_id" in t.columns:
115
+ # both a 10x barcode and an AIRR cell id: keep the one that names the cells of adata (by default the
116
+ # AIRR cell_id), so that renaming cannot leave two columns called cell_id
117
+ keep = "cell_id"
118
+ if obs_names is not None:
119
+ names = pd.Index(obs_names).astype(str)
120
+ hits = {c: int(t[c].astype(str).isin(names).sum()) for c in ("barcode", "cell_id")}
121
+ keep = "barcode" if hits["barcode"] > hits["cell_id"] else "cell_id"
122
+ t = t.drop(columns="cell_id" if keep == "barcode" else "barcode")
123
+ # 10x column names become AIRR names, unless the AIRR column is already there
124
+ t = t.rename(columns={k: v for k, v in TENX_TO_AIRR.items() if k in t.columns and v not in t.columns})
125
+ t = t.loc[:, ~t.columns.duplicated()]
126
+ if "is_cell" in t.columns:
127
+ t = t[t["is_cell"].astype(str).str.upper().isin(("TRUE", "T", "1"))]
128
+ if "high_confidence" in t.columns:
129
+ t = t[t["high_confidence"].astype(str).str.upper().isin(("TRUE", "T", "1"))]
130
+ missing = [c for c in REQUIRED if c not in t.columns]
131
+ if missing:
132
+ raise ValueError(f"contigs is missing {missing}; this function needs a contig-level AIRR table.")
133
+ return t
134
+
135
+
136
+ def _quiet():
137
+ """Dandelion prints a notice ("The AIRR data needs to undergo sanitization ...") for every table whose
138
+ boolean columns are not spelled T/F, twice per donor even with ``verbose=False``; hide it."""
139
+ return contextlib.redirect_stdout(io.StringIO())
140
+
141
+
142
+ def _dandelion_version(ddl) -> str:
143
+ """Installed version of sc-dandelion. Its own ``__version__`` asks setuptools-scm first, which reports the
144
+ version of whatever git repository the current directory is in."""
145
+ try:
146
+ from importlib.metadata import version
147
+
148
+ return version("sc-dandelion")
149
+ except Exception:
150
+ return str(getattr(ddl, "__version__", "unknown"))
151
+
152
+
153
+ def _require_dandelion():
154
+ try:
155
+ with warnings.catch_warnings():
156
+ # Dandelion imports nxviz, which prints a long notice about its own API change on import
157
+ warnings.filterwarnings("ignore", message=r"\s*nxviz has a new API")
158
+ import dandelion as ddl
159
+ except ImportError as exc: # pragma: no cover - exercised only without the optional dependency
160
+ raise ImportError(
161
+ "Clone calling needs the Dandelion package: pip install \"threadfin[dandelion] @ "
162
+ "git+https://github.com/Reynold4k/Threadfin.git\" (or: pip install sc-dandelion \"matplotlib<3.9\"; "
163
+ "Dandelion 0.5.7 needs matplotlib < 3.9 but does not say so). Alternatively call clones elsewhere and "
164
+ "put the ids in adata.obs['clone_id']."
165
+ ) from exc
166
+ return ddl
167
+
168
+
169
+ def _locus(contigs: pd.DataFrame) -> pd.Series:
170
+ """The chain of each contig, from `locus` when present and from the V call otherwise."""
171
+ if "locus" in contigs.columns and contigs["locus"].notna().any():
172
+ return contigs["locus"].astype(str).str.upper()
173
+ return contigs["v_call"].astype(str).str.upper().str[:3]
174
+
175
+
176
+ #: chains that carry a D segment: the BCR heavy chain and the TCR beta and delta chains
177
+ VDJ_LOCI = ("IGH", "TRB", "TRD")
178
+
179
+
180
+ def _receptor_name(locus: pd.Series) -> str | None:
181
+ """'BCR', 'TCR' or 'BCR or TCR': the receptor of the contigs. A few contigs of the other kind (a stray B cell
182
+ among T cells) do not count; a kind needs at least 5 % of the IG and TR contigs."""
183
+ kind = locus.astype(str).str.upper().str[:2].value_counts()
184
+ kind = kind[kind.index.isin(["IG", "TR"])]
185
+ share = kind / max(int(kind.sum()), 1)
186
+ return " or ".join(name for prefix, name in (("IG", "BCR"), ("TR", "TCR")) if share.get(prefix, 0) >= 0.05) or None
187
+ #: Dandelion's own junction-identity defaults: B-cell clones tolerate somatic hypermutation, T-cell clones do not
188
+ DEFAULT_IDENTITY = {"ig": 0.85, "tr-ab": 1.0, "tr-gd": 1.0}
189
+
190
+
191
+ def _cells_with_heavy_chain(t: pd.DataFrame, cell_key: str = "cell_id") -> pd.Index:
192
+ """Cells that carry at least one VDJ chain (BCR heavy chain, TCR beta or delta) in a contig-level table."""
193
+ locus = t["locus"] if "locus" in t.columns else _locus(t)
194
+ return pd.Index(pd.unique(t.loc[locus.astype(str).str.upper().isin(VDJ_LOCI).to_numpy(), cell_key].astype(str)))
195
+
196
+
197
+ def _fill_junction_aa(t: pd.DataFrame, *, verbose: bool = True) -> pd.DataFrame:
198
+ """Make sure `junction_aa` carries a real sequence for every contig.
199
+
200
+ ``find_clones`` groups on ``junction_aa`` by default, so a blank entry is not a missing optional
201
+ field — it is a grouping key shared with every other blank entry. Filling the column with an empty
202
+ string therefore merges every cell that happens to agree on V gene, J gene and junction length:
203
+ GSE175522 ships ``junction_aa`` entirely empty and that produced a single 972-cell "clone" and
204
+ dropped the dataset's clonal coherence from 0.558 to 0.050 before it was caught. Translate the
205
+ nucleotide junction instead, which is the sequence Dandelion would have grouped on anyway.
206
+ """
207
+ from .sequence import translate_nt
208
+
209
+ blank = {"", "nan", "none", "na", "null", "out_of_frame", "partial", "?", "-"}
210
+ if "junction_aa" in t.columns:
211
+ raw = t["junction_aa"].astype("object")
212
+ # missing values become "" explicitly: with pandas >= 3, astype(str) keeps NaN as missing
213
+ aa = raw.where(raw.notna(), "").astype(str).str.strip()
214
+ aa = aa.where(~aa.str.lower().isin(blank), "")
215
+ else:
216
+ aa = pd.Series("", index=t.index, dtype="object")
217
+ need = aa.eq("")
218
+ if need.any():
219
+ nt = t.loc[need, "junction"].astype(str)
220
+ aa.loc[need] = [translate_nt(s) or "" for s in nt]
221
+ filled = int((aa.loc[need] != "").sum())
222
+ if verbose:
223
+ log(f"junction_aa was blank for {int(need.sum()):,} of {len(t):,} contigs; translated the "
224
+ f"nucleotide junction for {filled:,} of them")
225
+ t = t.copy()
226
+ t["junction_aa"] = aa
227
+ still = t["junction_aa"].eq("")
228
+ if still.any():
229
+ if still.mean() > 0.05:
230
+ raise ValueError(
231
+ f"{int(still.sum()):,} of {len(t):,} contigs have neither junction_aa nor a translatable "
232
+ "junction. Clone calling would group all of them together on V gene, J gene and junction "
233
+ "length alone, so it is refused; supply junction_aa.")
234
+ if verbose:
235
+ log(f"dropping {int(still.sum()):,} contigs with no usable junction_aa")
236
+ t = t[~still]
237
+ return t
238
+
239
+
240
+ def _unique_sequence_ids(t: pd.DataFrame, verbose: bool = True) -> pd.DataFrame:
241
+ """Make contig ids unique. Cell Ranger names contigs after the barcode (``AAAC...-1_contig_1``), so two
242
+ libraries of one donor can carry the same id for different cells; Dandelion indexes contigs by this id and
243
+ would mix those cells' chains. Duplicated ids are prefixed with the cell id."""
244
+ sid = t["sequence_id"].astype(str)
245
+ if not sid.duplicated().any():
246
+ return t
247
+ t = t.copy()
248
+ dup = sid.duplicated(keep=False)
249
+ t["sequence_id"] = sid.where(~dup, t["cell_id"].astype(str) + "|" + sid)
250
+ if t["sequence_id"].duplicated().any(): # the same cell listed a contig twice
251
+ t["sequence_id"] = t["sequence_id"] + "_" + t.groupby("sequence_id").cumcount().astype(str)
252
+ if verbose:
253
+ log(f"{int(dup.sum()):,} contigs shared their id with a contig of another cell (barcode reused across "
254
+ "libraries); they were renamed after their cell")
255
+ return t
256
+
257
+
258
+ def define_clones_dandelion(
259
+ contigs: pd.DataFrame,
260
+ *,
261
+ use_light_chain: bool = True,
262
+ identity: float | dict | None = None,
263
+ donor_key: str | None = None,
264
+ cell_key: str = "cell_id",
265
+ productive_only: bool = True,
266
+ require_heavy_chain: bool = True,
267
+ check_contigs: bool = False,
268
+ out_col: str = "clone_id",
269
+ verbose: bool = True,
270
+ ) -> pd.Series:
271
+ """Call clones with Dandelion and return one clone id per cell.
272
+
273
+ Parameters
274
+ ----------
275
+ contigs
276
+ **Contig-level** AIRR table — one row per receptor chain, not per cell — with at least
277
+ ``cell_id``, ``v_call``, ``j_call`` and ``junction``. This is what Cell Ranger's
278
+ ``airr_rearrangement.tsv`` and ``filtered_contig_annotations.csv`` provide. BCR and TCR contigs are
279
+ both accepted.
280
+ use_light_chain
281
+ ``True`` (default) defines a clone on both chains (BCR heavy + light; TCR beta + alpha), which is
282
+ Dandelion's own definition. ``False`` keeps only the VDJ chain (IGH, TRB, TRD), for deposits with no
283
+ light (alpha) chain; the choice is recorded in ``Series.attrs['use_light_chain']``.
284
+ identity
285
+ Junction amino-acid identity required within a clone, passed to ``dandelion.tl.find_clones``.
286
+ ``None`` (default) uses Dandelion's defaults: 0.85 for BCR, which allows for somatic hypermutation,
287
+ and 1.0 (identical junctions) for TCR, which does not mutate. A number applies to every chain type;
288
+ a dict sets them separately (keys ``"ig"``, ``"tr-ab"``, ``"tr-gd"``).
289
+ donor_key
290
+ Column naming the individual. When given, clones are called separately within each donor, so no
291
+ clone can span two animals or participants; the donor is prefixed to the id.
292
+ productive_only
293
+ Drop non-productive rearrangements before calling.
294
+ require_heavy_chain
295
+ ``True`` (default) returns clone ids only for cells with a (productive) VDJ chain — the BCR heavy
296
+ chain, or the TCR beta or delta chain. Dandelion
297
+ also groups cells whose heavy chain was not recovered, by their light chain alone (ids such as
298
+ ``B_VJ_...``). Light-chain rearrangements are far less diverse than heavy-chain ones, so these
299
+ groups join unrelated cells and are not clones; in GSE287123 they were 5,276 of 21,939 cells and
300
+ 740 of 2,626 groups of two or more cells. ``False`` keeps them.
301
+ check_contigs
302
+ ``True`` runs Dandelion's own contig check (``dandelion.pp.check_contigs``) before the clones are
303
+ called, as Dandelion's tutorial does: identical contigs of a cell are merged, a cell with several
304
+ heavy chains keeps the one that clearly dominates in UMIs (IgM with IgD is allowed; two light chains
305
+ are allowed too, as in allelic inclusion), and cells without a dominant heavy chain — often doublets —
306
+ are set aside instead of joining clones. It needs UMI
307
+ counts (``umi_count`` or ``duplicate_count``); without them every cell with two chains of one kind is
308
+ set aside. Read counts (``consensus_count``) break ties and are replaced by the UMI count when absent.
309
+ ``False`` (default, as in the manuscript) calls clones on all productive contigs.
310
+
311
+ Returns
312
+ -------
313
+ Series indexed by cell id. ``attrs`` records the settings, the resulting clone counts (with
314
+ ``n_cells_with_combined_id``, the cells with two productive chains of one kind, and
315
+ ``n_cells_with_combined_id_two_heavy``, those among them with two heavy chains), and the
316
+ ``PYTHONHASHSEED`` in use (``None`` when unset; clone calls are then not bit-reproducible between Python
317
+ sessions, see the module notes).
318
+ """
319
+ required = [cell_key if c == "cell_id" else c for c in REQUIRED]
320
+ missing = [c for c in required if c not in contigs.columns]
321
+ if missing:
322
+ raise ValueError(f"contigs is missing {missing}; this function needs a contig-level AIRR table "
323
+ f"(cell_key={cell_key!r} names the column with the cell barcode).")
324
+ ddl = _require_dandelion()
325
+
326
+ t = contigs.copy()
327
+ t[cell_key] = t[cell_key].astype(str)
328
+ if productive_only and "productive" in t.columns:
329
+ keep = t["productive"].astype(str).str.strip().str.upper().isin(("T", "TRUE", "1", "1.0"))
330
+ t = t[keep]
331
+ t["locus"] = _locus(t)
332
+ if not use_light_chain:
333
+ t = t[t["locus"].isin(VDJ_LOCI)]
334
+ if t.empty:
335
+ raise ValueError("No heavy-chain (IGH) or TCR beta/delta contigs left; check the locus or v_call column.")
336
+ if identity is None:
337
+ identity = dict(DEFAULT_IDENTITY)
338
+ # Dandelion writes its own clone_id; keep any existing one under a different name
339
+ if "clone_id" in t.columns:
340
+ t = t.rename(columns={"clone_id": "clone_id_original"})
341
+ if cell_key != "cell_id":
342
+ # the caller's key becomes `cell_id`; any original `cell_id` is kept under another name so the
343
+ # rename cannot produce two columns with the same label
344
+ if "cell_id" in t.columns:
345
+ t = t.rename(columns={"cell_id": "cell_id_contig"})
346
+ t = t.rename(columns={cell_key: "cell_id"})
347
+ t = t.loc[:, ~t.columns.duplicated()]
348
+ # AIRR requires a unique per-contig id and Dandelion insists on it, but several public deposits
349
+ # (GSE286215 experiment 2 among them) ship without one. Build it from the cell and the chain.
350
+ # Dandelion also needs a per-contig abundance; TRUST4 reports and some deposits give only a read
351
+ # count, so fall back through the usual names before giving every contig equal weight.
352
+ if "umi_count" not in t.columns and "duplicate_count" not in t.columns:
353
+ src = next((c for c in ("consensus_count", "reads", "#count", "count") if c in t.columns), None)
354
+ t["umi_count"] = pd.to_numeric(t[src], errors="coerce").fillna(1) if src else 1
355
+ if "sequence_id" not in t.columns or t["sequence_id"].isna().all():
356
+ t = t.reset_index(drop=True)
357
+ t["sequence_id"] = (t["cell_id"].astype(str) + "_" + t["locus"].astype(str) + "_"
358
+ + t.groupby(["cell_id", "locus"]).cumcount().add(1).astype(str))
359
+ t = _unique_sequence_ids(t, verbose=verbose)
360
+ # Dandelion validates a fixed column list on construction. Deposits legitimately omit some of them
361
+ # (GSE195673 has no constant-region call), and an absent optional field should not stop clone calling.
362
+ for col in ("d_call", "c_call", "productive"):
363
+ if col not in t.columns:
364
+ t[col] = "T" if col == "productive" else ""
365
+ t = _fill_junction_aa(t, verbose=verbose)
366
+ with_heavy = set()
367
+
368
+ groups = [(None, t)] if donor_key is None else list(t.groupby(donor_key, observed=True))
369
+ out, n_ambiguous, combined, two_heavy = {}, 0, set(), set()
370
+ if check_contigs and "umi_count" in t.columns and pd.to_numeric(t["umi_count"], errors="coerce").nunique() <= 1:
371
+ warnings.warn("check_contigs=True but the contigs have no UMI counts, so no chain can dominate: every cell "
372
+ "with two chains of one kind will be set aside.", UserWarning, stacklevel=2)
373
+ if check_contigs and "consensus_count" not in t.columns:
374
+ # the check breaks ties in UMIs on read counts; without them the UMI count stands in
375
+ umis = t["umi_count"] if "umi_count" in t.columns else t["duplicate_count"]
376
+ t["consensus_count"] = pd.to_numeric(umis, errors="coerce").fillna(1).clip(lower=1)
377
+ for donor, sub in groups:
378
+ if sub["cell_id"].nunique() < 2:
379
+ continue
380
+ with _quiet():
381
+ vdj = ddl.Dandelion(sub.reset_index(drop=True))
382
+ if check_contigs:
383
+ with _quiet(), warnings.catch_warnings():
384
+ warnings.simplefilter("ignore", FutureWarning)
385
+ # returns the Dandelion object alone, or (Dandelion, AnnData) when an AnnData is passed
386
+ checked = ddl.pp.check_contigs(vdj, productive_only=productive_only, verbose=False)
387
+ vdj = checked[0] if isinstance(checked, tuple) else checked
388
+ n_ambiguous += int(vdj.data["ambiguous"].astype(str).eq("T").sum()) if "ambiguous" in vdj.data else 0
389
+ # find_clones ignores contigs flagged ambiguous, so a cell whose heavy chains were all set aside has
390
+ # no heavy chain left to call a clone on
391
+ kept = vdj.data if "ambiguous" not in vdj.data else vdj.data[vdj.data["ambiguous"].astype(str) != "T"]
392
+ with_heavy.update(_cells_with_heavy_chain(kept))
393
+ heavy = kept[_locus(kept).isin(VDJ_LOCI).to_numpy()].drop_duplicates(["cell_id", "v_call", "j_call", "junction_aa"])
394
+ n_heavy = heavy.groupby("cell_id").size()
395
+ two_heavy.update(n_heavy.index[n_heavy >= 2].astype(str))
396
+ with _quiet():
397
+ ddl.tl.find_clones(vdj, identity=identity, verbose=False)
398
+ # a cell Dandelion could not place (e.g. all its heavy chains set aside by the check) gets an empty id
399
+ clone_ids = vdj.data["clone_id"]
400
+ called = vdj.data[clone_ids.notna() & clone_ids.astype(str).str.strip().ne("")]
401
+ per_cell = called.groupby("cell_id")["clone_id"].first()
402
+ # Dandelion joins the clones of a cell with two productive chains of one kind ("a|b")
403
+ combined.update(per_cell.index[per_cell.astype(str).str.contains("|", regex=False)].astype(str))
404
+ prefix = "" if donor is None else f"{donor}|"
405
+ for cell, clone in per_cell.items():
406
+ out[str(cell)] = f"{prefix}{clone}"
407
+ if verbose and donor is not None:
408
+ log(f" {donor}: {per_cell.nunique()} clones over {len(per_cell)} cells")
409
+
410
+ s = pd.Series(out, name=out_col, dtype="object")
411
+ s.index.name = "cell_id"
412
+ n_without_heavy = int((~s.index.isin(with_heavy)).sum())
413
+ if require_heavy_chain and n_without_heavy:
414
+ s = s[s.index.isin(with_heavy)]
415
+ if verbose:
416
+ log(f"{n_without_heavy:,} cells without a heavy (or TCR beta/delta) chain were grouped by their light "
417
+ "(alpha) chain alone; they are left without a clone (require_heavy_chain=False keeps them)")
418
+ sizes = s.value_counts()
419
+ n_combined = int(s.index.isin(combined).sum())
420
+ n_combined_heavy = int((s.index.isin(combined) & s.index.isin(two_heavy)).sum())
421
+ s.attrs.update({
422
+ "method": "dandelion",
423
+ "receptor": _receptor_name(t["locus"]),
424
+ "dandelion_version": _dandelion_version(ddl),
425
+ "use_light_chain": bool(use_light_chain),
426
+ "require_heavy_chain": bool(require_heavy_chain),
427
+ "check_contigs": bool(check_contigs),
428
+ "n_contigs_ambiguous": n_ambiguous,
429
+ "n_cells_without_heavy_chain": n_without_heavy,
430
+ "n_cells_with_combined_id": n_combined,
431
+ "n_cells_with_combined_id_two_heavy": n_combined_heavy,
432
+ "identity": identity if isinstance(identity, dict) else float(identity),
433
+ "donor_key": donor_key,
434
+ "n_cells": int(s.size),
435
+ "n_clones": int(sizes.size),
436
+ "n_clones_ge2": int((sizes >= 2).sum()),
437
+ "largest_clone": int(sizes.max()) if sizes.size else 0,
438
+ "python_hash_seed": os.environ.get("PYTHONHASHSEED"),
439
+ })
440
+ if verbose:
441
+ chains = "both chains" if use_light_chain else "VDJ chain only"
442
+ ident = (f"identity {identity['ig']:g} (BCR), {identity['tr-ab']:g} (TCR)"
443
+ if isinstance(identity, dict) and {"ig", "tr-ab"} <= set(identity) else f"identity {identity}")
444
+ log(f"Dandelion ({chains}, {ident}): {s.size:,} cells, {sizes.size:,} clones, "
445
+ f"{int((sizes >= 2).sum()):,} with >= 2 cells, largest {int(sizes.max()) if sizes.size else 0}")
446
+ if n_combined >= max(10, 0.02 * s.size):
447
+ share = (f"{n_combined:,} cells ({100 * n_combined / s.size:.0f}%) carry two productive chains of one "
448
+ f"kind ({n_combined_heavy:,} two heavy (beta) chains, the others two light (alpha) chains)")
449
+ joined = "Dandelion gives each a clone id that joins both, so most of them form a clone of their own"
450
+ if check_contigs: # the check allows two light (alpha) chains per cell, as in allelic inclusion
451
+ log(f"{share} after the contig check; {joined}.")
452
+ else:
453
+ log(f"{share}: doublets, ambient RNA or allelic inclusion; {joined}. check_contigs=True keeps the "
454
+ "dominant heavy chain of a cell (Dandelion allows two light chains).")
455
+ if os.environ.get("PYTHONHASHSEED") is None:
456
+ log("PYTHONHASHSEED is not set, so Dandelion's clone calls can differ by a few clones between "
457
+ "Python sessions; set it (e.g. to 0) before starting Python for reproducible clone ids")
458
+ return s