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/io.py
ADDED
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
"""Input/output helpers for paired scRNA-seq + scBCR-seq data.
|
|
2
|
+
|
|
3
|
+
Supports the two most common BCR annotation formats:
|
|
4
|
+
|
|
5
|
+
* 10x Genomics Cell Ranger ``filtered_contig_annotations.csv``
|
|
6
|
+
* AIRR rearrangement TSV (e.g. IgBlast ``fmt19`` / Change-O ``db-pass``)
|
|
7
|
+
|
|
8
|
+
The main entry points are :func:`read_10x_vdj`, :func:`read_airr` and
|
|
9
|
+
:func:`attach_bcr`.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import pandas as pd
|
|
15
|
+
|
|
16
|
+
_HEAVY = "IGH"
|
|
17
|
+
_LIGHT = ("IGK", "IGL")
|
|
18
|
+
|
|
19
|
+
_CLONE_INFO_KEY = "threadfin_clones"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def read_10x_vdj(
|
|
23
|
+
path: str,
|
|
24
|
+
productive_only: bool = True,
|
|
25
|
+
high_confidence_only: bool = True,
|
|
26
|
+
) -> pd.DataFrame:
|
|
27
|
+
"""Read a 10x Cell Ranger ``filtered_contig_annotations.csv`` file.
|
|
28
|
+
|
|
29
|
+
One cell can carry multiple contigs (heavy + light chain). The contig with
|
|
30
|
+
the highest UMI count is kept per chain class.
|
|
31
|
+
|
|
32
|
+
Parameters
|
|
33
|
+
----------
|
|
34
|
+
path
|
|
35
|
+
Path to the CSV (optionally gzipped).
|
|
36
|
+
productive_only
|
|
37
|
+
Keep only productive contigs.
|
|
38
|
+
high_confidence_only
|
|
39
|
+
Keep only high-confidence contigs.
|
|
40
|
+
|
|
41
|
+
Returns
|
|
42
|
+
-------
|
|
43
|
+
DataFrame indexed by cell barcode with columns
|
|
44
|
+
``v_call, d_call, j_call, c_call, cdr3, cdr3_nt, umis, clonotype_id,
|
|
45
|
+
v_call_light, cdr3_light, n_contigs``.
|
|
46
|
+
"""
|
|
47
|
+
contigs = pd.read_csv(path)
|
|
48
|
+
required = {"barcode", "chain", "v_gene", "j_gene", "cdr3"}
|
|
49
|
+
missing = required - set(contigs.columns)
|
|
50
|
+
if missing:
|
|
51
|
+
raise ValueError(f"{path} is missing required columns: {sorted(missing)}")
|
|
52
|
+
|
|
53
|
+
if productive_only and "productive" in contigs.columns:
|
|
54
|
+
contigs = contigs[contigs["productive"] == True] # noqa: E712
|
|
55
|
+
if high_confidence_only and "high_confidence" in contigs.columns:
|
|
56
|
+
contigs = contigs[contigs["high_confidence"] == True] # noqa: E712
|
|
57
|
+
contigs = contigs[contigs["chain"].isin([_HEAVY, *_LIGHT])]
|
|
58
|
+
if len(contigs) == 0:
|
|
59
|
+
raise ValueError("No productive BCR contigs left after filtering.")
|
|
60
|
+
|
|
61
|
+
umis = contigs["umis"] if "umis" in contigs.columns else pd.Series(1, index=contigs.index)
|
|
62
|
+
contigs = contigs.assign(_umis=umis).sort_values(
|
|
63
|
+
"_umis", ascending=False, kind="mergesort")
|
|
64
|
+
|
|
65
|
+
n_contigs = contigs.groupby("barcode").size().rename("n_contigs")
|
|
66
|
+
|
|
67
|
+
heavy = contigs[contigs["chain"] == _HEAVY].drop_duplicates("barcode").set_index("barcode")
|
|
68
|
+
light = contigs[contigs["chain"].isin(_LIGHT)].drop_duplicates("barcode").set_index("barcode")
|
|
69
|
+
|
|
70
|
+
per_cell = pd.DataFrame(
|
|
71
|
+
{
|
|
72
|
+
"v_call": heavy["v_gene"],
|
|
73
|
+
"d_call": heavy["d_gene"] if "d_gene" in heavy.columns else pd.NA,
|
|
74
|
+
"j_call": heavy["j_gene"],
|
|
75
|
+
"c_call": heavy["c_gene"] if "c_gene" in heavy.columns else pd.NA,
|
|
76
|
+
"cdr3": heavy["cdr3"],
|
|
77
|
+
"cdr3_nt": heavy["cdr3_nt"] if "cdr3_nt" in heavy.columns else pd.NA,
|
|
78
|
+
"umis": heavy["_umis"],
|
|
79
|
+
"clonotype_id": (
|
|
80
|
+
heavy["raw_clonotype_id"] if "raw_clonotype_id" in heavy.columns else pd.NA
|
|
81
|
+
),
|
|
82
|
+
"v_call_light": light["v_gene"],
|
|
83
|
+
"cdr3_light": light["cdr3"],
|
|
84
|
+
"n_contigs": n_contigs,
|
|
85
|
+
}
|
|
86
|
+
)
|
|
87
|
+
per_cell.index.name = "barcode"
|
|
88
|
+
return per_cell
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def read_airr(path: str, cell_col: str | None = None) -> pd.DataFrame:
|
|
92
|
+
"""Read an AIRR rearrangement table (IgBlast fmt19 / Change-O TSV).
|
|
93
|
+
|
|
94
|
+
Parameters
|
|
95
|
+
----------
|
|
96
|
+
path
|
|
97
|
+
Path to the (optionally gzipped) TSV file.
|
|
98
|
+
cell_col
|
|
99
|
+
Column holding the cell barcode. When ``None``, ``cell_id`` is used if
|
|
100
|
+
present, otherwise the trailing ``_contig_<n>`` suffix of
|
|
101
|
+
``sequence_id`` is stripped to recover the barcode.
|
|
102
|
+
|
|
103
|
+
Returns
|
|
104
|
+
-------
|
|
105
|
+
DataFrame indexed by cell barcode with columns
|
|
106
|
+
``v_call, d_call, j_call, cdr3`` (whichever are present).
|
|
107
|
+
"""
|
|
108
|
+
bcr = pd.read_csv(path, sep="\t")
|
|
109
|
+
if cell_col is None:
|
|
110
|
+
if "cell_id" in bcr.columns:
|
|
111
|
+
cell_col = "cell_id"
|
|
112
|
+
elif "sequence_id" in bcr.columns:
|
|
113
|
+
bcr = bcr.assign(cell_id=bcr["sequence_id"].str.replace(r"_contig_\d+$", "", regex=True))
|
|
114
|
+
cell_col = "cell_id"
|
|
115
|
+
else:
|
|
116
|
+
raise ValueError("Cannot find a cell barcode column; pass `cell_col` explicitly.")
|
|
117
|
+
|
|
118
|
+
keep = [c for c in ("v_call", "d_call", "j_call", "c_call", "cdr3", "cdr3_aa",
|
|
119
|
+
"junction_aa", "clone_id", "locus") if c in bcr.columns]
|
|
120
|
+
if "cdr3" not in keep and "cdr3_aa" in keep:
|
|
121
|
+
bcr = bcr.rename(columns={"cdr3_aa": "cdr3"})
|
|
122
|
+
elif "cdr3" not in keep and "junction_aa" in keep:
|
|
123
|
+
bcr = bcr.rename(columns={"junction_aa": "cdr3"})
|
|
124
|
+
# some AIRR tables ship an empty junction_aa but a populated nucleotide
|
|
125
|
+
# junction; translate it wherever the amino-acid CDR3 is missing
|
|
126
|
+
if "junction" in bcr.columns:
|
|
127
|
+
from .sequence import translate_nt
|
|
128
|
+
|
|
129
|
+
if "cdr3" not in bcr.columns:
|
|
130
|
+
bcr["cdr3"] = bcr["junction"].map(translate_nt)
|
|
131
|
+
elif bcr["cdr3"].isna().any():
|
|
132
|
+
na = bcr["cdr3"].isna()
|
|
133
|
+
bcr["cdr3"] = bcr["cdr3"].astype(object)
|
|
134
|
+
bcr.loc[na, "cdr3"] = bcr.loc[na, "junction"].map(translate_nt)
|
|
135
|
+
# prefer the heavy chain for per-cell V/D/J calls when a locus column exists
|
|
136
|
+
if "locus" in bcr.columns and (bcr["locus"] == "IGH").any():
|
|
137
|
+
bcr = bcr[bcr["locus"] == "IGH"]
|
|
138
|
+
per_cell = bcr.drop_duplicates(cell_col).set_index(cell_col)
|
|
139
|
+
keep = [c for c in ("v_call", "d_call", "j_call", "c_call", "cdr3", "clone_id")
|
|
140
|
+
if c in per_cell.columns]
|
|
141
|
+
per_cell = per_cell[keep]
|
|
142
|
+
per_cell.index.name = "barcode"
|
|
143
|
+
return per_cell
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def build_clone_key(
|
|
147
|
+
bcr_table: pd.DataFrame,
|
|
148
|
+
strategy: str = "vdj",
|
|
149
|
+
out_col: str = "clone_id",
|
|
150
|
+
) -> pd.DataFrame:
|
|
151
|
+
"""Add a clonotype key to a per-cell BCR table.
|
|
152
|
+
|
|
153
|
+
Parameters
|
|
154
|
+
----------
|
|
155
|
+
bcr_table
|
|
156
|
+
Per-cell BCR table as returned by :func:`read_10x_vdj` or
|
|
157
|
+
:func:`read_airr`.
|
|
158
|
+
strategy
|
|
159
|
+
``"vdj"``: ``v_call_d_call_j_call`` of the heavy chain (germline-gene
|
|
160
|
+
level clonotype, as in the original Threadfin manuscript).
|
|
161
|
+
``"clonotype_id"``: use the Cell Ranger clonotype id (somatic-level).
|
|
162
|
+
``"cdr3"``: use the heavy-chain CDR3 amino acid sequence.
|
|
163
|
+
out_col
|
|
164
|
+
Name of the output column.
|
|
165
|
+
|
|
166
|
+
Returns
|
|
167
|
+
-------
|
|
168
|
+
The input table with an added ``out_col`` column.
|
|
169
|
+
"""
|
|
170
|
+
bcr_table = bcr_table.copy()
|
|
171
|
+
if strategy == "vdj":
|
|
172
|
+
for col in ("v_call", "d_call", "j_call"):
|
|
173
|
+
if col not in bcr_table.columns:
|
|
174
|
+
raise ValueError(f"strategy='vdj' requires a '{col}' column.")
|
|
175
|
+
key = (
|
|
176
|
+
bcr_table["v_call"].astype(str)
|
|
177
|
+
+ "_"
|
|
178
|
+
+ bcr_table["d_call"].astype(str)
|
|
179
|
+
+ "_"
|
|
180
|
+
+ bcr_table["j_call"].astype(str)
|
|
181
|
+
)
|
|
182
|
+
missing = bcr_table[["v_call", "d_call", "j_call"]].isna().any(axis=1)
|
|
183
|
+
bcr_table[out_col] = key.mask(missing)
|
|
184
|
+
elif strategy in ("clonotype_id", "cdr3"):
|
|
185
|
+
if strategy not in bcr_table.columns:
|
|
186
|
+
raise ValueError(f"strategy='{strategy}' requires a '{strategy}' column.")
|
|
187
|
+
vals = bcr_table[strategy]
|
|
188
|
+
is_na = vals.isna() | vals.astype(str).isin(("None", "", "nan"))
|
|
189
|
+
bcr_table[out_col] = vals.astype(str).mask(is_na)
|
|
190
|
+
else:
|
|
191
|
+
raise ValueError(f"Unknown strategy: {strategy!r}")
|
|
192
|
+
return bcr_table
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def _clone_modes(tab: pd.DataFrame, clone_col: str) -> pd.DataFrame:
|
|
196
|
+
"""Most frequent value of every column per clone (ties: smallest value as text).
|
|
197
|
+
|
|
198
|
+
Vectorised: one group count per column instead of a Python call per clone.
|
|
199
|
+
"""
|
|
200
|
+
out = pd.DataFrame(index=pd.Index(pd.unique(tab[clone_col]), name=clone_col))
|
|
201
|
+
for col in (c for c in tab.columns if c != clone_col):
|
|
202
|
+
sub = tab[[clone_col, col]].dropna()
|
|
203
|
+
if sub.empty:
|
|
204
|
+
out[col] = None
|
|
205
|
+
continue
|
|
206
|
+
counts = sub.groupby([clone_col, col], observed=True, sort=False).size().rename("n").reset_index()
|
|
207
|
+
counts["_key"] = counts[col].astype(str)
|
|
208
|
+
counts = counts.sort_values([clone_col, "n", "_key"], ascending=[True, False, True], kind="mergesort")
|
|
209
|
+
out[col] = counts.drop_duplicates(clone_col).set_index(clone_col)[col].reindex(out.index)
|
|
210
|
+
return out
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def attach_bcr(
|
|
214
|
+
adata,
|
|
215
|
+
bcr_table: pd.DataFrame,
|
|
216
|
+
clone_col: str = "clone_id",
|
|
217
|
+
prefix: str = "bcr_",
|
|
218
|
+
summarize: bool = True,
|
|
219
|
+
verbose: bool = True,
|
|
220
|
+
) -> "object":
|
|
221
|
+
"""Attach per-cell BCR annotations to ``adata.obs`` (vectorized).
|
|
222
|
+
|
|
223
|
+
Cells without a BCR get ``NaN``. Every column of ``bcr_table`` is added
|
|
224
|
+
to ``obs`` with ``prefix`` (the clone column keeps its own name).
|
|
225
|
+
Columns from a previous call with the same prefix are replaced.
|
|
226
|
+
|
|
227
|
+
Parameters
|
|
228
|
+
----------
|
|
229
|
+
adata
|
|
230
|
+
:class:`anndata.AnnData` with ``obs_names`` matching the BCR barcodes.
|
|
231
|
+
bcr_table
|
|
232
|
+
Per-cell BCR table indexed by barcode, with a ``clone_col`` column
|
|
233
|
+
(see :func:`threadfin.define_clones` or :func:`build_clone_key`).
|
|
234
|
+
clone_col
|
|
235
|
+
Column of ``bcr_table`` holding the clone id.
|
|
236
|
+
prefix
|
|
237
|
+
Prefix for the added ``obs`` columns.
|
|
238
|
+
summarize
|
|
239
|
+
Also store a clone-level summary (modal V/D/J calls and CDR3 per
|
|
240
|
+
clone) in ``adata.uns['threadfin_clones']``; only needed by the legacy
|
|
241
|
+
sequence-blending functions (``cdr3_weight``, ``joint_embedding``).
|
|
242
|
+
|
|
243
|
+
Returns
|
|
244
|
+
-------
|
|
245
|
+
The modified ``adata`` (in place and returned).
|
|
246
|
+
"""
|
|
247
|
+
if clone_col not in bcr_table.columns:
|
|
248
|
+
raise ValueError(f"bcr_table needs a '{clone_col}' column; see define_clones().")
|
|
249
|
+
|
|
250
|
+
tab = bcr_table.copy()
|
|
251
|
+
tab.index = tab.index.astype(str)
|
|
252
|
+
if tab.index.has_duplicates:
|
|
253
|
+
raise ValueError("bcr_table has duplicated barcodes; keep one row per cell.")
|
|
254
|
+
adata.obs_names = adata.obs_names.astype(str)
|
|
255
|
+
|
|
256
|
+
n_matched = int(adata.obs_names.isin(tab.index).sum())
|
|
257
|
+
if n_matched == 0:
|
|
258
|
+
raise ValueError(
|
|
259
|
+
"No overlap between adata.obs_names and BCR barcodes — check barcode formatting."
|
|
260
|
+
)
|
|
261
|
+
|
|
262
|
+
renamed = {c: prefix + c for c in tab.columns if c != clone_col}
|
|
263
|
+
stale = [c for c in list(renamed.values()) + [clone_col] if c in adata.obs.columns]
|
|
264
|
+
obs = adata.obs.drop(columns=stale)
|
|
265
|
+
adata.obs = obs.join(tab.rename(columns=renamed), how="left")
|
|
266
|
+
|
|
267
|
+
n_clones = int(tab.loc[tab.index.isin(adata.obs_names), clone_col].nunique())
|
|
268
|
+
if summarize:
|
|
269
|
+
clone_info = _clone_modes(tab.dropna(subset=[clone_col]), clone_col)
|
|
270
|
+
clone_info["n_cells_bcr_table"] = tab[clone_col].value_counts()
|
|
271
|
+
adata.uns[_CLONE_INFO_KEY] = clone_info
|
|
272
|
+
|
|
273
|
+
adata.uns.setdefault("threadfin", {})["attach_bcr"] = {
|
|
274
|
+
"n_cells_total": int(adata.n_obs),
|
|
275
|
+
"n_cells_with_bcr": n_matched,
|
|
276
|
+
"n_clones": n_clones,
|
|
277
|
+
}
|
|
278
|
+
if verbose:
|
|
279
|
+
print(f"[threadfin] attached clone ids: {n_matched}/{adata.n_obs} cells, {n_clones} clones.", flush=True)
|
|
280
|
+
return adata
|