threadfin 4.5.2__tar.gz → 4.6.0__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 (76) hide show
  1. {threadfin-4.5.2/threadfin.egg-info → threadfin-4.6.0}/PKG-INFO +92 -43
  2. {threadfin-4.5.2 → threadfin-4.6.0}/README.md +89 -40
  3. {threadfin-4.5.2 → threadfin-4.6.0}/pyproject.toml +8 -4
  4. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_api_reference.py +4 -0
  5. threadfin-4.6.0/tests/test_association_strata.py +299 -0
  6. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_bone_marrow_design.py +2 -0
  7. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_case_study_signatures.py +2 -0
  8. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_clone_state_sharing.py +5 -1
  9. threadfin-4.6.0/tests/test_dandelion_seed.py +254 -0
  10. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_ebv_contig_matching.py +5 -1
  11. threadfin-4.6.0/tests/test_geneset_and_export.py +315 -0
  12. threadfin-4.6.0/tests/test_memory_reference.py +337 -0
  13. threadfin-4.6.0/tests/test_read_paths.py +163 -0
  14. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_release_metadata.py +4 -0
  15. threadfin-4.6.0/tests/test_result_plots.py +104 -0
  16. threadfin-4.6.0/tests/test_statistical_properties.py +581 -0
  17. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_user_inputs.py +2 -0
  18. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_v4_core.py +90 -0
  19. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/__init__.py +1 -1
  20. threadfin-4.6.0/threadfin/_dandelion_worker.py +225 -0
  21. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/_utils.py +33 -0
  22. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/api.py +304 -61
  23. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/dandelion.py +226 -75
  24. threadfin-4.6.0/threadfin/dynamics.py +503 -0
  25. threadfin-4.6.0/threadfin/export.py +403 -0
  26. threadfin-4.6.0/threadfin/heritability.py +518 -0
  27. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/plotting.py +27 -16
  28. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/pp.py +15 -5
  29. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/profiles.py +24 -11
  30. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/programmes.py +59 -29
  31. threadfin-4.6.0/threadfin/stats.py +761 -0
  32. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/tl.py +5 -3
  33. {threadfin-4.5.2 → threadfin-4.6.0/threadfin.egg-info}/PKG-INFO +92 -43
  34. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin.egg-info/SOURCES.txt +8 -0
  35. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin.egg-info/requires.txt +3 -1
  36. threadfin-4.5.2/threadfin/dynamics.py +0 -275
  37. threadfin-4.5.2/threadfin/export.py +0 -215
  38. threadfin-4.5.2/threadfin/heritability.py +0 -224
  39. threadfin-4.5.2/threadfin/stats.py +0 -501
  40. {threadfin-4.5.2 → threadfin-4.6.0}/LICENSE +0 -0
  41. {threadfin-4.5.2 → threadfin-4.6.0}/setup.cfg +0 -0
  42. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_bcrgraph_clones.py +0 -0
  43. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_clones_v3.py +0 -0
  44. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_dandelion_adapter.py +0 -0
  45. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_density.py +0 -0
  46. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_export.py +0 -0
  47. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_integrate.py +0 -0
  48. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_io.py +0 -0
  49. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_maptune.py +0 -0
  50. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_migration.py +0 -0
  51. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_parallel_and_robustness.py +0 -0
  52. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_phylo.py +0 -0
  53. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_profile_reproducibility.py +0 -0
  54. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_programs.py +0 -0
  55. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_reclustering_presets.py +0 -0
  56. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_sequence_v2.py +0 -0
  57. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_specificity.py +0 -0
  58. {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_threadfin.py +0 -0
  59. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/bcrgraph.py +0 -0
  60. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/clones.py +0 -0
  61. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/core.py +0 -0
  62. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/density.py +0 -0
  63. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/expression.py +0 -0
  64. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/integrate.py +0 -0
  65. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/io.py +0 -0
  66. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/maptune.py +0 -0
  67. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/metrics.py +0 -0
  68. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/migration.py +0 -0
  69. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/phylo.py +0 -0
  70. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/programs.py +0 -0
  71. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/reclustering.py +0 -0
  72. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/sequence.py +0 -0
  73. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/simulate.py +0 -0
  74. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/specificity.py +0 -0
  75. {threadfin-4.5.2 → threadfin-4.6.0}/threadfin.egg-info/dependency_links.txt +0 -0
  76. {threadfin-4.5.2 → threadfin-4.6.0}/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.2
3
+ Version: 4.6.0
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
@@ -33,12 +33,12 @@ Requires-Dist: matplotlib>=3.7
33
33
  Requires-Dist: igraph>=0.10
34
34
  Requires-Dist: leidenalg>=0.10
35
35
  Requires-Dist: umap-learn>=0.5.5
36
- Requires-Dist: pynndescent>=0.5.8
36
+ Requires-Dist: pynndescent<0.7,>=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
40
  Requires-Dist: sc-dandelion<1,>=0.5.7; extra == "dandelion"
41
- Requires-Dist: matplotlib<3.9,>=3.7; extra == "dandelion"
41
+ Requires-Dist: matplotlib<3.9,>=3.7; python_version < "3.13" and extra == "dandelion"
42
42
  Provides-Extra: seq
43
43
  Requires-Dist: parasail>=1.3; extra == "seq"
44
44
  Provides-Extra: data
@@ -81,10 +81,13 @@ pip install threadfin # Python 3.10–3.14 on Linux, macOS or W
81
81
  pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs
82
82
  ```
83
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"`.
84
+ Scanpy, Leiden, UMAP and Harmony are installed with it; a fresh `pip install "threadfin[dandelion]"` takes about
85
+ 3 minutes. Clone calls are the same in every Python session, with no setting needed. Dandelion's clone calls
86
+ depend on Python's string-hash seed, so Threadfin always calls them under seed 0, in a separate Python process
87
+ when Python was not started with `PYTHONHASHSEED=0` (about 2 s more). Threadfin is validated with Dandelion 0.5.x;
88
+ Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`.
89
+ The development version installs with
90
+ `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
88
91
 
89
92
  ### 2. Run
90
93
 
@@ -104,14 +107,14 @@ result = tf.run(
104
107
  donor_key="donor", # the individual each cell came from
105
108
  sample_key="sample", # the sample or library each cell came from (never a sort gate,
106
109
  # 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
110
+ n_jobs=8, # processes to use; the result is the same for any number
108
111
  )
109
112
  ```
110
113
 
111
114
  `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
112
115
  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.
116
+ clone map and looks for clonal programmes. On the 16 public datasets tested (884 to 206,000 cells) it took about 1
117
+ to 11 minutes with 8 cores ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
115
118
 
116
119
  ### 3. Read the results
117
120
 
@@ -128,9 +131,9 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
128
131
 
129
132
  | What you get | Where |
130
133
  |---|---|
131
- | Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
134
+ | Are cells of one clone more alike than cells of different clones? Clonal coherence, its excess over shuffled clone labels and its permutation P value | `result.coherence`; first part of the summary |
132
135
  | 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"]` |
136
+ | Groups of clones that behave alike (programmes), with their stability and state composition | `result.programmes`; `result.composition`; `adata.obs["clone_programme"]` |
134
137
  | How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
135
138
  | A Methods paragraph for your paper, with references | `result.methods()` |
136
139
 
@@ -138,16 +141,44 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
138
141
 
139
142
  * **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
140
143
  `tf.run(..., test=["antigen_binding", "isotype"])`.
144
+ * **Several tissues or sort gates per donor**, each sequenced in its own libraries: describe clones relative to the
145
+ donor, so that differences between tissues are kept, and shuffle clone labels within libraries,
146
+ `tf.run(..., sample_key="donor", strata_key="sample")`
147
+ ([Tutorial 2, section 5](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md#5-choosing-donor_key-sample_key-strata_key-and-batch_key)).
141
148
  * **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
149
+ * **Programmes described per clone**: with `state_key=`, the state composition of each programme is the share of
150
+ its cells in each state; `composition_weight="clones"` counts every clone once instead.
142
151
  * **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
143
152
  * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
144
153
  * **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.
154
+ * **Large data**: `n_jobs=-1` uses every CPU core ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
155
+ * **Identical results**: `n_jobs` never changes a result. The automatically chosen clone map can change with the
156
+ number of BLAS threads, so keep `OMP_NUM_THREADS` the same between runs; every statistic agrees to about 1e-7
157
+ either way. Random draws follow the order of the cells, so the same cells in another order can give different
158
+ programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
159
+ depend on the order.
147
160
  * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
148
161
  has clone ids and an embedding, so run it with
149
162
  `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
150
163
 
164
+ ### Run time and memory
165
+
166
+ The complete `tf.run`, from raw counts and contigs to the summary, on subsamples of a real dataset (EBV tonsil
167
+ organoids, GSE317492) with 8 cores:
168
+
169
+ | Cells | Time | Extra peak memory |
170
+ |---|---|---|
171
+ | 25,000 | 100 s | 2.3 GB |
172
+ | 50,000 | 160 s | 4.7 GB |
173
+ | 100,000 | 329 s | 9.2 GB |
174
+ | 205,630 | 650 s | 18.6 GB |
175
+
176
+ Time grows about linearly with the number of cells. Clone calling with Dandelion is the longest step (45 % of the
177
+ run at full size). The extra peak memory comes on top of the loaded data, about 0.09 GB per 1,000 cells, and is set
178
+ by building the expression embedding. With a precomputed embedding and given clone ids, the remaining steps take
179
+ about an hour for a million simulated cells on 8 cores
180
+ ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
181
+
151
182
  ### Tutorials
152
183
 
153
184
  | Tutorial | What it covers |
@@ -158,10 +189,20 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
158
189
  | [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
190
  | [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
191
 
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)).
192
+ New in 4.6.0: `strata_key=` names the sampling unit within which the coherence test shuffles clone labels when it
193
+ is finer than the context (`sample_key`); `composition_weight="clones"` describes each programme by its average
194
+ clone; the summary states the excess of clonal coherence over shuffled labels, the strata used and the order of
195
+ time points or tissues. Clone calls are identical in every session, with no setting. The Dandelion extra installs
196
+ on Python 3.10–3.14. Clonal memory compares a clone with other clones of its donor seen at the same two levels,
197
+ with each snapshot's own noise. The gene-set test allows for co-expressed genes. Export-lag intervals hold for
198
+ any distribution, also in days. Label tests shuffle among clones of the same donor and of similar size, and flag
199
+ labels fixed within each sample. The run is recorded in the AnnData, and `ThreadfinResult.from_adata` rebuilds
200
+ the result after saving.
201
+ 4.5.3 keeps pynndescent below 0.7; 4.5.2 lists labels that are fixed within each donor
202
+ (age, sex) as not testable instead of reporting p = 1, and reads raw counts from a layer (`counts_layer=`); 4.5.1
203
+ pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy input, `result.methods()` and gene-level summaries of the
204
+ clone landscape ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
205
+
165
206
 
166
207
  ---
167
208
 
@@ -182,28 +223,29 @@ measured. Threadfin works with [AnnData](https://anndata.readthedocs.io) and
182
223
  The cells of one clone are distributed across states: germinal-centre (GC) B cells, plasmablasts, plasma
183
224
  cells and memory B cells. Two clones can have the same average state and still differ in how their cells
184
225
  are distributed. Selection, antigen affinity and fate bias act on clones, so questions such as *which
185
- clones connect the germinal centre with plasma-cell output* or *does antigen binding go with a clone's
186
- state* need the clone as the unit of representation and of statistical inference. Three features of
226
+ clones connect the germinal centre with antibody-secreting cells (ASCs)* or *does antigen binding go with a
227
+ clone's state* need the clone as the unit of representation and of statistical inference. Three features of
187
228
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
188
229
 
189
230
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
190
231
  sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
191
232
  small.
192
233
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
193
- relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
194
- design.
195
- * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
234
+ relative to the cells sampled with it, and every permutation test shuffles labels only within the units of
235
+ the sampling design: clone labels within libraries, the labels you test within donors.
236
+ * **Treating cells as independent inflates significance.** Label tests use clones, not cells, as replicates,
237
+ and the coherence test compares real clones with random clones of the same sizes.
196
238
 
197
239
  ## What Threadfin answers
198
240
 
199
241
  | Question | Output | Function |
200
242
  |---|---|---|
201
- | Is cell state inherited within clones? | clonal coherence: variance explained by clone, against labels shuffled within samples | `tl.clonal_coherence` |
202
- | How are clones related to one another? | the clone embedding, laid out automatically so that continua stay connected | `tl.embed_clones` |
243
+ | Are cells of one clone more alike than cells of different clones? | clonal coherence: the share of the variance of cell states explained by clone, against clone labels shuffled within sampling units | `tl.clonal_coherence` |
244
+ | How similar are clones to one another? | the clone embedding, laid out automatically so that it is no more fragmented than the clone profiles | `tl.embed_clones` |
203
245
  | Which clones behave alike? | clonal programmes, with split tests and bootstrap stability | `tl.find_programmes` |
204
246
  | What explains the differences between clones? | variance in clone profiles explained by a label; per-programme effects | `tl.profile_association`, `tl.association_test` |
205
247
  | Do clones keep their state over time or across tissues? | the clonal memory index | `tl.clonal_memory` |
206
- | How far behind its germinal centre is a clone's output? | the export lag, in somatic mutations and in days | `tl.export_lag` |
248
+ | How much less mutated is a clone's output than its own germinal-centre cells? | the median within-clone mutation gap with a sign-test interval; with a time column, also in days at the germinal centre's rate, with an interval | `tl.export_lag` |
207
249
 
208
250
  ## Examples from public data
209
251
 
@@ -213,9 +255,10 @@ further public datasets are in [case studies](https://github.com/Reynold4k/Threa
213
255
  manuscript — status, datasets, every analysis and a benchmark against related tools — is in
214
256
  [`manuscript/`](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md).
215
257
 
216
- * **Gut-associated lymphoid tissues** (Siniscalco *et al.*, *Immunity* 2025): the clone embedding resolves
217
- a continuous path of clones from GC B cells, through clones that contain both GC B cells and plasma
218
- cells, to plasma-cell clones, with clones that lack GC-fate labelling grouped at its end.
258
+ * **Gut-associated lymphoid tissues** (Siniscalco *et al.*, *Immunity* 2025): the clone embedding orders the
259
+ clones from GC B-cell clones, through clones that contain both GC B cells and ASCs, to ASC clones; clones
260
+ whose ASCs lack GC-fate labelling group at the ASC end, and the isotype measured in the BCR sequences changes
261
+ along the order (IgG1 to IgA).
219
262
  * **Spontaneous germinal centres** (Castrillon *et al.*, *eLife* 2023): position along the clone embedding
220
263
  orders clones by the diversity of their cell states, and memory-containing clones concentrate at one
221
264
  end.
@@ -223,20 +266,23 @@ manuscript — status, datasets, every analysis and a benchmark against related
223
266
  together with GC B cells of the same clone is a property of clones that cannot be read from the
224
267
  cell-level embedding.
225
268
  * **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
226
- between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed, so
227
- the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
228
- clone profiles but were each sequenced in their own library.
269
+ between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed; a
270
+ library effect would push the two cohorts in opposite directions, and their division directions agree
271
+ (cosine similarity 0.89). Antigen-bait and dark-zone gates are also associated with clone profiles but were
272
+ each sequenced in their own library.
229
273
 
230
274
  ## A clone embedding that holds together
231
275
 
232
- UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
276
+ UMAP draws connected populations of clones as one picture only for suitable settings, and the suitable
233
277
  settings differ between datasets. Threadfin therefore chooses them for each dataset by default: it lays
234
278
  the clones out over a ladder of settings, scores each layout for coherence (the fraction of clones in one
235
279
  connected piece) and for fidelity to the clone profiles, and keeps the most faithful setting that holds
236
280
  together in every layout it tried. A map is not allowed to be more fragmented than the clone profiles
237
281
  themselves, and the final map is checked once more before it is returned. The record of the choice is
238
282
  stored with the results, and the settings can always be fixed by hand
239
- ([Tutorial 3](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md)).
283
+ ([Tutorial 3](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md)). Because the
284
+ layout is chosen to stay connected, a connected map is not evidence of a continuum: whether clones form groups
285
+ is judged from the programmes, their stability and the tests, which use the profiles.
240
286
 
241
287
  ```python
242
288
  tf.tl.embed_clones(adata) # automatic (default)
@@ -255,13 +301,13 @@ tf.tl.map_quality(features, xy) # score any clone map (p
255
301
  2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
256
302
  a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
257
303
  between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
258
- context according to the number of cells (best linear unbiased prediction under a random-effects
259
- model).
260
- 3. **Clonal coherence** is the intraclass correlation of state within clones, tested against clone labels
261
- permuted within samples.
304
+ average profile of all profiled clones according to the number of cells (best linear unbiased prediction
305
+ under a random-effects model).
306
+ 3. **Clonal coherence** is the intraclass correlation of cell states (the expression embedding) within clones,
307
+ tested against clone labels permuted within sampling units (`strata_key`; by default the sampling context).
262
308
  4. **The clone embedding** is a UMAP of the clone profiles with settings chosen as above.
263
309
  5. **Clonal programmes** are graph communities of clones; each split is tested against a single Gaussian
264
- group, and each programme's stability is estimated by bootstrap resampling.
310
+ group, and each programme's stability is estimated by resampling the cells of every clone.
265
311
  6. **Clone-level tests** quantify how much of the variance between clone profiles a label explains, with
266
312
  labels permuted among the clones of each donor.
267
313
 
@@ -280,6 +326,7 @@ The full description, with references, is in [Methods](https://github.com/Reynol
280
326
  | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
281
327
  | [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
282
328
  | [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 |
329
+ | [Figure gallery](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/tutorial_path/figures/README.md) | every figure Threadfin draws, for each of the 16 public datasets of the technical validation |
283
330
 
284
331
  ## Citation
285
332
 
@@ -293,14 +340,16 @@ Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2
293
340
  Clonotrace, clone2vec, Benisse and CoNGA also combine lineage and transcriptome, and answer related but
294
341
  different questions. On the same data and clones ([benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md), with a
295
342
  one-page overview): Threadfin and Benisse represent every clone with two or more cells by default
296
- (clone2vec starts at three cells, Clonotrace at ten), and Threadfin's test of clonal coherence keeps its
297
- error rate when samples differ, where per-clone graph scores and cell-level tests do not. For recovering
343
+ (clone2vec starts at three cells, Clonotrace at ten), and Threadfin's test of clonal coherence, with clone
344
+ labels shuffled within samples, keeps its error rate when samples differ, where per-clone graph scores and
345
+ cell-level tests do not. For recovering
298
346
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
299
347
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
300
348
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
301
349
  others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
302
- times) and finished every run without help; a million cells take about an hour on 8 cores
303
- ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
350
+ times) and finished every run without help. The complete analysis of 205,630 cells takes 11 minutes on 8
351
+ cores, and with a precomputed embedding and given clone ids a million simulated cells take about an hour
352
+ ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
304
353
  The benchmark reports every result, including those where Threadfin is not the best.
305
354
 
306
355
  ## Related tools
@@ -27,10 +27,13 @@ pip install threadfin # Python 3.10–3.14 on Linux, macOS or W
27
27
  pip install "threadfin[dandelion]" # also installs Dandelion (0.5.x), to call clones from BCR or TCR contigs
28
28
  ```
29
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"`.
30
+ Scanpy, Leiden, UMAP and Harmony are installed with it; a fresh `pip install "threadfin[dandelion]"` takes about
31
+ 3 minutes. Clone calls are the same in every Python session, with no setting needed. Dandelion's clone calls
32
+ depend on Python's string-hash seed, so Threadfin always calls them under seed 0, in a separate Python process
33
+ when Python was not started with `PYTHONHASHSEED=0` (about 2 s more). Threadfin is validated with Dandelion 0.5.x;
34
+ Dandelion 1.0 (October 2026) calls clones differently, so the extra installs `sc-dandelion<1`.
35
+ The development version installs with
36
+ `pip install "git+https://github.com/Reynold4k/Threadfin.git"`.
34
37
 
35
38
  ### 2. Run
36
39
 
@@ -50,14 +53,14 @@ result = tf.run(
50
53
  donor_key="donor", # the individual each cell came from
51
54
  sample_key="sample", # the sample or library each cell came from (never a sort gate,
52
55
  # 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
56
+ n_jobs=8, # processes to use; the result is the same for any number
54
57
  )
55
58
  ```
56
59
 
57
60
  `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
58
61
  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.
62
+ clone map and looks for clonal programmes. On the 16 public datasets tested (884 to 206,000 cells) it took about 1
63
+ to 11 minutes with 8 cores ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
61
64
 
62
65
  ### 3. Read the results
63
66
 
@@ -74,9 +77,9 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
74
77
 
75
78
  | What you get | Where |
76
79
  |---|---|
77
- | Does clone identity shape cell state? Clonal coherence, with its permutation P value | `result.coherence`; first part of the summary |
80
+ | Are cells of one clone more alike than cells of different clones? Clonal coherence, its excess over shuffled clone labels and its permutation P value | `result.coherence`; first part of the summary |
78
81
  | 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"]` |
82
+ | Groups of clones that behave alike (programmes), with their stability and state composition | `result.programmes`; `result.composition`; `adata.obs["clone_programme"]` |
80
83
  | How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
81
84
  | A Methods paragraph for your paper, with references | `result.methods()` |
82
85
 
@@ -84,16 +87,44 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
84
87
 
85
88
  * **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
86
89
  `tf.run(..., test=["antigen_binding", "isotype"])`.
90
+ * **Several tissues or sort gates per donor**, each sequenced in its own libraries: describe clones relative to the
91
+ donor, so that differences between tissues are kept, and shuffle clone labels within libraries,
92
+ `tf.run(..., sample_key="donor", strata_key="sample")`
93
+ ([Tutorial 2, section 5](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md#5-choosing-donor_key-sample_key-strata_key-and-batch_key)).
87
94
  * **Time points or tissues**, to ask whether clones keep their state: `tf.run(..., time_key="timepoint")`.
95
+ * **Programmes described per clone**: with `state_key=`, the state composition of each programme is the share of
96
+ its cells in each state; `composition_weight="clones"` counts every clone once instead.
88
97
  * **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
89
98
  * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
90
99
  * **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.
100
+ * **Large data**: `n_jobs=-1` uses every CPU core ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
101
+ * **Identical results**: `n_jobs` never changes a result. The automatically chosen clone map can change with the
102
+ number of BLAS threads, so keep `OMP_NUM_THREADS` the same between runs; every statistic agrees to about 1e-7
103
+ either way. Random draws follow the order of the cells, so the same cells in another order can give different
104
+ programmes; sort them first (`adata = adata[adata.obs_names.sort_values()].copy()`) when results must not
105
+ depend on the order.
93
106
  * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
94
107
  has clone ids and an embedding, so run it with
95
108
  `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
96
109
 
110
+ ### Run time and memory
111
+
112
+ The complete `tf.run`, from raw counts and contigs to the summary, on subsamples of a real dataset (EBV tonsil
113
+ organoids, GSE317492) with 8 cores:
114
+
115
+ | Cells | Time | Extra peak memory |
116
+ |---|---|---|
117
+ | 25,000 | 100 s | 2.3 GB |
118
+ | 50,000 | 160 s | 4.7 GB |
119
+ | 100,000 | 329 s | 9.2 GB |
120
+ | 205,630 | 650 s | 18.6 GB |
121
+
122
+ Time grows about linearly with the number of cells. Clone calling with Dandelion is the longest step (45 % of the
123
+ run at full size). The extra peak memory comes on top of the loaded data, about 0.09 GB per 1,000 cells, and is set
124
+ by building the expression embedding. With a precomputed embedding and given clone ids, the remaining steps take
125
+ about an hour for a million simulated cells on 8 cores
126
+ ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
127
+
97
128
  ### Tutorials
98
129
 
99
130
  | Tutorial | What it covers |
@@ -104,10 +135,20 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
104
135
  | [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
136
  | [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
137
 
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)).
138
+ New in 4.6.0: `strata_key=` names the sampling unit within which the coherence test shuffles clone labels when it
139
+ is finer than the context (`sample_key`); `composition_weight="clones"` describes each programme by its average
140
+ clone; the summary states the excess of clonal coherence over shuffled labels, the strata used and the order of
141
+ time points or tissues. Clone calls are identical in every session, with no setting. The Dandelion extra installs
142
+ on Python 3.10–3.14. Clonal memory compares a clone with other clones of its donor seen at the same two levels,
143
+ with each snapshot's own noise. The gene-set test allows for co-expressed genes. Export-lag intervals hold for
144
+ any distribution, also in days. Label tests shuffle among clones of the same donor and of similar size, and flag
145
+ labels fixed within each sample. The run is recorded in the AnnData, and `ThreadfinResult.from_adata` rebuilds
146
+ the result after saving.
147
+ 4.5.3 keeps pynndescent below 0.7; 4.5.2 lists labels that are fixed within each donor
148
+ (age, sex) as not testable instead of reporting p = 1, and reads raw counts from a layer (`counts_layer=`); 4.5.1
149
+ pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy input, `result.methods()` and gene-level summaries of the
150
+ clone landscape ([changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md)).
151
+
111
152
 
112
153
  ---
113
154
 
@@ -128,28 +169,29 @@ measured. Threadfin works with [AnnData](https://anndata.readthedocs.io) and
128
169
  The cells of one clone are distributed across states: germinal-centre (GC) B cells, plasmablasts, plasma
129
170
  cells and memory B cells. Two clones can have the same average state and still differ in how their cells
130
171
  are distributed. Selection, antigen affinity and fate bias act on clones, so questions such as *which
131
- clones connect the germinal centre with plasma-cell output* or *does antigen binding go with a clone's
132
- state* need the clone as the unit of representation and of statistical inference. Three features of
172
+ clones connect the germinal centre with antibody-secreting cells (ASCs)* or *does antigen binding go with a
173
+ clone's state* need the clone as the unit of representation and of statistical inference. Three features of
133
174
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
134
175
 
135
176
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
136
177
  sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
137
178
  small.
138
179
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
139
- relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
140
- design.
141
- * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
180
+ relative to the cells sampled with it, and every permutation test shuffles labels only within the units of
181
+ the sampling design: clone labels within libraries, the labels you test within donors.
182
+ * **Treating cells as independent inflates significance.** Label tests use clones, not cells, as replicates,
183
+ and the coherence test compares real clones with random clones of the same sizes.
142
184
 
143
185
  ## What Threadfin answers
144
186
 
145
187
  | Question | Output | Function |
146
188
  |---|---|---|
147
- | Is cell state inherited within clones? | clonal coherence: variance explained by clone, against labels shuffled within samples | `tl.clonal_coherence` |
148
- | How are clones related to one another? | the clone embedding, laid out automatically so that continua stay connected | `tl.embed_clones` |
189
+ | Are cells of one clone more alike than cells of different clones? | clonal coherence: the share of the variance of cell states explained by clone, against clone labels shuffled within sampling units | `tl.clonal_coherence` |
190
+ | How similar are clones to one another? | the clone embedding, laid out automatically so that it is no more fragmented than the clone profiles | `tl.embed_clones` |
149
191
  | Which clones behave alike? | clonal programmes, with split tests and bootstrap stability | `tl.find_programmes` |
150
192
  | What explains the differences between clones? | variance in clone profiles explained by a label; per-programme effects | `tl.profile_association`, `tl.association_test` |
151
193
  | Do clones keep their state over time or across tissues? | the clonal memory index | `tl.clonal_memory` |
152
- | How far behind its germinal centre is a clone's output? | the export lag, in somatic mutations and in days | `tl.export_lag` |
194
+ | How much less mutated is a clone's output than its own germinal-centre cells? | the median within-clone mutation gap with a sign-test interval; with a time column, also in days at the germinal centre's rate, with an interval | `tl.export_lag` |
153
195
 
154
196
  ## Examples from public data
155
197
 
@@ -159,9 +201,10 @@ further public datasets are in [case studies](https://github.com/Reynold4k/Threa
159
201
  manuscript — status, datasets, every analysis and a benchmark against related tools — is in
160
202
  [`manuscript/`](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md).
161
203
 
162
- * **Gut-associated lymphoid tissues** (Siniscalco *et al.*, *Immunity* 2025): the clone embedding resolves
163
- a continuous path of clones from GC B cells, through clones that contain both GC B cells and plasma
164
- cells, to plasma-cell clones, with clones that lack GC-fate labelling grouped at its end.
204
+ * **Gut-associated lymphoid tissues** (Siniscalco *et al.*, *Immunity* 2025): the clone embedding orders the
205
+ clones from GC B-cell clones, through clones that contain both GC B cells and ASCs, to ASC clones; clones
206
+ whose ASCs lack GC-fate labelling group at the ASC end, and the isotype measured in the BCR sequences changes
207
+ along the order (IgG1 to IgA).
165
208
  * **Spontaneous germinal centres** (Castrillon *et al.*, *eLife* 2023): position along the clone embedding
166
209
  orders clones by the diversity of their cell states, and memory-containing clones concentrate at one
167
210
  end.
@@ -169,20 +212,23 @@ manuscript — status, datasets, every analysis and a benchmark against related
169
212
  together with GC B cells of the same clone is a property of clones that cannot be read from the
170
213
  cell-level embedding.
171
214
  * **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
172
- between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed, so
173
- the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
174
- clone profiles but were each sequenced in their own library.
215
+ between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed; a
216
+ library effect would push the two cohorts in opposite directions, and their division directions agree
217
+ (cosine similarity 0.89). Antigen-bait and dark-zone gates are also associated with clone profiles but were
218
+ each sequenced in their own library.
175
219
 
176
220
  ## A clone embedding that holds together
177
221
 
178
- UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
222
+ UMAP draws connected populations of clones as one picture only for suitable settings, and the suitable
179
223
  settings differ between datasets. Threadfin therefore chooses them for each dataset by default: it lays
180
224
  the clones out over a ladder of settings, scores each layout for coherence (the fraction of clones in one
181
225
  connected piece) and for fidelity to the clone profiles, and keeps the most faithful setting that holds
182
226
  together in every layout it tried. A map is not allowed to be more fragmented than the clone profiles
183
227
  themselves, and the final map is checked once more before it is returned. The record of the choice is
184
228
  stored with the results, and the settings can always be fixed by hand
185
- ([Tutorial 3](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md)).
229
+ ([Tutorial 3](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md)). Because the
230
+ layout is chosen to stay connected, a connected map is not evidence of a continuum: whether clones form groups
231
+ is judged from the programmes, their stability and the tests, which use the profiles.
186
232
 
187
233
  ```python
188
234
  tf.tl.embed_clones(adata) # automatic (default)
@@ -201,13 +247,13 @@ tf.tl.map_quality(features, xy) # score any clone map (p
201
247
  2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
202
248
  a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
203
249
  between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
204
- context according to the number of cells (best linear unbiased prediction under a random-effects
205
- model).
206
- 3. **Clonal coherence** is the intraclass correlation of state within clones, tested against clone labels
207
- permuted within samples.
250
+ average profile of all profiled clones according to the number of cells (best linear unbiased prediction
251
+ under a random-effects model).
252
+ 3. **Clonal coherence** is the intraclass correlation of cell states (the expression embedding) within clones,
253
+ tested against clone labels permuted within sampling units (`strata_key`; by default the sampling context).
208
254
  4. **The clone embedding** is a UMAP of the clone profiles with settings chosen as above.
209
255
  5. **Clonal programmes** are graph communities of clones; each split is tested against a single Gaussian
210
- group, and each programme's stability is estimated by bootstrap resampling.
256
+ group, and each programme's stability is estimated by resampling the cells of every clone.
211
257
  6. **Clone-level tests** quantify how much of the variance between clone profiles a label explains, with
212
258
  labels permuted among the clones of each donor.
213
259
 
@@ -226,6 +272,7 @@ The full description, with references, is in [Methods](https://github.com/Reynol
226
272
  | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
227
273
  | [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
228
274
  | [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 |
275
+ | [Figure gallery](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/tutorial_path/figures/README.md) | every figure Threadfin draws, for each of the 16 public datasets of the technical validation |
229
276
 
230
277
  ## Citation
231
278
 
@@ -239,14 +286,16 @@ Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2
239
286
  Clonotrace, clone2vec, Benisse and CoNGA also combine lineage and transcriptome, and answer related but
240
287
  different questions. On the same data and clones ([benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md), with a
241
288
  one-page overview): Threadfin and Benisse represent every clone with two or more cells by default
242
- (clone2vec starts at three cells, Clonotrace at ten), and Threadfin's test of clonal coherence keeps its
243
- error rate when samples differ, where per-clone graph scores and cell-level tests do not. For recovering
289
+ (clone2vec starts at three cells, Clonotrace at ten), and Threadfin's test of clonal coherence, with clone
290
+ labels shuffled within samples, keeps its error rate when samples differ, where per-clone graph scores and
291
+ cell-level tests do not. For recovering
244
292
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
245
293
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
246
294
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
247
295
  others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
248
- times) and finished every run without help; a million cells take about an hour on 8 cores
249
- ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
296
+ times) and finished every run without help. The complete analysis of 205,630 cells takes 11 minutes on 8
297
+ cores, and with a precomputed embedding and given clone ids a million simulated cells take about an hour
298
+ ([run time and memory](https://github.com/Reynold4k/Threadfin#run-time-and-memory)).
250
299
  The benchmark reports every result, including those where Threadfin is not the best.
251
300
 
252
301
  ## Related tools
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "threadfin"
7
- version = "4.5.2"
7
+ version = "4.6.0"
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"
@@ -37,16 +37,20 @@ dependencies = [
37
37
  "igraph>=0.10",
38
38
  "leidenalg>=0.10",
39
39
  "umap-learn>=0.5.5", # older releases import pkg_resources, absent from new environments
40
- "pynndescent>=0.5.8", # likewise
40
+ # likewise; 0.7 (2026-10-27) returns sparse arrays that scanpy's neighbour search cannot read, and finds
41
+ # different approximate neighbours, so new installations would no longer reproduce the validated results
42
+ "pynndescent>=0.5.8,<0.7",
41
43
  "harmonypy>=0.0.9; platform_system != 'Windows'",
42
44
  # harmonypy 2.x ships no Windows wheels and does not compile with MSVC; 0.2 and earlier are pure Python
43
45
  "harmonypy>=0.0.9,<2; platform_system == 'Windows'",
44
46
  ]
45
47
 
46
48
  [project.optional-dependencies]
47
- # clone definition with Dandelion; sc-dandelion 0.5.7 uses matplotlib.cm.get_cmap, removed in matplotlib 3.9.
49
+ # clone definition with Dandelion; sc-dandelion 0.5.7 imports nxviz, which uses matplotlib.cm.get_cmap, removed in
50
+ # matplotlib 3.9. Up to Python 3.12 the extra keeps the validated matplotlib < 3.9; matplotlib < 3.9 has no wheels
51
+ # for Python 3.13+, where importing threadfin restores get_cmap for Dandelion (clone calls verified identical).
48
52
  # 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"]
53
+ dandelion = ["sc-dandelion>=0.5.7,<1", "matplotlib>=3.7,<3.9; python_version < '3.13'"]
50
54
  seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
51
55
  data = ["mudata>=0.3", "awkward>=2"] # reading scirpy/MuData example data
52
56
  test = ["pytest>=7", "pytest-cov>=4"]
@@ -3,7 +3,11 @@
3
3
  import importlib.util
4
4
  from pathlib import Path
5
5
 
6
+ import pytest
7
+
6
8
  DOCS = Path(__file__).resolve().parents[1] / "docs"
9
+ if not (DOCS / "make_api_reference.py").exists(): # the sdist ships the tests but not docs/
10
+ pytest.skip("docs/ is not part of this copy of Threadfin", allow_module_level=True)
7
11
 
8
12
 
9
13
  def test_api_reference_is_current():