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