threadfin 4.5.3__tar.gz → 4.6.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {threadfin-4.5.3/threadfin.egg-info → threadfin-4.6.1}/PKG-INFO +92 -44
- {threadfin-4.5.3 → threadfin-4.6.1}/README.md +90 -42
- {threadfin-4.5.3 → threadfin-4.6.1}/pyproject.toml +4 -3
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_api_reference.py +4 -0
- threadfin-4.6.1/tests/test_association_strata.py +299 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_bone_marrow_design.py +2 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_case_study_signatures.py +2 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_clone_state_sharing.py +5 -1
- threadfin-4.6.1/tests/test_dandelion_seed.py +254 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_ebv_contig_matching.py +5 -1
- threadfin-4.6.1/tests/test_geneset_and_export.py +315 -0
- threadfin-4.6.1/tests/test_memory_reference.py +337 -0
- threadfin-4.6.1/tests/test_read_paths.py +163 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_release_metadata.py +4 -0
- threadfin-4.6.1/tests/test_result_plots.py +104 -0
- threadfin-4.6.1/tests/test_statistical_properties.py +581 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_user_inputs.py +2 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_v4_core.py +90 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/__init__.py +1 -1
- threadfin-4.6.1/threadfin/_dandelion_worker.py +225 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/_utils.py +33 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/api.py +304 -61
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/dandelion.py +226 -75
- threadfin-4.6.1/threadfin/dynamics.py +503 -0
- threadfin-4.6.1/threadfin/export.py +403 -0
- threadfin-4.6.1/threadfin/heritability.py +518 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/plotting.py +27 -16
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/pp.py +15 -5
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/profiles.py +24 -11
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/programmes.py +59 -29
- threadfin-4.6.1/threadfin/stats.py +761 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/tl.py +5 -3
- {threadfin-4.5.3 → threadfin-4.6.1/threadfin.egg-info}/PKG-INFO +92 -44
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin.egg-info/SOURCES.txt +8 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin.egg-info/requires.txt +2 -0
- threadfin-4.5.3/threadfin/dynamics.py +0 -275
- threadfin-4.5.3/threadfin/export.py +0 -215
- threadfin-4.5.3/threadfin/heritability.py +0 -224
- threadfin-4.5.3/threadfin/stats.py +0 -501
- {threadfin-4.5.3 → threadfin-4.6.1}/LICENSE +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/setup.cfg +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_bcrgraph_clones.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_clones_v3.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_dandelion_adapter.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_density.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_export.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_integrate.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_io.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_maptune.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_migration.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_parallel_and_robustness.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_phylo.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_profile_reproducibility.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_programs.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_reclustering_presets.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_sequence_v2.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_specificity.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/tests/test_threadfin.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/bcrgraph.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/clones.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/core.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/density.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/expression.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/integrate.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/io.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/maptune.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/metrics.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/migration.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/phylo.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/programs.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/reclustering.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/sequence.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/simulate.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin/specificity.py +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin.egg-info/dependency_links.txt +0 -0
- {threadfin-4.5.3 → threadfin-4.6.1}/threadfin.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: threadfin
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.6.1
|
|
4
4
|
Summary: Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory
|
|
5
5
|
Author-email: Chen Satoshi <103236530+Reynold4k@users.noreply.github.com>
|
|
6
6
|
License: MIT
|
|
@@ -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
|
|
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
|
-
|
|
88
|
-
|
|
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, #
|
|
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 (
|
|
115
|
-
|
|
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
|
-
|
|
|
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
|
|
147
|
-
|
|
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.
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
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
|
|
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
|
|
195
|
-
design.
|
|
196
|
-
* **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.
|
|
197
238
|
|
|
198
239
|
## What Threadfin answers
|
|
199
240
|
|
|
200
241
|
| Question | Output | Function |
|
|
201
242
|
|---|---|---|
|
|
202
|
-
|
|
|
203
|
-
| 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` |
|
|
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
|
|
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
|
|
218
|
-
|
|
219
|
-
|
|
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
|
|
228
|
-
|
|
229
|
-
|
|
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
|
|
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
|
-
|
|
260
|
-
model).
|
|
261
|
-
3. **Clonal coherence** is the intraclass correlation of
|
|
262
|
-
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).
|
|
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
|
|
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
|
|
298
|
-
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
|
|
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
|
|
304
|
-
|
|
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
|
|
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
|
-
|
|
34
|
-
|
|
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, #
|
|
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 (
|
|
61
|
-
|
|
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
|
-
|
|
|
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
|
|
93
|
-
|
|
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.
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
|
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
|
|
141
|
-
design.
|
|
142
|
-
* **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.
|
|
143
184
|
|
|
144
185
|
## What Threadfin answers
|
|
145
186
|
|
|
146
187
|
| Question | Output | Function |
|
|
147
188
|
|---|---|---|
|
|
148
|
-
|
|
|
149
|
-
| 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` |
|
|
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
|
|
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
|
|
164
|
-
|
|
165
|
-
|
|
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
|
|
174
|
-
|
|
175
|
-
|
|
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
|
|
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
|
-
|
|
206
|
-
model).
|
|
207
|
-
3. **Clonal coherence** is the intraclass correlation of
|
|
208
|
-
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).
|
|
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
|
|
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
|
|
244
|
-
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
|
|
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
|
|
250
|
-
|
|
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.
|
|
7
|
+
version = "4.6.1"
|
|
8
8
|
description = "Relationships between B-cell clones from paired single-cell RNA and BCR sequencing: clone embeddings, clonal coherence, clonal programmes, clone-level tests and clonal memory"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.10"
|
|
@@ -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.
|
|
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():
|