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.
- {threadfin-4.5.2/threadfin.egg-info → threadfin-4.6.0}/PKG-INFO +92 -43
- {threadfin-4.5.2 → threadfin-4.6.0}/README.md +89 -40
- {threadfin-4.5.2 → threadfin-4.6.0}/pyproject.toml +8 -4
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_api_reference.py +4 -0
- threadfin-4.6.0/tests/test_association_strata.py +299 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_bone_marrow_design.py +2 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_case_study_signatures.py +2 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_clone_state_sharing.py +5 -1
- threadfin-4.6.0/tests/test_dandelion_seed.py +254 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_ebv_contig_matching.py +5 -1
- threadfin-4.6.0/tests/test_geneset_and_export.py +315 -0
- threadfin-4.6.0/tests/test_memory_reference.py +337 -0
- threadfin-4.6.0/tests/test_read_paths.py +163 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_release_metadata.py +4 -0
- threadfin-4.6.0/tests/test_result_plots.py +104 -0
- threadfin-4.6.0/tests/test_statistical_properties.py +581 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_user_inputs.py +2 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_v4_core.py +90 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/__init__.py +1 -1
- threadfin-4.6.0/threadfin/_dandelion_worker.py +225 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/_utils.py +33 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/api.py +304 -61
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/dandelion.py +226 -75
- threadfin-4.6.0/threadfin/dynamics.py +503 -0
- threadfin-4.6.0/threadfin/export.py +403 -0
- threadfin-4.6.0/threadfin/heritability.py +518 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/plotting.py +27 -16
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/pp.py +15 -5
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/profiles.py +24 -11
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/programmes.py +59 -29
- threadfin-4.6.0/threadfin/stats.py +761 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/tl.py +5 -3
- {threadfin-4.5.2 → threadfin-4.6.0/threadfin.egg-info}/PKG-INFO +92 -43
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin.egg-info/SOURCES.txt +8 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin.egg-info/requires.txt +3 -1
- threadfin-4.5.2/threadfin/dynamics.py +0 -275
- threadfin-4.5.2/threadfin/export.py +0 -215
- threadfin-4.5.2/threadfin/heritability.py +0 -224
- threadfin-4.5.2/threadfin/stats.py +0 -501
- {threadfin-4.5.2 → threadfin-4.6.0}/LICENSE +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/setup.cfg +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_bcrgraph_clones.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_clones_v3.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_dandelion_adapter.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_density.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_export.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_integrate.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_io.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_maptune.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_migration.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_parallel_and_robustness.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_phylo.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_profile_reproducibility.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_programs.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_reclustering_presets.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_sequence_v2.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_specificity.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/tests/test_threadfin.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/bcrgraph.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/clones.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/core.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/density.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/expression.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/integrate.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/io.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/maptune.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/metrics.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/migration.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/phylo.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/programs.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/reclustering.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/sequence.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/simulate.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin/specificity.py +0 -0
- {threadfin-4.5.2 → threadfin-4.6.0}/threadfin.egg-info/dependency_links.txt +0 -0
- {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.
|
|
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
|
|
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
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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, #
|
|
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 (
|
|
114
|
-
|
|
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
|
-
|
|
|
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
|
|
146
|
-
|
|
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.
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
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
|
|
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
|
|
194
|
-
design.
|
|
195
|
-
* **Treating cells as independent inflates significance.**
|
|
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
|
-
|
|
|
202
|
-
| How are 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
|
|
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
|
|
217
|
-
|
|
218
|
-
|
|
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
|
|
227
|
-
|
|
228
|
-
|
|
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
|
|
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
|
-
|
|
259
|
-
model).
|
|
260
|
-
3. **Clonal coherence** is the intraclass correlation of
|
|
261
|
-
permuted within
|
|
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
|
|
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
|
|
297
|
-
error rate when samples differ, where per-clone graph scores and
|
|
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
|
|
303
|
-
|
|
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
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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, #
|
|
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 (
|
|
60
|
-
|
|
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
|
-
|
|
|
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
|
|
92
|
-
|
|
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.
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
|
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
|
|
140
|
-
design.
|
|
141
|
-
* **Treating cells as independent inflates significance.**
|
|
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
|
-
|
|
|
148
|
-
| How are 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
|
|
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
|
|
163
|
-
|
|
164
|
-
|
|
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
|
|
173
|
-
|
|
174
|
-
|
|
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
|
|
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
|
-
|
|
205
|
-
model).
|
|
206
|
-
3. **Clonal coherence** is the intraclass correlation of
|
|
207
|
-
permuted within
|
|
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
|
|
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
|
|
243
|
-
error rate when samples differ, where per-clone graph scores and
|
|
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
|
|
249
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
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():
|