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