threadfin 4.5.0__tar.gz → 4.5.2__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 (65) hide show
  1. {threadfin-4.5.0/threadfin.egg-info → threadfin-4.5.2}/PKG-INFO +112 -70
  2. {threadfin-4.5.0 → threadfin-4.5.2}/README.md +110 -68
  3. {threadfin-4.5.0 → threadfin-4.5.2}/pyproject.toml +4 -3
  4. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_dandelion_adapter.py +9 -0
  5. threadfin-4.5.2/tests/test_user_inputs.py +246 -0
  6. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/__init__.py +1 -1
  7. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/api.py +38 -12
  8. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/dandelion.py +17 -3
  9. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/plotting.py +37 -16
  10. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/profiles.py +5 -7
  11. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/programmes.py +18 -18
  12. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/stats.py +33 -8
  13. {threadfin-4.5.0 → threadfin-4.5.2/threadfin.egg-info}/PKG-INFO +112 -70
  14. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin.egg-info/requires.txt +1 -1
  15. threadfin-4.5.0/tests/test_user_inputs.py +0 -119
  16. {threadfin-4.5.0 → threadfin-4.5.2}/LICENSE +0 -0
  17. {threadfin-4.5.0 → threadfin-4.5.2}/setup.cfg +0 -0
  18. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_api_reference.py +0 -0
  19. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_bcrgraph_clones.py +0 -0
  20. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_bone_marrow_design.py +0 -0
  21. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_case_study_signatures.py +0 -0
  22. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_clone_state_sharing.py +0 -0
  23. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_clones_v3.py +0 -0
  24. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_density.py +0 -0
  25. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_ebv_contig_matching.py +0 -0
  26. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_export.py +0 -0
  27. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_integrate.py +0 -0
  28. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_io.py +0 -0
  29. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_maptune.py +0 -0
  30. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_migration.py +0 -0
  31. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_parallel_and_robustness.py +0 -0
  32. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_phylo.py +0 -0
  33. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_profile_reproducibility.py +0 -0
  34. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_programs.py +0 -0
  35. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_reclustering_presets.py +0 -0
  36. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_release_metadata.py +0 -0
  37. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_sequence_v2.py +0 -0
  38. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_specificity.py +0 -0
  39. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_threadfin.py +0 -0
  40. {threadfin-4.5.0 → threadfin-4.5.2}/tests/test_v4_core.py +0 -0
  41. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/_utils.py +0 -0
  42. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/bcrgraph.py +0 -0
  43. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/clones.py +0 -0
  44. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/core.py +0 -0
  45. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/density.py +0 -0
  46. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/dynamics.py +0 -0
  47. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/export.py +0 -0
  48. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/expression.py +0 -0
  49. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/heritability.py +0 -0
  50. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/integrate.py +0 -0
  51. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/io.py +0 -0
  52. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/maptune.py +0 -0
  53. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/metrics.py +0 -0
  54. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/migration.py +0 -0
  55. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/phylo.py +0 -0
  56. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/pp.py +0 -0
  57. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/programs.py +0 -0
  58. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/reclustering.py +0 -0
  59. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/sequence.py +0 -0
  60. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/simulate.py +0 -0
  61. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/specificity.py +0 -0
  62. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin/tl.py +0 -0
  63. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin.egg-info/SOURCES.txt +0 -0
  64. {threadfin-4.5.0 → threadfin-4.5.2}/threadfin.egg-info/dependency_links.txt +0 -0
  65. {threadfin-4.5.0 → threadfin-4.5.2}/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.2
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,108 @@ 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>
69
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
68
+ <a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
69
+ <a href="https://github.com/Reynold4k/Threadfin/blob/main/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 with two or more cells, tests clonal coherence, lays out the
113
+ clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
114
+ 15 minutes with 8 cores.
115
+
116
+ ### 3. Read the results
117
+
118
+ ```python
119
+ print(result.summary()) # plain-language report
120
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, programme sizes or composition
121
+ print(result.methods()) # a Methods paragraph with the settings and versions used
122
+ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, reliability, programme, map position
123
+ ```
124
+
125
+ <p align="center">
126
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
127
+ </p>
128
+
129
+ | What you get | Where |
130
+ |---|---|
131
+ | Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
132
+ | A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
133
+ | Groups of clones that behave alike, with their stability | `result.programmes`; `adata.obs["clone_programme"]` |
134
+ | How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
135
+ | A Methods paragraph for your paper, with references | `result.methods()` |
136
+
137
+ ### Common variations
138
+
139
+ * **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
140
+ `tf.run(..., test=["antigen_binding", "isotype"])`.
141
+ * **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
142
+ * **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
143
+ * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
144
+ * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
145
+ * **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
146
+ on 8 cores.
147
+ * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
148
+ has clone ids and an embedding, so run it with
149
+ `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
150
+
151
+ ### Tutorials
152
+
153
+ | Tutorial | What it covers |
154
+ |---|---|
155
+ | [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 |
156
+ | [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 |
157
+ | [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 |
158
+ | [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
159
+ | [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) |
160
+
161
+ 4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
162
+ reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
163
+ input, `result.methods()` and gene-level summaries of the clone landscape
164
+ ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
165
+
166
+ ---
167
+
168
+ ## What Threadfin does
169
+
72
170
  **Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
73
171
  uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
74
172
  Each clone is represented by the distribution of transcriptional states among its sampled cells,
@@ -89,9 +187,11 @@ state* need the clone as the unit of representation and of statistical inference
89
187
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
90
188
 
91
189
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
92
- sampled, and each clone carries a reliability score. No clone is discarded for being small.
190
+ sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
191
+ small.
93
192
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
94
- relative to the cells sampled with it, and every test shuffles labels within the sampling design.
193
+ relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
194
+ design.
95
195
  * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
96
196
 
97
197
  ## What Threadfin answers
@@ -127,62 +227,6 @@ manuscript — status, datasets, every analysis and a benchmark against related
127
227
  the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
128
228
  clone profiles but were each sequenced in their own library.
129
229
 
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
230
  ## A clone embedding that holds together
187
231
 
188
232
  UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
@@ -206,7 +250,8 @@ tf.tl.map_quality(features, xy) # score any clone map (p
206
250
  <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
207
251
  </p>
208
252
 
209
- 1. **Clones** are defined from paired heavy- and light-chain sequences within each donor (Dandelion).
253
+ 1. **Clones** are defined from paired heavy- and light-chain sequences (for T cells, beta and alpha chains)
254
+ within each donor (Dandelion).
210
255
  2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
211
256
  a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
212
257
  between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
@@ -226,18 +271,15 @@ The full description, with references, is in [Methods](https://github.com/Reynol
226
271
 
227
272
  | | |
228
273
  |---|---|
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
274
  | [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
235
275
  | [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
276
+ | [Compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md) | Python and dependency versions, operating systems and datasets tested |
277
+ | [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
236
278
  | [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
237
279
  | [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
238
280
  | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
239
281
  | [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 |
282
+ | [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
283
 
242
284
  ## Citation
243
285
 
@@ -256,7 +298,7 @@ error rate when samples differ, where per-clone graph scores and cell-level test
256
298
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
257
299
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
258
300
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
259
- others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 300 to 2,400
301
+ others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
260
302
  times) and finished every run without help; a million cells take about an hour on 8 cores
261
303
  ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
262
304
  The benchmark reports every result, including those where Threadfin is not the best.
@@ -11,10 +11,108 @@
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>
15
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
14
+ <a href="https://pypi.org/project/threadfin/"><img src="https://img.shields.io/pypi/v/threadfin.svg" alt="PyPI version"></a>
15
+ <a href="https://github.com/Reynold4k/Threadfin/blob/main/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 with two or more cells, tests clonal coherence, lays out the
59
+ clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
60
+ 15 minutes with 8 cores.
61
+
62
+ ### 3. Read the results
63
+
64
+ ```python
65
+ print(result.summary()) # plain-language report
66
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, programme sizes or composition
67
+ print(result.methods()) # a Methods paragraph with the settings and versions used
68
+ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, reliability, programme, map position
69
+ ```
70
+
71
+ <p align="center">
72
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
73
+ </p>
74
+
75
+ | What you get | Where |
76
+ |---|---|
77
+ | Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
78
+ | A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
79
+ | Groups of clones that behave alike, with their stability | `result.programmes`; `adata.obs["clone_programme"]` |
80
+ | How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
81
+ | A Methods paragraph for your paper, with references | `result.methods()` |
82
+
83
+ ### Common variations
84
+
85
+ * **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
86
+ `tf.run(..., test=["antigen_binding", "isotype"])`.
87
+ * **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
88
+ * **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
89
+ * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
90
+ * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
91
+ * **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
92
+ on 8 cores.
93
+ * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
94
+ has clone ids and an embedding, so run it with
95
+ `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
96
+
97
+ ### Tutorials
98
+
99
+ | Tutorial | What it covers |
100
+ |---|---|
101
+ | [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 |
102
+ | [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 |
103
+ | [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 |
104
+ | [4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
105
+ | [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) |
106
+
107
+ 4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
108
+ reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
109
+ input, `result.methods()` and gene-level summaries of the clone landscape
110
+ ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
111
+
112
+ ---
113
+
114
+ ## What Threadfin does
115
+
18
116
  **Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
19
117
  uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
20
118
  Each clone is represented by the distribution of transcriptional states among its sampled cells,
@@ -35,9 +133,11 @@ state* need the clone as the unit of representation and of statistical inference
35
133
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
36
134
 
37
135
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
38
- sampled, and each clone carries a reliability score. No clone is discarded for being small.
136
+ sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
137
+ small.
39
138
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
40
- relative to the cells sampled with it, and every test shuffles labels within the sampling design.
139
+ relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
140
+ design.
41
141
  * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
42
142
 
43
143
  ## What Threadfin answers
@@ -73,62 +173,6 @@ manuscript — status, datasets, every analysis and a benchmark against related
73
173
  the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
74
174
  clone profiles but were each sequenced in their own library.
75
175
 
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
176
  ## A clone embedding that holds together
133
177
 
134
178
  UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
@@ -152,7 +196,8 @@ tf.tl.map_quality(features, xy) # score any clone map (p
152
196
  <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
153
197
  </p>
154
198
 
155
- 1. **Clones** are defined from paired heavy- and light-chain sequences within each donor (Dandelion).
199
+ 1. **Clones** are defined from paired heavy- and light-chain sequences (for T cells, beta and alpha chains)
200
+ within each donor (Dandelion).
156
201
  2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
157
202
  a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
158
203
  between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
@@ -172,18 +217,15 @@ The full description, with references, is in [Methods](https://github.com/Reynol
172
217
 
173
218
  | | |
174
219
  |---|---|
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
220
  | [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
181
221
  | [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
222
+ | [Compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md) | Python and dependency versions, operating systems and datasets tested |
223
+ | [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
182
224
  | [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
183
225
  | [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
184
226
  | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
185
227
  | [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 |
228
+ | [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
229
 
188
230
  ## Citation
189
231
 
@@ -202,7 +244,7 @@ error rate when samples differ, where per-clone graph scores and cell-level test
202
244
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
203
245
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
204
246
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
205
- others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 300 to 2,400
247
+ others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
206
248
  times) and finished every run without help; a million cells take about an hour on 8 cores
207
249
  ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
208
250
  The benchmark reports every result, including those where Threadfin is not the best.
@@ -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.2"
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()