threadfin 4.5.3__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.3/threadfin.egg-info → threadfin-4.6.0}/PKG-INFO +92 -44
  2. {threadfin-4.5.3 → threadfin-4.6.0}/README.md +90 -42
  3. {threadfin-4.5.3 → threadfin-4.6.0}/pyproject.toml +4 -3
  4. {threadfin-4.5.3 → 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.3 → threadfin-4.6.0}/tests/test_bone_marrow_design.py +2 -0
  7. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_case_study_signatures.py +2 -0
  8. {threadfin-4.5.3 → 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.3 → 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.3 → 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.3 → threadfin-4.6.0}/tests/test_user_inputs.py +2 -0
  18. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_v4_core.py +90 -0
  19. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/__init__.py +1 -1
  20. threadfin-4.6.0/threadfin/_dandelion_worker.py +225 -0
  21. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/_utils.py +33 -0
  22. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/api.py +304 -61
  23. {threadfin-4.5.3 → 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.3 → threadfin-4.6.0}/threadfin/plotting.py +27 -16
  28. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/pp.py +15 -5
  29. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/profiles.py +24 -11
  30. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/programmes.py +59 -29
  31. threadfin-4.6.0/threadfin/stats.py +761 -0
  32. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/tl.py +5 -3
  33. {threadfin-4.5.3 → threadfin-4.6.0/threadfin.egg-info}/PKG-INFO +92 -44
  34. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin.egg-info/SOURCES.txt +8 -0
  35. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin.egg-info/requires.txt +2 -0
  36. threadfin-4.5.3/threadfin/dynamics.py +0 -275
  37. threadfin-4.5.3/threadfin/export.py +0 -215
  38. threadfin-4.5.3/threadfin/heritability.py +0 -224
  39. threadfin-4.5.3/threadfin/stats.py +0 -501
  40. {threadfin-4.5.3 → threadfin-4.6.0}/LICENSE +0 -0
  41. {threadfin-4.5.3 → threadfin-4.6.0}/setup.cfg +0 -0
  42. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_bcrgraph_clones.py +0 -0
  43. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_clones_v3.py +0 -0
  44. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_dandelion_adapter.py +0 -0
  45. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_density.py +0 -0
  46. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_export.py +0 -0
  47. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_integrate.py +0 -0
  48. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_io.py +0 -0
  49. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_maptune.py +0 -0
  50. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_migration.py +0 -0
  51. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_parallel_and_robustness.py +0 -0
  52. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_phylo.py +0 -0
  53. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_profile_reproducibility.py +0 -0
  54. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_programs.py +0 -0
  55. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_reclustering_presets.py +0 -0
  56. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_sequence_v2.py +0 -0
  57. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_specificity.py +0 -0
  58. {threadfin-4.5.3 → threadfin-4.6.0}/tests/test_threadfin.py +0 -0
  59. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/bcrgraph.py +0 -0
  60. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/clones.py +0 -0
  61. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/core.py +0 -0
  62. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/density.py +0 -0
  63. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/expression.py +0 -0
  64. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/integrate.py +0 -0
  65. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/io.py +0 -0
  66. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/maptune.py +0 -0
  67. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/metrics.py +0 -0
  68. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/migration.py +0 -0
  69. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/phylo.py +0 -0
  70. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/programs.py +0 -0
  71. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/reclustering.py +0 -0
  72. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/sequence.py +0 -0
  73. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/simulate.py +0 -0
  74. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin/specificity.py +0 -0
  75. {threadfin-4.5.3 → threadfin-4.6.0}/threadfin.egg-info/dependency_links.txt +0 -0
  76. {threadfin-4.5.3 → 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.3
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
@@ -38,7 +38,7 @@ 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
@@ -78,14 +78,16 @@ distribution of its cells' transcriptional states, so that clones, not cells, ca
78
78
 
79
79
  ```bash
80
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; Python 3.10–3.12
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`,
87
- with matplotlib < 3.9 (which Dandelion 0.5 needs, and which has no packages for Python 3.13 or later). The development version
88
- 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"`.
89
91
 
90
92
  ### 2. Run
91
93
 
@@ -105,14 +107,14 @@ result = tf.run(
105
107
  donor_key="donor", # the individual each cell came from
106
108
  sample_key="sample", # the sample or library each cell came from (never a sort gate,
107
109
  # tissue or time point you want to compare: those go in test=)
108
- 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
109
111
  )
110
112
  ```
111
113
 
112
114
  `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
113
115
  receptor genes, estimates one profile per clone with two or more cells, tests clonal coherence, lays out the
114
- clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
115
- 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)).
116
118
 
117
119
  ### 3. Read the results
118
120
 
@@ -129,9 +131,9 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
129
131
 
130
132
  | What you get | Where |
131
133
  |---|---|
132
- | 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 |
133
135
  | A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
134
- | 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"]` |
135
137
  | How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
136
138
  | A Methods paragraph for your paper, with references | `result.methods()` |
137
139
 
@@ -139,16 +141,44 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
139
141
 
140
142
  * **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
141
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)).
142
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.
143
151
  * **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
144
152
  * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
145
153
  * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
146
- * **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
147
- 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.
148
160
  * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
149
161
  has clone ids and an embedding, so run it with
150
162
  `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
151
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
+
152
182
  ### Tutorials
153
183
 
154
184
  | Tutorial | What it covers |
@@ -159,10 +189,20 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
159
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` |
160
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) |
161
191
 
162
- 4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
163
- reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
164
- input, `result.methods()` and gene-level summaries of the clone landscape
165
- ([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
+
166
206
 
167
207
  ---
168
208
 
@@ -183,28 +223,29 @@ measured. Threadfin works with [AnnData](https://anndata.readthedocs.io) and
183
223
  The cells of one clone are distributed across states: germinal-centre (GC) B cells, plasmablasts, plasma
184
224
  cells and memory B cells. Two clones can have the same average state and still differ in how their cells
185
225
  are distributed. Selection, antigen affinity and fate bias act on clones, so questions such as *which
186
- clones connect the germinal centre with plasma-cell output* or *does antigen binding go with a clone's
187
- 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
188
228
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
189
229
 
190
230
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
191
231
  sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
192
232
  small.
193
233
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
194
- relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
195
- design.
196
- * **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.
197
238
 
198
239
  ## What Threadfin answers
199
240
 
200
241
  | Question | Output | Function |
201
242
  |---|---|---|
202
- | Is cell state inherited within clones? | clonal coherence: variance explained by clone, against labels shuffled within samples | `tl.clonal_coherence` |
203
- | 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` |
204
245
  | Which clones behave alike? | clonal programmes, with split tests and bootstrap stability | `tl.find_programmes` |
205
246
  | What explains the differences between clones? | variance in clone profiles explained by a label; per-programme effects | `tl.profile_association`, `tl.association_test` |
206
247
  | Do clones keep their state over time or across tissues? | the clonal memory index | `tl.clonal_memory` |
207
- | 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` |
208
249
 
209
250
  ## Examples from public data
210
251
 
@@ -214,9 +255,10 @@ further public datasets are in [case studies](https://github.com/Reynold4k/Threa
214
255
  manuscript — status, datasets, every analysis and a benchmark against related tools — is in
215
256
  [`manuscript/`](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md).
216
257
 
217
- * **Gut-associated lymphoid tissues** (Siniscalco *et al.*, *Immunity* 2025): the clone embedding resolves
218
- a continuous path of clones from GC B cells, through clones that contain both GC B cells and plasma
219
- 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).
220
262
  * **Spontaneous germinal centres** (Castrillon *et al.*, *eLife* 2023): position along the clone embedding
221
263
  orders clones by the diversity of their cell states, and memory-containing clones concentrate at one
222
264
  end.
@@ -224,20 +266,23 @@ manuscript — status, datasets, every analysis and a benchmark against related
224
266
  together with GC B cells of the same clone is a property of clones that cannot be read from the
225
267
  cell-level embedding.
226
268
  * **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
227
- between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed, so
228
- the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
229
- 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.
230
273
 
231
274
  ## A clone embedding that holds together
232
275
 
233
- 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
234
277
  settings differ between datasets. Threadfin therefore chooses them for each dataset by default: it lays
235
278
  the clones out over a ladder of settings, scores each layout for coherence (the fraction of clones in one
236
279
  connected piece) and for fidelity to the clone profiles, and keeps the most faithful setting that holds
237
280
  together in every layout it tried. A map is not allowed to be more fragmented than the clone profiles
238
281
  themselves, and the final map is checked once more before it is returned. The record of the choice is
239
282
  stored with the results, and the settings can always be fixed by hand
240
- ([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.
241
286
 
242
287
  ```python
243
288
  tf.tl.embed_clones(adata) # automatic (default)
@@ -256,13 +301,13 @@ tf.tl.map_quality(features, xy) # score any clone map (p
256
301
  2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
257
302
  a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
258
303
  between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
259
- context according to the number of cells (best linear unbiased prediction under a random-effects
260
- model).
261
- 3. **Clonal coherence** is the intraclass correlation of state within clones, tested against clone labels
262
- 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).
263
308
  4. **The clone embedding** is a UMAP of the clone profiles with settings chosen as above.
264
309
  5. **Clonal programmes** are graph communities of clones; each split is tested against a single Gaussian
265
- 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.
266
311
  6. **Clone-level tests** quantify how much of the variance between clone profiles a label explains, with
267
312
  labels permuted among the clones of each donor.
268
313
 
@@ -281,6 +326,7 @@ The full description, with references, is in [Methods](https://github.com/Reynol
281
326
  | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
282
327
  | [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
283
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 |
284
330
 
285
331
  ## Citation
286
332
 
@@ -294,14 +340,16 @@ Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2
294
340
  Clonotrace, clone2vec, Benisse and CoNGA also combine lineage and transcriptome, and answer related but
295
341
  different questions. On the same data and clones ([benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md), with a
296
342
  one-page overview): Threadfin and Benisse represent every clone with two or more cells by default
297
- (clone2vec starts at three cells, Clonotrace at ten), and Threadfin's test of clonal coherence keeps its
298
- 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
299
346
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
300
347
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
301
348
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
302
349
  others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
303
- times) and finished every run without help; a million cells take about an hour on 8 cores
304
- ([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)).
305
353
  The benchmark reports every result, including those where Threadfin is not the best.
306
354
 
307
355
  ## Related tools
@@ -24,14 +24,16 @@ distribution of its cells' transcriptional states, so that clones, not cells, ca
24
24
 
25
25
  ```bash
26
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; Python 3.10–3.12
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`,
33
- with matplotlib < 3.9 (which Dandelion 0.5 needs, and which has no packages for Python 3.13 or later). The development version
34
- 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"`.
35
37
 
36
38
  ### 2. Run
37
39
 
@@ -51,14 +53,14 @@ result = tf.run(
51
53
  donor_key="donor", # the individual each cell came from
52
54
  sample_key="sample", # the sample or library each cell came from (never a sort gate,
53
55
  # tissue or time point you want to compare: those go in test=)
54
- 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
55
57
  )
56
58
  ```
57
59
 
58
60
  `tf.run` calls clones within each donor (Dandelion, paired chains), builds an expression embedding without the
59
61
  receptor genes, estimates one profile per clone with two or more cells, tests clonal coherence, lays out the
60
- clone map and looks for clonal programmes. On the 16 public datasets tested (up to 206,000 cells) it took 1 to
61
- 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)).
62
64
 
63
65
  ### 3. Read the results
64
66
 
@@ -75,9 +77,9 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
75
77
 
76
78
  | What you get | Where |
77
79
  |---|---|
78
- | 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 |
79
81
  | A map with one point per clone | `result.plot()`; `result.clones[["x", "y"]]` |
80
- | 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"]` |
81
83
  | How much your own labels explain the differences between clones | `result.profile_tests` (with `test=[...]`) |
82
84
  | A Methods paragraph for your paper, with references | `result.methods()` |
83
85
 
@@ -85,16 +87,44 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
85
87
 
86
88
  * **Your own labels** (antigen binding, isotype, sort gate): any `adata.obs` columns, e.g.
87
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)).
88
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.
89
97
  * **T cells**: pass the TCR contigs as `bcr`; clones are called on identical beta and alpha junctions.
90
98
  * **scirpy users**: pass your scirpy AnnData or MuData as `bcr`.
91
99
  * **Clones defined elsewhere**: put them in `adata.obs["clone_id"]` and leave out `bcr`.
92
- * **Large data**: `n_jobs=-1` uses every CPU core and gives the same result; a million cells take about an hour
93
- 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.
94
106
  * **No data at hand**: `adata = tf.sim.simulate_repertoire()` makes a repertoire with a known answer; it already
95
107
  has clone ids and an embedding, so run it with
96
108
  `tf.run(adata, donor_key="donor", sample_key="context", basis="X_pca")` (tutorial 1).
97
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
+
98
128
  ### Tutorials
99
129
 
100
130
  | Tutorial | What it covers |
@@ -105,10 +135,20 @@ result.clones.to_csv("clones.csv") # per clone with >= 2 cells: size, relia
105
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` |
106
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) |
107
137
 
108
- 4.5.2 lists labels that are fixed within each donor (age, sex) as not testable instead of reporting p = 1, and
109
- reads raw counts from a layer (`counts_layer=`); 4.5.1 pins Dandelion below 1.0. New in 4.5.0: T cells, scirpy
110
- input, `result.methods()` and gene-level summaries of the clone landscape
111
- ([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
+
112
152
 
113
153
  ---
114
154
 
@@ -129,28 +169,29 @@ measured. Threadfin works with [AnnData](https://anndata.readthedocs.io) and
129
169
  The cells of one clone are distributed across states: germinal-centre (GC) B cells, plasmablasts, plasma
130
170
  cells and memory B cells. Two clones can have the same average state and still differ in how their cells
131
171
  are distributed. Selection, antigen affinity and fate bias act on clones, so questions such as *which
132
- clones connect the germinal centre with plasma-cell output* or *does antigen binding go with a clone's
133
- 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
134
174
  repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
135
175
 
136
176
  * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
137
177
  sampled, and every clone with two or more cells carries a reliability score: none is discarded for being
138
178
  small.
139
179
  * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
140
- relative to the cells sampled with it, and every permutation test shuffles labels within the sampling
141
- design.
142
- * **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.
143
184
 
144
185
  ## What Threadfin answers
145
186
 
146
187
  | Question | Output | Function |
147
188
  |---|---|---|
148
- | Is cell state inherited within clones? | clonal coherence: variance explained by clone, against labels shuffled within samples | `tl.clonal_coherence` |
149
- | 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` |
150
191
  | Which clones behave alike? | clonal programmes, with split tests and bootstrap stability | `tl.find_programmes` |
151
192
  | What explains the differences between clones? | variance in clone profiles explained by a label; per-programme effects | `tl.profile_association`, `tl.association_test` |
152
193
  | Do clones keep their state over time or across tissues? | the clonal memory index | `tl.clonal_memory` |
153
- | 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` |
154
195
 
155
196
  ## Examples from public data
156
197
 
@@ -160,9 +201,10 @@ further public datasets are in [case studies](https://github.com/Reynold4k/Threa
160
201
  manuscript — status, datasets, every analysis and a benchmark against related tools — is in
161
202
  [`manuscript/`](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md).
162
203
 
163
- * **Gut-associated lymphoid tissues** (Siniscalco *et al.*, *Immunity* 2025): the clone embedding resolves
164
- a continuous path of clones from GC B cells, through clones that contain both GC B cells and plasma
165
- 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).
166
208
  * **Spontaneous germinal centres** (Castrillon *et al.*, *eLife* 2023): position along the clone embedding
167
209
  orders clones by the diversity of their cell states, and memory-containing clones concentrate at one
168
210
  end.
@@ -170,20 +212,23 @@ manuscript — status, datasets, every analysis and a benchmark against related
170
212
  together with GC B cells of the same clone is a property of clones that cannot be read from the
171
213
  cell-level embedding.
172
214
  * **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
173
- between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed, so
174
- the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
175
- 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.
176
219
 
177
220
  ## A clone embedding that holds together
178
221
 
179
- 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
180
223
  settings differ between datasets. Threadfin therefore chooses them for each dataset by default: it lays
181
224
  the clones out over a ladder of settings, scores each layout for coherence (the fraction of clones in one
182
225
  connected piece) and for fidelity to the clone profiles, and keeps the most faithful setting that holds
183
226
  together in every layout it tried. A map is not allowed to be more fragmented than the clone profiles
184
227
  themselves, and the final map is checked once more before it is returned. The record of the choice is
185
228
  stored with the results, and the settings can always be fixed by hand
186
- ([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.
187
232
 
188
233
  ```python
189
234
  tf.tl.embed_clones(adata) # automatic (default)
@@ -202,13 +247,13 @@ tf.tl.map_quality(features, xy) # score any clone map (p
202
247
  2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
203
248
  a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
204
249
  between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
205
- context according to the number of cells (best linear unbiased prediction under a random-effects
206
- model).
207
- 3. **Clonal coherence** is the intraclass correlation of state within clones, tested against clone labels
208
- 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).
209
254
  4. **The clone embedding** is a UMAP of the clone profiles with settings chosen as above.
210
255
  5. **Clonal programmes** are graph communities of clones; each split is tested against a single Gaussian
211
- 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.
212
257
  6. **Clone-level tests** quantify how much of the variance between clone profiles a label explains, with
213
258
  labels permuted among the clones of each donor.
214
259
 
@@ -227,6 +272,7 @@ The full description, with references, is in [Methods](https://github.com/Reynol
227
272
  | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
228
273
  | [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
229
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 |
230
276
 
231
277
  ## Citation
232
278
 
@@ -240,14 +286,16 @@ Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2
240
286
  Clonotrace, clone2vec, Benisse and CoNGA also combine lineage and transcriptome, and answer related but
241
287
  different questions. On the same data and clones ([benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md), with a
242
288
  one-page overview): Threadfin and Benisse represent every clone with two or more cells by default
243
- (clone2vec starts at three cells, Clonotrace at ten), and Threadfin's test of clonal coherence keeps its
244
- 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
245
292
  measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
246
293
  coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
247
294
  planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
248
295
  others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 290 to 2,400
249
- times) and finished every run without help; a million cells take about an hour on 8 cores
250
- ([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)).
251
299
  The benchmark reports every result, including those where Threadfin is not the best.
252
300
 
253
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.3"
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"
@@ -47,9 +47,10 @@ dependencies = [
47
47
 
48
48
  [project.optional-dependencies]
49
49
  # clone definition with Dandelion; sc-dandelion 0.5.7 imports nxviz, which uses matplotlib.cm.get_cmap, removed in
50
- # matplotlib 3.9. matplotlib < 3.9 has wheels only for Python <= 3.12, so the extra needs Python 3.10-3.12.
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).
51
52
  # sc-dandelion 1.0 (2026-10-25) calls clones differently and is not yet validated, hence < 1.
52
- 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'"]
53
54
  seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
54
55
  data = ["mudata>=0.3", "awkward>=2"] # reading scirpy/MuData example data
55
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():