threadfin 4.5.0__tar.gz → 4.5.1__tar.gz

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.
Files changed (64) hide show
  1. {threadfin-4.5.0/threadfin.egg-info → threadfin-4.5.1}/PKG-INFO +103 -66
  2. {threadfin-4.5.0 → threadfin-4.5.1}/README.md +101 -64
  3. {threadfin-4.5.0 → threadfin-4.5.1}/pyproject.toml +4 -3
  4. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_dandelion_adapter.py +9 -0
  5. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_user_inputs.py +82 -0
  6. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/__init__.py +1 -1
  7. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/api.py +12 -4
  8. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/dandelion.py +17 -3
  9. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/plotting.py +37 -16
  10. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/profiles.py +5 -7
  11. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/programmes.py +11 -13
  12. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/stats.py +15 -8
  13. {threadfin-4.5.0 → threadfin-4.5.1/threadfin.egg-info}/PKG-INFO +103 -66
  14. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin.egg-info/requires.txt +1 -1
  15. {threadfin-4.5.0 → threadfin-4.5.1}/LICENSE +0 -0
  16. {threadfin-4.5.0 → threadfin-4.5.1}/setup.cfg +0 -0
  17. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_api_reference.py +0 -0
  18. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_bcrgraph_clones.py +0 -0
  19. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_bone_marrow_design.py +0 -0
  20. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_case_study_signatures.py +0 -0
  21. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_clone_state_sharing.py +0 -0
  22. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_clones_v3.py +0 -0
  23. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_density.py +0 -0
  24. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_ebv_contig_matching.py +0 -0
  25. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_export.py +0 -0
  26. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_integrate.py +0 -0
  27. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_io.py +0 -0
  28. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_maptune.py +0 -0
  29. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_migration.py +0 -0
  30. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_parallel_and_robustness.py +0 -0
  31. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_phylo.py +0 -0
  32. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_profile_reproducibility.py +0 -0
  33. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_programs.py +0 -0
  34. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_reclustering_presets.py +0 -0
  35. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_release_metadata.py +0 -0
  36. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_sequence_v2.py +0 -0
  37. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_specificity.py +0 -0
  38. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_threadfin.py +0 -0
  39. {threadfin-4.5.0 → threadfin-4.5.1}/tests/test_v4_core.py +0 -0
  40. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/_utils.py +0 -0
  41. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/bcrgraph.py +0 -0
  42. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/clones.py +0 -0
  43. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/core.py +0 -0
  44. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/density.py +0 -0
  45. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/dynamics.py +0 -0
  46. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/export.py +0 -0
  47. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/expression.py +0 -0
  48. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/heritability.py +0 -0
  49. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/integrate.py +0 -0
  50. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/io.py +0 -0
  51. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/maptune.py +0 -0
  52. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/metrics.py +0 -0
  53. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/migration.py +0 -0
  54. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/phylo.py +0 -0
  55. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/pp.py +0 -0
  56. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/programs.py +0 -0
  57. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/reclustering.py +0 -0
  58. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/sequence.py +0 -0
  59. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/simulate.py +0 -0
  60. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/specificity.py +0 -0
  61. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin/tl.py +0 -0
  62. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin.egg-info/SOURCES.txt +0 -0
  63. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin.egg-info/dependency_links.txt +0 -0
  64. {threadfin-4.5.0 → threadfin-4.5.1}/threadfin.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: threadfin
3
- Version: 4.5.0
3
+ Version: 4.5.1
4
4
  Summary: Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory
5
5
  Author-email: Chen Satoshi <103236530+Reynold4k@users.noreply.github.com>
6
6
  License: MIT
@@ -37,7 +37,7 @@ Requires-Dist: pynndescent>=0.5.8
37
37
  Requires-Dist: harmonypy>=0.0.9; platform_system != "Windows"
38
38
  Requires-Dist: harmonypy<2,>=0.0.9; platform_system == "Windows"
39
39
  Provides-Extra: dandelion
40
- Requires-Dist: sc-dandelion>=0.5.7; extra == "dandelion"
40
+ Requires-Dist: sc-dandelion<1,>=0.5.7; extra == "dandelion"
41
41
  Requires-Dist: matplotlib<3.9,>=3.7; extra == "dandelion"
42
42
  Provides-Extra: seq
43
43
  Requires-Dist: parasail>=1.3; extra == "seq"
@@ -65,10 +65,105 @@ Dynamic: license-file
65
65
  <p align="center">
66
66
  <a href="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml"><img src="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
67
67
  <a href="https://www.python.org"><img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue.svg" alt="Python 3.10 to 3.14"></a>
68
- <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-4.3.1-informational.svg" alt="version 4.3.1"></a>
68
+ <a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
69
69
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
70
70
  </p>
71
71
 
72
+ Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
73
+ distribution of its cells' transcriptional states, so that clones, not cells, can be compared, mapped and tested.
74
+
75
+ ## Get started
76
+
77
+ ### 1. Install
78
+
79
+ ```bash
80
+ pip install threadfin # Python 3.10–3.14 on Linux, macOS or Windows; no GPU or R needed
81
+ pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs
82
+ ```
83
+
84
+ Scanpy, Leiden, UMAP and Harmony are installed with it. Dandelion's clone calls depend on Python's hash seed:
85
+ start Python with `PYTHONHASHSEED=0` when clone ids must be identical run after run. Threadfin is validated with
86
+ Dandelion 0.5.x; Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`. The development version
87
+ installs with `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
88
+
89
+ ### 2. Run
90
+
91
+ You need, for the same cells: raw gene counts in an [AnnData](https://anndata.readthedocs.io) object, the
92
+ contig-level receptor table (Cell Ranger's `filtered_contig_annotations.csv` or an AIRR `.tsv`), and the donor
93
+ and sample of each cell.
94
+
95
+ ```python
96
+ import scanpy as sc
97
+ import threadfin as tf
98
+
99
+ adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
100
+
101
+ result = tf.run(
102
+ adata,
103
+ bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
104
+ donor_key="donor", # the individual each cell came from
105
+ sample_key="sample", # the sample or library each cell came from (never a sort gate,
106
+ # tissue or time point you want to compare: those go in test=)
107
+ n_jobs=8, # CPU cores to use; the result is the same with any number
108
+ )
109
+ ```
110
+
111
+ `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
112
+ receptor genes, estimates one profile per clone, tests clonal coherence, lays out the clone map and looks for
113
+ clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to 15 minutes with 8 cores.
114
+
115
+ ### 3. Read the results
116
+
117
+ ```python
118
+ print(result.summary()) # plain-language report
119
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
120
+ print(result.methods()) # a Methods paragraph with the settings and versions used
121
+ result.clones.to_csv("clones.csv") # one row per clone: size, reliability, programme, map position
122
+ ```
123
+
124
+ <p align="center">
125
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
126
+ </p>
127
+
128
+ | What you get | Where |
129
+ |---|---|
130
+ | Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
131
+ | A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
132
+ | Groups of clones that behave alike, with their stability | `result.programmes`; `adata.obs["clone_programme"]` |
133
+ | How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
134
+ | A Methods paragraph for your paper, with references | `result.methods()` |
135
+
136
+ ### Common variations
137
+
138
+ * **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
139
+ `tf.run(..., test=["antigen_binding", "isotype"])`.
140
+ * **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
141
+ * **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
142
+ * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
143
+ * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
144
+ * **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
145
+ on 8 cores.
146
+ * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
147
+ has clone ids and an embedding, so run it with
148
+ `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
149
+
150
+ ### Tutorials
151
+
152
+ | Tutorial | What it covers |
153
+ |---|---|
154
+ | [1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data in a minute, with every output explained |
155
+ | [2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results: quality control, several samples and donors, clone calling, T cells, troubleshooting |
156
+ | [3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
157
+ | [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
158
+ | [5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset (GSE287123) end to end: download, hashtag demultiplexing, clones, embedding, Threadfin and interpretation; executed in a fresh environment before every release (about 6 minutes on 8 cores) |
159
+
160
+ 4.5.1 pins Dandelion below 1.0 and fixes T-cell contig files passed as a path. New in 4.5.0: T cells, scirpy input, `result.methods()` and gene-level summaries of the clone landscape
161
+ ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
162
+
163
+ ---
164
+
165
+ ## What Threadfin does
166
+
72
167
  **Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
73
168
  uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
74
169
  Each clone is represented by the distribution of transcriptional states among its sampled cells,
@@ -127,62 +222,6 @@ manuscript — status, datasets, every analysis and a benchmark against related
127
222
  the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
128
223
  clone profiles but were each sequenced in their own library.
129
224
 
130
- ## Installation
131
-
132
- ```bash
133
- pip install "git+https://github.com/Reynold4k/Threadfin.git"
134
- # with Dandelion, to define clones from BCR contigs:
135
- pip install "threadfin[dandelion] @ git+https://github.com/Reynold4k/Threadfin.git"
136
- ```
137
-
138
- Threadfin requires Python ≥ 3.10 and is tested on 3.10 to 3.14, down to the oldest dependency versions it
139
- allows ([compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md)); Scanpy, Leiden, UMAP and Harmony are installed with it, and no
140
- GPU or R is needed. Clones can be defined from BCR contigs with Dandelion (the `[dandelion]` extra also pins
141
- `matplotlib<3.9`, which Dandelion 0.5.7 needs but does not declare), or you can provide your own clone ids
142
- in `adata.obs["clone_id"]`. Dandelion's clone calls depend on Python's string-hash seed; start Python with
143
- `PYTHONHASHSEED=0` if clone ids must be identical run after run.
144
-
145
- ## Quick start
146
-
147
- ```python
148
- import scanpy as sc
149
- import threadfin as tf
150
-
151
- adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
152
-
153
- result = tf.run(
154
- adata,
155
- bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
156
- donor_key="donor", # the individual each cell came from
157
- sample_key="sample", # the sample or library each cell came from
158
- )
159
- print(result.summary()) # plain-language report
160
- result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
161
- print(result.methods()) # a Methods paragraph with the settings used
162
- ```
163
-
164
- `tf.run` defines clones within each donor, builds an expression embedding without immunoglobulin genes,
165
- estimates one profile per clone, tests clonal coherence, lays out the clone embedding, finds clonal
166
- programmes and reports their stability. Add `test=[...]` to test your own labels and `time_key=` to ask
167
- whether clones keep their state, and `n_jobs=-1` to use every CPU core (the results do not change). No data
168
- at hand? `tf.sim.simulate_repertoire()` makes a repertoire with a known answer
169
- ([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)).
170
- T cells work the same way, with TCR contigs as `bcr`, and receptor data loaded with scirpy can be passed as
171
- they are ([Tutorial 2, section 6](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md#6-how-clones-are-called)).
172
-
173
- <p align="center">
174
- <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
175
- </p>
176
-
177
- ## A complete, tested tutorial on public data
178
-
179
- [`docs/tutorials/05_end_to_end_tutorial.ipynb`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) takes you from an
180
- empty folder to the main result of the manuscript's Figure 4: it creates the environment
181
- ([`environment.yml`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/environment.yml)), downloads a published dataset from GEO (GSE287123,
182
- about 600 MB), assigns cells to mice from hashtags, defines clones, builds the embedding, runs Threadfin and
183
- explains every output, including how to tell biology from a sequencing-library effect. It was executed end
184
- to end in a fresh environment before release and takes about 6 minutes on 8 CPU cores (about 8 GB of memory).
185
-
186
225
  ## A clone embedding that holds together
187
226
 
188
227
  UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
@@ -206,7 +245,8 @@ tf.tl.map_quality(features, xy) # score any clone map (p
206
245
  <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
207
246
  </p>
208
247
 
209
- 1. **Clones** are defined from paired heavy- and light-chain sequences within each donor (Dandelion).
248
+ 1. **Clones** are defined from paired heavy- and light-chain sequences (for T cells, beta and alpha chains)
249
+ within each donor (Dandelion).
210
250
  2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
211
251
  a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
212
252
  between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
@@ -226,18 +266,15 @@ The full description, with references, is in [Methods](https://github.com/Reynol
226
266
 
227
267
  | | |
228
268
  |---|---|
229
- | [Tutorial 1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data, with its output |
230
- | [Tutorial 2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results, with several samples and donors |
231
- | [Tutorial 3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
232
- | [Tutorial 4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
233
- | [Tutorial 5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset end to end: download, demultiplexing, clones, embedding, Threadfin, interpretation |
234
269
  | [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
235
270
  | [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
271
+ | [Compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md) | Python and dependency versions, operating systems and datasets tested |
272
+ | [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
236
273
  | [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
237
274
  | [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
238
275
  | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
239
276
  | [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
240
- | [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
277
+ | [Technical validation](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/README.md) | the tutorials on 16 public datasets, sensitivity to clone calling and embedding, power, a million cells, T cells |
241
278
 
242
279
  ## Citation
243
280
 
@@ -11,10 +11,105 @@
11
11
  <p align="center">
12
12
  <a href="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml"><img src="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
13
13
  <a href="https://www.python.org"><img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue.svg" alt="Python 3.10 to 3.14"></a>
14
- <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-4.3.1-informational.svg" alt="version 4.3.1"></a>
14
+ <a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
15
15
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
16
16
  </p>
17
17
 
18
+ Threadfin takes paired single-cell RNA and receptor (BCR or TCR) sequencing and describes every clone by the
19
+ distribution of its cells' transcriptional states, so that clones, not cells, can be compared, mapped and tested.
20
+
21
+ ## Get started
22
+
23
+ ### 1. Install
24
+
25
+ ```bash
26
+ pip install threadfin # Python 3.10–3.14 on Linux, macOS or Windows; no GPU or R needed
27
+ pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs
28
+ ```
29
+
30
+ Scanpy, Leiden, UMAP and Harmony are installed with it. Dandelion's clone calls depend on Python's hash seed:
31
+ start Python with `PYTHONHASHSEED=0` when clone ids must be identical run after run. Threadfin is validated with
32
+ Dandelion 0.5.x; Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`. The development version
33
+ installs with `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
34
+
35
+ ### 2. Run
36
+
37
+ You need, for the same cells: raw gene counts in an [AnnData](https://anndata.readthedocs.io) object, the
38
+ contig-level receptor table (Cell Ranger's `filtered_contig_annotations.csv` or an AIRR `.tsv`), and the donor
39
+ and sample of each cell.
40
+
41
+ ```python
42
+ import scanpy as sc
43
+ import threadfin as tf
44
+
45
+ adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
46
+
47
+ result = tf.run(
48
+ adata,
49
+ bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
50
+ donor_key="donor", # the individual each cell came from
51
+ sample_key="sample", # the sample or library each cell came from (never a sort gate,
52
+ # tissue or time point you want to compare: those go in test=)
53
+ n_jobs=8, # CPU cores to use; the result is the same with any number
54
+ )
55
+ ```
56
+
57
+ `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
58
+ receptor genes, estimates one profile per clone, tests clonal coherence, lays out the clone map and looks for
59
+ clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to 15 minutes with 8 cores.
60
+
61
+ ### 3. Read the results
62
+
63
+ ```python
64
+ print(result.summary()) # plain-language report
65
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
66
+ print(result.methods()) # a Methods paragraph with the settings and versions used
67
+ result.clones.to_csv("clones.csv") # one row per clone: size, reliability, programme, map position
68
+ ```
69
+
70
+ <p align="center">
71
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
72
+ </p>
73
+
74
+ | What you get | Where |
75
+ |---|---|
76
+ | Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
77
+ | A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
78
+ | Groups of clones that behave alike, with their stability | `result.programmes`; `adata.obs["clone_programme"]` |
79
+ | How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
80
+ | A Methods paragraph for your paper, with references | `result.methods()` |
81
+
82
+ ### Common variations
83
+
84
+ * **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
85
+ `tf.run(..., test=["antigen_binding", "isotype"])`.
86
+ * **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
87
+ * **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
88
+ * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
89
+ * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
90
+ * **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
91
+ on 8 cores.
92
+ * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
93
+ has clone ids and an embedding, so run it with
94
+ `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
95
+
96
+ ### Tutorials
97
+
98
+ | Tutorial | What it covers |
99
+ |---|---|
100
+ | [1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data in a minute, with every output explained |
101
+ | [2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results: quality control, several samples and donors, clone calling, T cells, troubleshooting |
102
+ | [3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
103
+ | [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
104
+ | [5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset (GSE287123) end to end: download, hashtag demultiplexing, clones, embedding, Threadfin and interpretation; executed in a fresh environment before every release (about 6 minutes on 8 cores) |
105
+
106
+ 4.5.1 pins Dandelion below 1.0 and fixes T-cell contig files passed as a path. New in 4.5.0: T cells, scirpy input, `result.methods()` and gene-level summaries of the clone landscape
107
+ ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
108
+
109
+ ---
110
+
111
+ ## What Threadfin does
112
+
18
113
  **Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
19
114
  uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
20
115
  Each clone is represented by the distribution of transcriptional states among its sampled cells,
@@ -73,62 +168,6 @@ manuscript — status, datasets, every analysis and a benchmark against related
73
168
  the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
74
169
  clone profiles but were each sequenced in their own library.
75
170
 
76
- ## Installation
77
-
78
- ```bash
79
- pip install "git+https://github.com/Reynold4k/Threadfin.git"
80
- # with Dandelion, to define clones from BCR contigs:
81
- pip install "threadfin[dandelion] @ git+https://github.com/Reynold4k/Threadfin.git"
82
- ```
83
-
84
- Threadfin requires Python ≥ 3.10 and is tested on 3.10 to 3.14, down to the oldest dependency versions it
85
- allows ([compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md)); Scanpy, Leiden, UMAP and Harmony are installed with it, and no
86
- GPU or R is needed. Clones can be defined from BCR contigs with Dandelion (the `[dandelion]` extra also pins
87
- `matplotlib<3.9`, which Dandelion 0.5.7 needs but does not declare), or you can provide your own clone ids
88
- in `adata.obs["clone_id"]`. Dandelion's clone calls depend on Python's string-hash seed; start Python with
89
- `PYTHONHASHSEED=0` if clone ids must be identical run after run.
90
-
91
- ## Quick start
92
-
93
- ```python
94
- import scanpy as sc
95
- import threadfin as tf
96
-
97
- adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
98
-
99
- result = tf.run(
100
- adata,
101
- bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
102
- donor_key="donor", # the individual each cell came from
103
- sample_key="sample", # the sample or library each cell came from
104
- )
105
- print(result.summary()) # plain-language report
106
- result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
107
- print(result.methods()) # a Methods paragraph with the settings used
108
- ```
109
-
110
- `tf.run` defines clones within each donor, builds an expression embedding without immunoglobulin genes,
111
- estimates one profile per clone, tests clonal coherence, lays out the clone embedding, finds clonal
112
- programmes and reports their stability. Add `test=[...]` to test your own labels and `time_key=` to ask
113
- whether clones keep their state, and `n_jobs=-1` to use every CPU core (the results do not change). No data
114
- at hand? `tf.sim.simulate_repertoire()` makes a repertoire with a known answer
115
- ([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)).
116
- T cells work the same way, with TCR contigs as `bcr`, and receptor data loaded with scirpy can be passed as
117
- they are ([Tutorial 2, section 6](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md#6-how-clones-are-called)).
118
-
119
- <p align="center">
120
- <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
121
- </p>
122
-
123
- ## A complete, tested tutorial on public data
124
-
125
- [`docs/tutorials/05_end_to_end_tutorial.ipynb`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) takes you from an
126
- empty folder to the main result of the manuscript's Figure 4: it creates the environment
127
- ([`environment.yml`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/environment.yml)), downloads a published dataset from GEO (GSE287123,
128
- about 600 MB), assigns cells to mice from hashtags, defines clones, builds the embedding, runs Threadfin and
129
- explains every output, including how to tell biology from a sequencing-library effect. It was executed end
130
- to end in a fresh environment before release and takes about 6 minutes on 8 CPU cores (about 8 GB of memory).
131
-
132
171
  ## A clone embedding that holds together
133
172
 
134
173
  UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
@@ -152,7 +191,8 @@ tf.tl.map_quality(features, xy) # score any clone map (p
152
191
  <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
153
192
  </p>
154
193
 
155
- 1. **Clones** are defined from paired heavy- and light-chain sequences within each donor (Dandelion).
194
+ 1. **Clones** are defined from paired heavy- and light-chain sequences (for T cells, beta and alpha chains)
195
+ within each donor (Dandelion).
156
196
  2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
157
197
  a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
158
198
  between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
@@ -172,18 +212,15 @@ The full description, with references, is in [Methods](https://github.com/Reynol
172
212
 
173
213
  | | |
174
214
  |---|---|
175
- | [Tutorial 1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data, with its output |
176
- | [Tutorial 2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results, with several samples and donors |
177
- | [Tutorial 3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
178
- | [Tutorial 4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
179
- | [Tutorial 5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset end to end: download, demultiplexing, clones, embedding, Threadfin, interpretation |
180
215
  | [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
181
216
  | [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
217
+ | [Compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md) | Python and dependency versions, operating systems and datasets tested |
218
+ | [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
182
219
  | [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
183
220
  | [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
184
221
  | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
185
222
  | [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
186
- | [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
223
+ | [Technical validation](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/README.md) | the tutorials on 16 public datasets, sensitivity to clone calling and embedding, power, a million cells, T cells |
187
224
 
188
225
  ## Citation
189
226
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "threadfin"
7
- version = "4.5.0"
7
+ version = "4.5.1"
8
8
  description = "Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -44,8 +44,9 @@ dependencies = [
44
44
  ]
45
45
 
46
46
  [project.optional-dependencies]
47
- # clone definition with Dandelion; sc-dandelion 0.5.7 uses matplotlib.cm.get_cmap, removed in matplotlib 3.9
48
- dandelion = ["sc-dandelion>=0.5.7", "matplotlib>=3.7,<3.9"]
47
+ # clone definition with Dandelion; sc-dandelion 0.5.7 uses matplotlib.cm.get_cmap, removed in matplotlib 3.9.
48
+ # sc-dandelion 1.0 (2026-10-25) calls clones differently and is not yet validated, hence < 1.
49
+ dandelion = ["sc-dandelion>=0.5.7,<1", "matplotlib>=3.7,<3.9"]
49
50
  seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
50
51
  data = ["mudata>=0.3", "awkward>=2"] # reading scirpy/MuData example data
51
52
  test = ["pytest>=7", "pytest-cov>=4"]
@@ -279,3 +279,12 @@ def test_receptor_data_can_come_from_a_scirpy_object():
279
279
  t = read_contigs(adata)
280
280
  assert len(t) == 5 and set(t["cell_id"]) == {"cell0", "cell1", "cell2"}
281
281
  assert {"v_call", "j_call", "junction", "locus"} <= set(t.columns)
282
+
283
+
284
+ def test_dandelion_1x_is_flagged(monkeypatch):
285
+ """sc-dandelion 1.0 calls clones differently from the validated 0.5.x; using it must not be silent."""
286
+ pytest.importorskip("dandelion")
287
+ import threadfin.dandelion as tfd
288
+ monkeypatch.setattr(tfd, "_dandelion_version", lambda ddl: "1.0.0")
289
+ with pytest.warns(UserWarning, match="validated with sc-dandelion 0.5.x"):
290
+ tfd._require_dandelion()
@@ -117,3 +117,85 @@ def test_a_subset_without_copy_runs_and_keeps_its_results():
117
117
  assert view.is_view
118
118
  res = tf.run(view, basis="X_pca", donor_key="donor", sample_key="context", n_perm=10, n_boot=3, verbose=False)
119
119
  assert not view.is_view and "threadfin" in view.uns and len(res.clones) > 0
120
+
121
+
122
+ def _tcr_csv_for(adata, path):
123
+ """A Cell Ranger TCR filtered_contig_annotations.csv for the simulated cells: one beta and one alpha chain
124
+ per cell, identical within a clone and distinct between clones."""
125
+ rng = np.random.default_rng(0)
126
+ aa = np.array(list("ACDEFGHIKLMNPQRSTVWY"))
127
+ junctions = {c: ("CASS" + "".join(rng.choice(aa, 7)) + "F", "CAV" + "".join(rng.choice(aa, 7)) + "F")
128
+ for c in adata.obs["clone_id"].astype(str).unique()}
129
+ rows = []
130
+ for cell, clone in adata.obs["clone_id"].astype(str).items():
131
+ beta, alpha = junctions[clone]
132
+ for chain, v, j, cdr3 in (("TRB", "TRBV7-9", "TRBJ2-7", beta), ("TRA", "TRAV1-2", "TRAJ33", alpha)):
133
+ rows.append({"barcode": cell, "is_cell": True, "high_confidence": True, "chain": chain, "v_gene": v,
134
+ "d_gene": "None", "j_gene": j, "c_gene": chain[:2] + "C", "productive": True,
135
+ "cdr3": cdr3, "cdr3_nt": "TGT" * len(cdr3), "reads": 500, "umis": 5})
136
+ pd.DataFrame(rows).to_csv(path, index=False)
137
+
138
+
139
+ def test_t_cell_contigs_can_be_passed_as_a_file_path(tmp_path):
140
+ """The README's T-cell route: a TCR filtered_contig_annotations.csv path used to crash after clone calling
141
+ ('No productive BCR contigs left') because the per-cell summary read B-cell chains only."""
142
+ pytest.importorskip("dandelion")
143
+ adata = tf.sim.simulate_repertoire(random_state=0, n_clones=150)
144
+ true_clone = adata.obs["clone_id"].astype(str).copy()
145
+ _tcr_csv_for(adata, tmp_path / "tcr.csv")
146
+ del adata.obs["clone_id"]
147
+ res = tf.run(adata, bcr=str(tmp_path / "tcr.csv"), basis="X_pca", donor_key="donor", sample_key="context",
148
+ n_perm=10, n_boot=3, verbose=False)
149
+ called = adata.obs["clone_id"]
150
+ assert res.settings.get("receptor") == "TCR" and called.notna().all()
151
+ # the called clones are the simulated ones (within donors)
152
+ assert pd.crosstab(called, true_clone).gt(0).sum(axis=1).eq(1).all()
153
+
154
+
155
+ def test_define_clones_accepts_cell_ranger_column_names():
156
+ """Tutorial 2 passes the Cell Ranger contig table (barcode, v_gene, j_gene, cdr3_nt) directly."""
157
+ pytest.importorskip("dandelion")
158
+ adata = tf.sim.simulate_repertoire(random_state=0, n_clones=40)
159
+ import tempfile, os
160
+ with tempfile.TemporaryDirectory() as d:
161
+ _tcr_csv_for(adata, os.path.join(d, "tcr.csv"))
162
+ contigs = pd.read_csv(os.path.join(d, "tcr.csv"))
163
+ contigs["donor"] = contigs["barcode"].map(adata.obs["donor"].astype(str))
164
+ ids = tf.define_clones_dandelion(contigs, donor_key="donor", verbose=False)
165
+ assert ids.notna().all() and ids.index.isin(adata.obs_names).all()
166
+
167
+
168
+ def test_fraction_of_a_level_that_never_occurs_warns():
169
+ """fraction:IGHA on a column holding IGHA1/IGHA2 used to return 0 for every clone without a word."""
170
+ adata = tf.sim.simulate_repertoire(random_state=0, n_clones=60)
171
+ tf.tl.clone_profiles(adata, basis="X_pca", context_key="context", donor_key="donor", verbose=False)
172
+ adata.obs["iso"] = np.where(np.arange(adata.n_obs) % 2, "IGHA1", "IGHG1")
173
+ with pytest.warns(UserWarning, match="Levels starting with 'IGHA': IGHA1"):
174
+ out = tf.tl.clone_labels(adata, "iso", how="fraction:IGHA")
175
+ assert (out == 0).all()
176
+
177
+
178
+ def test_overview_shows_the_coherence_of_the_result(monkeypatch):
179
+ """Panel b used to show whatever clonal_coherence ran last, not result.coherence."""
180
+ import threadfin.plotting as plotting
181
+ adata = tf.sim.simulate_repertoire(random_state=0, n_clones=1000)
182
+ res = tf.run(adata, basis="X_pca", donor_key="donor", sample_key="context", n_perm=10, n_boot=3, verbose=False)
183
+ tf.tl.clonal_coherence(adata, strata_key="donor", n_perm=10, verbose=False) # a later, different test
184
+ seen = {}
185
+ original = plotting.coherence
186
+
187
+ def spy(adata, *, result=None, ax=None, save=None):
188
+ seen["icc"] = (result or adata.uns["threadfin"]["coherence"])["icc"]
189
+ return original(adata, result=result, ax=ax, save=save)
190
+
191
+ monkeypatch.setattr(plotting, "coherence", spy)
192
+ res.plot()
193
+ assert seen["icc"] == res.coherence["icc"]
194
+
195
+
196
+ def test_overview_is_drawn_when_no_programmes_were_found():
197
+ """A small dataset gets 'not enough reliably profiled clones' for programmes; result.plot() used to crash."""
198
+ adata = tf.sim.simulate_repertoire(random_state=0, n_clones=200)
199
+ res = tf.run(adata, basis="X_pca", donor_key="donor", sample_key="context", n_perm=10, n_boot=3, verbose=False)
200
+ assert res.programmes.empty
201
+ assert res.plot() is not None
@@ -39,7 +39,7 @@ from .programs import community_markers, community_score # noqa: E402
39
39
  from .reclustering import reclustering_presets # noqa: E402
40
40
  from .specificity import annotate_specificity, specificity_enrichment # noqa: E402
41
41
 
42
- __version__ = "4.5.0"
42
+ __version__ = "4.5.1"
43
43
  __all__ = [
44
44
  "ThreadfinResult",
45
45
  "DensityResult",
@@ -150,8 +150,14 @@ class ThreadfinResult:
150
150
  vc = VarianceComponents(np.asarray(prof_vc["sigma2"]), np.asarray(prof_vc["tau2"]),
151
151
  prof_vc["n0"], prof_vc["n_clones"], prof_vc["n_cells"],
152
152
  np.zeros(len(prof_vc["tau2"])))
153
+ n_half = vc.min_cells_for(0.5)
153
154
  lines.append(f" Profiles are shrunk towards the mean, so a clone reaches reliability 0.5 at "
154
- f"{vc.min_cells_for(0.5)} cells. No clone is filtered out on reliability.")
155
+ f"{n_half} {'cell' if n_half == 1 else 'cells'}. No clone is filtered out on reliability.")
156
+ n_profiled = int(prof_vc["n_clones"])
157
+ if n_profiled < 10:
158
+ lines.append(f" Caution: only {n_profiled} clones have two or more cells. Estimates from so few clones "
159
+ "are unstable; Threadfin's power analyses need about 10 clones to detect a clonal ICC "
160
+ "of 0.1, and more for weaker effects.")
155
161
  prog = self.programmes
156
162
  lines += ["", "2. Which clones behave alike? (clonal programmes)"]
157
163
  if prog.empty:
@@ -408,7 +414,7 @@ class ThreadfinResult:
408
414
  """Overview figure (clone map, coherence test, programme composition, stability)."""
409
415
  from .plotting import overview
410
416
 
411
- return overview(self.adata, state_key=self.settings.get("state_key"), save=save)
417
+ return overview(self.adata, state_key=self.settings.get("state_key"), coherence_result=self.coherence, save=save)
412
418
 
413
419
 
414
420
  # --------------------------------------------------------------------------- the pipeline
@@ -553,7 +559,7 @@ def run(
553
559
  raise ValueError(
554
560
  "No barcode of the receptor data matches adata.obs_names. Check that both use the same barcode "
555
561
  "format; for multi-sample data, harmonise the barcodes first (see "
556
- "barcode_prefix/barcode_suffix in threadfin.read_bcr())."
562
+ "tutorial 2, section 4: prefix the cell_id column of the contig table)."
557
563
  )
558
564
  if donor_key is not None:
559
565
  donor_of_cell = pd.Series(adata.obs[donor_key].astype(str).to_numpy(),
@@ -568,7 +574,9 @@ def run(
568
574
  "Matched receptor contigs produced no clone calls. Each retained cell needs "
569
575
  "heavy-chain (TCR: beta or delta) V and J calls plus a non-empty junction/CDR3 sequence."
570
576
  )
571
- if not isinstance(bcr, (str, Path)): # a DataFrame or a scirpy object: clone ids only
577
+ if not isinstance(bcr, (str, Path)) or receptor != "BCR":
578
+ # a DataFrame or a scirpy object, or T-cell contigs (read_bcr summarises B-cell chains only):
579
+ # clone ids only
572
580
  table = ids.rename(clone_key).to_frame()
573
581
  table.index.name = "barcode"
574
582
  else: