threadfin 4.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. threadfin-4.5.0/LICENSE +21 -0
  2. threadfin-4.5.0/PKG-INFO +288 -0
  3. threadfin-4.5.0/README.md +234 -0
  4. threadfin-4.5.0/pyproject.toml +73 -0
  5. threadfin-4.5.0/setup.cfg +4 -0
  6. threadfin-4.5.0/tests/test_api_reference.py +13 -0
  7. threadfin-4.5.0/tests/test_bcrgraph_clones.py +252 -0
  8. threadfin-4.5.0/tests/test_bone_marrow_design.py +39 -0
  9. threadfin-4.5.0/tests/test_case_study_signatures.py +85 -0
  10. threadfin-4.5.0/tests/test_clone_state_sharing.py +140 -0
  11. threadfin-4.5.0/tests/test_clones_v3.py +167 -0
  12. threadfin-4.5.0/tests/test_dandelion_adapter.py +281 -0
  13. threadfin-4.5.0/tests/test_density.py +194 -0
  14. threadfin-4.5.0/tests/test_ebv_contig_matching.py +27 -0
  15. threadfin-4.5.0/tests/test_export.py +92 -0
  16. threadfin-4.5.0/tests/test_integrate.py +223 -0
  17. threadfin-4.5.0/tests/test_io.py +297 -0
  18. threadfin-4.5.0/tests/test_maptune.py +132 -0
  19. threadfin-4.5.0/tests/test_migration.py +141 -0
  20. threadfin-4.5.0/tests/test_parallel_and_robustness.py +103 -0
  21. threadfin-4.5.0/tests/test_phylo.py +136 -0
  22. threadfin-4.5.0/tests/test_profile_reproducibility.py +141 -0
  23. threadfin-4.5.0/tests/test_programs.py +104 -0
  24. threadfin-4.5.0/tests/test_reclustering_presets.py +130 -0
  25. threadfin-4.5.0/tests/test_release_metadata.py +15 -0
  26. threadfin-4.5.0/tests/test_sequence_v2.py +146 -0
  27. threadfin-4.5.0/tests/test_specificity.py +221 -0
  28. threadfin-4.5.0/tests/test_threadfin.py +169 -0
  29. threadfin-4.5.0/tests/test_user_inputs.py +119 -0
  30. threadfin-4.5.0/tests/test_v4_core.py +417 -0
  31. threadfin-4.5.0/threadfin/__init__.py +86 -0
  32. threadfin-4.5.0/threadfin/_utils.py +260 -0
  33. threadfin-4.5.0/threadfin/api.py +658 -0
  34. threadfin-4.5.0/threadfin/bcrgraph.py +255 -0
  35. threadfin-4.5.0/threadfin/clones.py +653 -0
  36. threadfin-4.5.0/threadfin/core.py +531 -0
  37. threadfin-4.5.0/threadfin/dandelion.py +458 -0
  38. threadfin-4.5.0/threadfin/density.py +409 -0
  39. threadfin-4.5.0/threadfin/dynamics.py +275 -0
  40. threadfin-4.5.0/threadfin/export.py +215 -0
  41. threadfin-4.5.0/threadfin/expression.py +121 -0
  42. threadfin-4.5.0/threadfin/heritability.py +224 -0
  43. threadfin-4.5.0/threadfin/integrate.py +350 -0
  44. threadfin-4.5.0/threadfin/io.py +280 -0
  45. threadfin-4.5.0/threadfin/maptune.py +743 -0
  46. threadfin-4.5.0/threadfin/metrics.py +137 -0
  47. threadfin-4.5.0/threadfin/migration.py +165 -0
  48. threadfin-4.5.0/threadfin/phylo.py +834 -0
  49. threadfin-4.5.0/threadfin/plotting.py +535 -0
  50. threadfin-4.5.0/threadfin/pp.py +253 -0
  51. threadfin-4.5.0/threadfin/profiles.py +603 -0
  52. threadfin-4.5.0/threadfin/programmes.py +1028 -0
  53. threadfin-4.5.0/threadfin/programs.py +133 -0
  54. threadfin-4.5.0/threadfin/reclustering.py +68 -0
  55. threadfin-4.5.0/threadfin/sequence.py +379 -0
  56. threadfin-4.5.0/threadfin/simulate.py +206 -0
  57. threadfin-4.5.0/threadfin/specificity.py +355 -0
  58. threadfin-4.5.0/threadfin/stats.py +476 -0
  59. threadfin-4.5.0/threadfin/tl.py +62 -0
  60. threadfin-4.5.0/threadfin.egg-info/PKG-INFO +288 -0
  61. threadfin-4.5.0/threadfin.egg-info/SOURCES.txt +62 -0
  62. threadfin-4.5.0/threadfin.egg-info/dependency_links.txt +1 -0
  63. threadfin-4.5.0/threadfin.egg-info/requires.txt +37 -0
  64. threadfin-4.5.0/threadfin.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Chen Satoshi (Reynold4k)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,288 @@
1
+ Metadata-Version: 2.4
2
+ Name: threadfin
3
+ Version: 4.5.0
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
+ Author-email: Chen Satoshi <103236530+Reynold4k@users.noreply.github.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Reynold4k/Threadfin
8
+ Project-URL: Repository, https://github.com/Reynold4k/Threadfin
9
+ Project-URL: Issues, https://github.com/Reynold4k/Threadfin/issues
10
+ Project-URL: Documentation, https://github.com/Reynold4k/Threadfin/blob/main/docs/README.md
11
+ Project-URL: Changelog, https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md
12
+ Keywords: single-cell,scRNA-seq,BCR,VDJ,B cell,clone,clonal lineage,germinal center,immunology,repertoire
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
22
+ Requires-Python: >=3.10
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: anndata>=0.10
26
+ Requires-Dist: numpy>=1.24
27
+ Requires-Dist: pandas>=2.0
28
+ Requires-Dist: scipy>=1.10
29
+ Requires-Dist: scikit-learn>=1.3
30
+ Requires-Dist: joblib>=1.2
31
+ Requires-Dist: scanpy>=1.10
32
+ Requires-Dist: matplotlib>=3.7
33
+ Requires-Dist: igraph>=0.10
34
+ Requires-Dist: leidenalg>=0.10
35
+ Requires-Dist: umap-learn>=0.5.5
36
+ Requires-Dist: pynndescent>=0.5.8
37
+ Requires-Dist: harmonypy>=0.0.9; platform_system != "Windows"
38
+ Requires-Dist: harmonypy<2,>=0.0.9; platform_system == "Windows"
39
+ Provides-Extra: dandelion
40
+ Requires-Dist: sc-dandelion>=0.5.7; extra == "dandelion"
41
+ Requires-Dist: matplotlib<3.9,>=3.7; extra == "dandelion"
42
+ Provides-Extra: seq
43
+ Requires-Dist: parasail>=1.3; extra == "seq"
44
+ Provides-Extra: data
45
+ Requires-Dist: mudata>=0.3; extra == "data"
46
+ Requires-Dist: awkward>=2; extra == "data"
47
+ Provides-Extra: test
48
+ Requires-Dist: pytest>=7; extra == "test"
49
+ Requires-Dist: pytest-cov>=4; extra == "test"
50
+ Provides-Extra: benchmark
51
+ Requires-Dist: clone2vec>=0.1; extra == "benchmark"
52
+ Requires-Dist: psutil>=5; extra == "benchmark"
53
+ Dynamic: license-file
54
+
55
+ <p align="center">
56
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_overview.png" width="720" alt="Threadfin turns paired single-cell RNA and BCR sequencing into a clone embedding, one point per clone">
57
+ </p>
58
+
59
+ <h1 align="center">Threadfin</h1>
60
+
61
+ <p align="center">
62
+ <b>Relationships between B-cell clones from paired single-cell RNA and receptor sequencing</b>
63
+ </p>
64
+
65
+ <p align="center">
66
+ <a href="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml"><img src="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
67
+ <a href="https://www.python.org"><img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue.svg" alt="Python 3.10 to 3.14"></a>
68
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-4.3.1-informational.svg" alt="version 4.3.1"></a>
69
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
70
+ </p>
71
+
72
+ **Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
73
+ uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
74
+ Each clone is represented by the distribution of transcriptional states among its sampled cells,
75
+ estimated relative to the cells sampled alongside it and shrunk according to the number of cells
76
+ captured. Clones are then compared with one another: in a **clone embedding** with one point per clone,
77
+ in **clonal programmes** of clones that behave alike, and in **clone-level tests** of anything you
78
+ measured. Threadfin works with [AnnData](https://anndata.readthedocs.io) and
79
+ [Scanpy](https://scanpy.readthedocs.io), and defines clones with
80
+ [Dandelion](https://github.com/zktuong/dandelion).
81
+
82
+ ## Why clones?
83
+
84
+ The cells of one clone are distributed across states: germinal-centre (GC) B cells, plasmablasts, plasma
85
+ cells and memory B cells. Two clones can have the same average state and still differ in how their cells
86
+ are distributed. Selection, antigen affinity and fate bias act on clones, so questions such as *which
87
+ clones connect the germinal centre with plasma-cell output* or *does antigen binding go with a clone's
88
+ state* need the clone as the unit of representation and of statistical inference. Three features of
89
+ repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
90
+
91
+ * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
92
+ sampled, and each clone carries a reliability score. No clone is discarded for being small.
93
+ * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
94
+ relative to the cells sampled with it, and every test shuffles labels within the sampling design.
95
+ * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
96
+
97
+ ## What Threadfin answers
98
+
99
+ | Question | Output | Function |
100
+ |---|---|---|
101
+ | Is cell state inherited within clones? | clonal coherence: variance explained by clone, against labels shuffled within samples | `tl.clonal_coherence` |
102
+ | How are clones related to one another? | the clone embedding, laid out automatically so that continua stay connected | `tl.embed_clones` |
103
+ | Which clones behave alike? | clonal programmes, with split tests and bootstrap stability | `tl.find_programmes` |
104
+ | What explains the differences between clones? | variance in clone profiles explained by a label; per-programme effects | `tl.profile_association`, `tl.association_test` |
105
+ | Do clones keep their state over time or across tissues? | the clonal memory index | `tl.clonal_memory` |
106
+ | How far behind its germinal centre is a clone's output? | the export lag, in somatic mutations and in days | `tl.export_lag` |
107
+
108
+ ## Examples from public data
109
+
110
+ The manuscript applies Threadfin to nine paired datasets from immunization, infection, vaccination and
111
+ spontaneous germinal centres ([figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md)); scripts and results for these and
112
+ further public datasets are in [case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md), and everything behind the
113
+ manuscript — status, datasets, every analysis and a benchmark against related tools — is in
114
+ [`manuscript/`](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md).
115
+
116
+ * **Gut-associated lymphoid tissues** (Siniscalco *et al.*, *Immunity* 2025): the clone embedding resolves
117
+ a continuous path of clones from GC B cells, through clones that contain both GC B cells and plasma
118
+ cells, to plasma-cell clones, with clones that lack GC-fate labelling grouped at its end.
119
+ * **Spontaneous germinal centres** (Castrillon *et al.*, *eLife* 2023): position along the clone embedding
120
+ orders clones by the diversity of their cell states, and memory-containing clones concentrate at one
121
+ end.
122
+ * ***Plasmodium* infection** (Skinner *et al.*, *Nat. Immunol.* 2026): whether plasmablasts were sampled
123
+ together with GC B cells of the same clone is a property of clones that cannot be read from the
124
+ cell-level embedding.
125
+ * **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
126
+ between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed, so
127
+ the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
128
+ clone profiles but were each sequenced in their own library.
129
+
130
+ ## Installation
131
+
132
+ ```bash
133
+ pip install "git+https://github.com/Reynold4k/Threadfin.git"
134
+ # with Dandelion, to define clones from BCR contigs:
135
+ pip install "threadfin[dandelion] @ git+https://github.com/Reynold4k/Threadfin.git"
136
+ ```
137
+
138
+ Threadfin requires Python ≥ 3.10 and is tested on 3.10 to 3.14, down to the oldest dependency versions it
139
+ allows ([compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md)); Scanpy, Leiden, UMAP and Harmony are installed with it, and no
140
+ GPU or R is needed. Clones can be defined from BCR contigs with Dandelion (the `[dandelion]` extra also pins
141
+ `matplotlib<3.9`, which Dandelion 0.5.7 needs but does not declare), or you can provide your own clone ids
142
+ in `adata.obs["clone_id"]`. Dandelion's clone calls depend on Python's string-hash seed; start Python with
143
+ `PYTHONHASHSEED=0` if clone ids must be identical run after run.
144
+
145
+ ## Quick start
146
+
147
+ ```python
148
+ import scanpy as sc
149
+ import threadfin as tf
150
+
151
+ adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
152
+
153
+ result = tf.run(
154
+ adata,
155
+ bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
156
+ donor_key="donor", # the individual each cell came from
157
+ sample_key="sample", # the sample or library each cell came from
158
+ )
159
+ print(result.summary()) # plain-language report
160
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
161
+ print(result.methods()) # a Methods paragraph with the settings used
162
+ ```
163
+
164
+ `tf.run` defines clones within each donor, builds an expression embedding without immunoglobulin genes,
165
+ estimates one profile per clone, tests clonal coherence, lays out the clone embedding, finds clonal
166
+ programmes and reports their stability. Add `test=[...]` to test your own labels and `time_key=` to ask
167
+ whether clones keep their state, and `n_jobs=-1` to use every CPU core (the results do not change). No data
168
+ at hand? `tf.sim.simulate_repertoire()` makes a repertoire with a known answer
169
+ ([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)).
170
+ T cells work the same way, with TCR contigs as `bcr`, and receptor data loaded with scirpy can be passed as
171
+ they are ([Tutorial 2, section 6](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md#6-how-clones-are-called)).
172
+
173
+ <p align="center">
174
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
175
+ </p>
176
+
177
+ ## A complete, tested tutorial on public data
178
+
179
+ [`docs/tutorials/05_end_to_end_tutorial.ipynb`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) takes you from an
180
+ empty folder to the main result of the manuscript's Figure 4: it creates the environment
181
+ ([`environment.yml`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/environment.yml)), downloads a published dataset from GEO (GSE287123,
182
+ about 600 MB), assigns cells to mice from hashtags, defines clones, builds the embedding, runs Threadfin and
183
+ explains every output, including how to tell biology from a sequencing-library effect. It was executed end
184
+ to end in a fresh environment before release and takes about 6 minutes on 8 CPU cores (about 8 GB of memory).
185
+
186
+ ## A clone embedding that holds together
187
+
188
+ UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
189
+ settings differ between datasets. Threadfin therefore chooses them for each dataset by default: it lays
190
+ the clones out over a ladder of settings, scores each layout for coherence (the fraction of clones in one
191
+ connected piece) and for fidelity to the clone profiles, and keeps the most faithful setting that holds
192
+ together in every layout it tried. A map is not allowed to be more fragmented than the clone profiles
193
+ themselves, and the final map is checked once more before it is returned. The record of the choice is
194
+ stored with the results, and the settings can always be fixed by hand
195
+ ([Tutorial 3](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md)).
196
+
197
+ ```python
198
+ tf.tl.embed_clones(adata) # automatic (default)
199
+ tf.tl.embed_clones(adata, n_neighbors=30, min_dist=0.3) # by hand
200
+ tf.tl.map_quality(features, xy) # score any clone map (profiles, coordinates)
201
+ ```
202
+
203
+ ## How it works
204
+
205
+ <p align="center">
206
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
207
+ </p>
208
+
209
+ 1. **Clones** are defined from paired heavy- and light-chain sequences within each donor (Dandelion).
210
+ 2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
211
+ a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
212
+ between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
213
+ context according to the number of cells (best linear unbiased prediction under a random-effects
214
+ model).
215
+ 3. **Clonal coherence** is the intraclass correlation of state within clones, tested against clone labels
216
+ permuted within samples.
217
+ 4. **The clone embedding** is a UMAP of the clone profiles with settings chosen as above.
218
+ 5. **Clonal programmes** are graph communities of clones; each split is tested against a single Gaussian
219
+ group, and each programme's stability is estimated by bootstrap resampling.
220
+ 6. **Clone-level tests** quantify how much of the variance between clone profiles a label explains, with
221
+ labels permuted among the clones of each donor.
222
+
223
+ The full description, with references, is in [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md).
224
+
225
+ ## Documentation
226
+
227
+ | | |
228
+ |---|---|
229
+ | [Tutorial 1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data, with its output |
230
+ | [Tutorial 2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results, with several samples and donors |
231
+ | [Tutorial 3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
232
+ | [Tutorial 4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
233
+ | [Tutorial 5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset end to end: download, demultiplexing, clones, embedding, Threadfin, interpretation |
234
+ | [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
235
+ | [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
236
+ | [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
237
+ | [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
238
+ | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
239
+ | [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
240
+ | [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
241
+
242
+ ## Citation
243
+
244
+ A manuscript describing Threadfin is in preparation. Until it is available, please cite this repository
245
+ ([CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff)) and the tools Threadfin builds on: Dandelion (Suo *et al.*, *Nat.
246
+ Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2018) and UMAP (McInnes
247
+ *et al.*, *J. Open Source Softw.* 2018).
248
+
249
+ ## How Threadfin compares with related tools
250
+
251
+ Clonotrace, clone2vec, Benisse and CoNGA also combine lineage and transcriptome, and answer related but
252
+ different questions. On the same data and clones ([benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md), with a
253
+ one-page overview): Threadfin and Benisse represent every clone with two or more cells by default
254
+ (clone2vec starts at three cells, Clonotrace at ten), and Threadfin's test of clonal coherence keeps its
255
+ error rate when samples differ, where per-clone graph scores and cell-level tests do not. For recovering
256
+ measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
257
+ coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
258
+ planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
259
+ others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 300 to 2,400
260
+ times) and finished every run without help; a million cells take about an hour on 8 cores
261
+ ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
262
+ The benchmark reports every result, including those where Threadfin is not the best.
263
+
264
+ ## Related tools
265
+
266
+ * [Dandelion](https://github.com/zktuong/dandelion) — single-cell immune receptor analysis; Threadfin's
267
+ clone definition.
268
+ * [Clonotrace](https://github.com/yuntianf/Clonotrace) — distances between expanded clones on the cell-state
269
+ graph after label spreading.
270
+ * [clone2vec](https://github.com/kharchenkolab/clone2vec) — clone embeddings learned from which clones'
271
+ cells are neighbours.
272
+ * [Benisse](https://github.com/wooyongc/Benisse) — a joint space of BCR sequences and expression.
273
+ * [CoNGA](https://github.com/phbradley/conga) — graph-vs-graph analysis of T-cell receptor and expression
274
+ similarity.
275
+ * [Scirpy](https://github.com/scverse/scirpy) — single-cell immune receptor analysis in the scverse
276
+ ecosystem; Threadfin reads its AnnData and MuData objects.
277
+ * [Scanpy](https://github.com/scverse/scanpy) and [AnnData](https://github.com/scverse/anndata) — the data
278
+ structures and single-cell tools Threadfin works with.
279
+ * [Immcantation](https://immcantation.readthedocs.io) — B-cell receptor repertoire analysis, including
280
+ clonal lineage reconstruction.
281
+
282
+ ## Support
283
+
284
+ Please report bugs and ask questions through [GitHub issues](https://github.com/Reynold4k/Threadfin/issues).
285
+
286
+ ## License
287
+
288
+ MIT; see [LICENSE](https://github.com/Reynold4k/Threadfin/blob/main/LICENSE).
@@ -0,0 +1,234 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_overview.png" width="720" alt="Threadfin turns paired single-cell RNA and BCR sequencing into a clone embedding, one point per clone">
3
+ </p>
4
+
5
+ <h1 align="center">Threadfin</h1>
6
+
7
+ <p align="center">
8
+ <b>Relationships between B-cell clones from paired single-cell RNA and receptor sequencing</b>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml"><img src="https://github.com/Reynold4k/Threadfin/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
13
+ <a href="https://www.python.org"><img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue.svg" alt="Python 3.10 to 3.14"></a>
14
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-4.3.1-informational.svg" alt="version 4.3.1"></a>
15
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT licence"></a>
16
+ </p>
17
+
18
+ **Threadfin** is a Python package for paired single-cell RNA and B-cell receptor (BCR) sequencing. It
19
+ uses the **clone** — the B cells that descend from one V(D)J rearrangement — as the unit of analysis.
20
+ Each clone is represented by the distribution of transcriptional states among its sampled cells,
21
+ estimated relative to the cells sampled alongside it and shrunk according to the number of cells
22
+ captured. Clones are then compared with one another: in a **clone embedding** with one point per clone,
23
+ in **clonal programmes** of clones that behave alike, and in **clone-level tests** of anything you
24
+ measured. Threadfin works with [AnnData](https://anndata.readthedocs.io) and
25
+ [Scanpy](https://scanpy.readthedocs.io), and defines clones with
26
+ [Dandelion](https://github.com/zktuong/dandelion).
27
+
28
+ ## Why clones?
29
+
30
+ The cells of one clone are distributed across states: germinal-centre (GC) B cells, plasmablasts, plasma
31
+ cells and memory B cells. Two clones can have the same average state and still differ in how their cells
32
+ are distributed. Selection, antigen affinity and fate bias act on clones, so questions such as *which
33
+ clones connect the germinal centre with plasma-cell output* or *does antigen binding go with a clone's
34
+ state* need the clone as the unit of representation and of statistical inference. Three features of
35
+ repertoires sampled *in vivo* make this difficult, and Threadfin addresses each:
36
+
37
+ * **Most clones are captured as one or a few cells.** Profiles are shrunk according to the number of cells
38
+ sampled, and each clone carries a reliability score. No clone is discarded for being small.
39
+ * **Clone membership is confounded with donor, sample, tissue and sorting gate.** Each clone is described
40
+ relative to the cells sampled with it, and every test shuffles labels within the sampling design.
41
+ * **Treating cells as independent inflates significance.** Tests use clones, not cells, as replicates.
42
+
43
+ ## What Threadfin answers
44
+
45
+ | Question | Output | Function |
46
+ |---|---|---|
47
+ | Is cell state inherited within clones? | clonal coherence: variance explained by clone, against labels shuffled within samples | `tl.clonal_coherence` |
48
+ | How are clones related to one another? | the clone embedding, laid out automatically so that continua stay connected | `tl.embed_clones` |
49
+ | Which clones behave alike? | clonal programmes, with split tests and bootstrap stability | `tl.find_programmes` |
50
+ | What explains the differences between clones? | variance in clone profiles explained by a label; per-programme effects | `tl.profile_association`, `tl.association_test` |
51
+ | Do clones keep their state over time or across tissues? | the clonal memory index | `tl.clonal_memory` |
52
+ | How far behind its germinal centre is a clone's output? | the export lag, in somatic mutations and in days | `tl.export_lag` |
53
+
54
+ ## Examples from public data
55
+
56
+ The manuscript applies Threadfin to nine paired datasets from immunization, infection, vaccination and
57
+ spontaneous germinal centres ([figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md)); scripts and results for these and
58
+ further public datasets are in [case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md), and everything behind the
59
+ manuscript — status, datasets, every analysis and a benchmark against related tools — is in
60
+ [`manuscript/`](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md).
61
+
62
+ * **Gut-associated lymphoid tissues** (Siniscalco *et al.*, *Immunity* 2025): the clone embedding resolves
63
+ a continuous path of clones from GC B cells, through clones that contain both GC B cells and plasma
64
+ cells, to plasma-cell clones, with clones that lack GC-fate labelling grouped at its end.
65
+ * **Spontaneous germinal centres** (Castrillon *et al.*, *eLife* 2023): position along the clone embedding
66
+ orders clones by the diversity of their cell states, and memory-containing clones concentrate at one
67
+ end.
68
+ * ***Plasmodium* infection** (Skinner *et al.*, *Nat. Immunol.* 2026): whether plasmablasts were sampled
69
+ together with GC B cells of the same clone is a property of clones that cannot be read from the
70
+ cell-level embedding.
71
+ * **Model-antigen germinal centres** (Merkenschlager *et al.*, *Nature* 2025): the main axis of variation
72
+ between clone profiles follows recent division in two cohorts whose sequencing libraries are crossed, so
73
+ the association cannot be a library artefact; antigen-bait and dark-zone gates are also associated with
74
+ clone profiles but were each sequenced in their own library.
75
+
76
+ ## Installation
77
+
78
+ ```bash
79
+ pip install "git+https://github.com/Reynold4k/Threadfin.git"
80
+ # with Dandelion, to define clones from BCR contigs:
81
+ pip install "threadfin[dandelion] @ git+https://github.com/Reynold4k/Threadfin.git"
82
+ ```
83
+
84
+ Threadfin requires Python ≥ 3.10 and is tested on 3.10 to 3.14, down to the oldest dependency versions it
85
+ allows ([compatibility](https://github.com/Reynold4k/Threadfin/blob/main/docs/COMPATIBILITY.md)); Scanpy, Leiden, UMAP and Harmony are installed with it, and no
86
+ GPU or R is needed. Clones can be defined from BCR contigs with Dandelion (the `[dandelion]` extra also pins
87
+ `matplotlib<3.9`, which Dandelion 0.5.7 needs but does not declare), or you can provide your own clone ids
88
+ in `adata.obs["clone_id"]`. Dandelion's clone calls depend on Python's string-hash seed; start Python with
89
+ `PYTHONHASHSEED=0` if clone ids must be identical run after run.
90
+
91
+ ## Quick start
92
+
93
+ ```python
94
+ import scanpy as sc
95
+ import threadfin as tf
96
+
97
+ adata = sc.read_h5ad("b_cells.h5ad") # raw counts, one row per cell
98
+
99
+ result = tf.run(
100
+ adata,
101
+ bcr="filtered_contig_annotations.csv", # Cell Ranger VDJ output or an AIRR .tsv
102
+ donor_key="donor", # the individual each cell came from
103
+ sample_key="sample", # the sample or library each cell came from
104
+ )
105
+ print(result.summary()) # plain-language report
106
+ result.plot("threadfin_overview.pdf") # clone map, coherence, stability, composition
107
+ print(result.methods()) # a Methods paragraph with the settings used
108
+ ```
109
+
110
+ `tf.run` defines clones within each donor, builds an expression embedding without immunoglobulin genes,
111
+ estimates one profile per clone, tests clonal coherence, lays out the clone embedding, finds clonal
112
+ programmes and reports their stability. Add `test=[...]` to test your own labels and `time_key=` to ask
113
+ whether clones keep their state, and `n_jobs=-1` to use every CPU core (the results do not change). No data
114
+ at hand? `tf.sim.simulate_repertoire()` makes a repertoire with a known answer
115
+ ([Tutorial 1](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md)).
116
+ T cells work the same way, with TCR contigs as `bcr`, and receptor data loaded with scirpy can be passed as
117
+ they are ([Tutorial 2, section 6](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md#6-how-clones-are-called)).
118
+
119
+ <p align="center">
120
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/tutorial_overview.png" width="760" alt="Overview figure produced by result.plot()">
121
+ </p>
122
+
123
+ ## A complete, tested tutorial on public data
124
+
125
+ [`docs/tutorials/05_end_to_end_tutorial.ipynb`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) takes you from an
126
+ empty folder to the main result of the manuscript's Figure 4: it creates the environment
127
+ ([`environment.yml`](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/environment.yml)), downloads a published dataset from GEO (GSE287123,
128
+ about 600 MB), assigns cells to mice from hashtags, defines clones, builds the embedding, runs Threadfin and
129
+ explains every output, including how to tell biology from a sequencing-library effect. It was executed end
130
+ to end in a fresh environment before release and takes about 6 minutes on 8 CPU cores (about 8 GB of memory).
131
+
132
+ ## A clone embedding that holds together
133
+
134
+ UMAP draws continuous populations of clones as one picture only for suitable settings, and the suitable
135
+ settings differ between datasets. Threadfin therefore chooses them for each dataset by default: it lays
136
+ the clones out over a ladder of settings, scores each layout for coherence (the fraction of clones in one
137
+ connected piece) and for fidelity to the clone profiles, and keeps the most faithful setting that holds
138
+ together in every layout it tried. A map is not allowed to be more fragmented than the clone profiles
139
+ themselves, and the final map is checked once more before it is returned. The record of the choice is
140
+ stored with the results, and the settings can always be fixed by hand
141
+ ([Tutorial 3](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md)).
142
+
143
+ ```python
144
+ tf.tl.embed_clones(adata) # automatic (default)
145
+ tf.tl.embed_clones(adata, n_neighbors=30, min_dist=0.3) # by hand
146
+ tf.tl.map_quality(features, xy) # score any clone map (profiles, coordinates)
147
+ ```
148
+
149
+ ## How it works
150
+
151
+ <p align="center">
152
+ <img src="https://raw.githubusercontent.com/Reynold4k/Threadfin/main/docs/_static/threadfin_workflow.png" width="760" alt="Threadfin workflow">
153
+ </p>
154
+
155
+ 1. **Clones** are defined from paired heavy- and light-chain sequences within each donor (Dandelion).
156
+ 2. **Clone profiles.** Each cell is described relative to the mean of its sampling context. The cells of
157
+ a clone are summarised by a kernel mean embedding of their state distribution, so a clone divided
158
+ between two states differs from a clone in an intermediate state, and the profile is shrunk towards the
159
+ context according to the number of cells (best linear unbiased prediction under a random-effects
160
+ model).
161
+ 3. **Clonal coherence** is the intraclass correlation of state within clones, tested against clone labels
162
+ permuted within samples.
163
+ 4. **The clone embedding** is a UMAP of the clone profiles with settings chosen as above.
164
+ 5. **Clonal programmes** are graph communities of clones; each split is tested against a single Gaussian
165
+ group, and each programme's stability is estimated by bootstrap resampling.
166
+ 6. **Clone-level tests** quantify how much of the variance between clone profiles a label explains, with
167
+ labels permuted among the clones of each donor.
168
+
169
+ The full description, with references, is in [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md).
170
+
171
+ ## Documentation
172
+
173
+ | | |
174
+ |---|---|
175
+ | [Tutorial 1 — Getting started](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/01_getting_started.md) | the whole analysis on simulated data, with its output |
176
+ | [Tutorial 2 — Your own data](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/02_your_data.md) | from Cell Ranger output to results, with several samples and donors |
177
+ | [Tutorial 3 — The clone map](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/03_clone_map.md) | automatic and hand-set layouts, and how to check a map |
178
+ | [Tutorial 4 — Step by step](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/04_step_by_step.md) | the individual functions in `threadfin.tl` |
179
+ | [Tutorial 5 — From GEO to results (notebook)](https://github.com/Reynold4k/Threadfin/blob/main/docs/tutorials/05_end_to_end_tutorial.ipynb) | a published dataset end to end: download, demultiplexing, clones, embedding, Threadfin, interpretation |
180
+ | [Methods](https://github.com/Reynold4k/Threadfin/blob/main/docs/METHODS.md) | the statistical model behind each step |
181
+ | [Function reference](https://github.com/Reynold4k/Threadfin/blob/main/docs/API.md) | every public function and its arguments, generated from the code |
182
+ | [The manuscript](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/README.md) | publication status, datasets, every analysis, open work |
183
+ | [Case studies](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/case_studies/README.md) | scripts and results for the public datasets |
184
+ | [Figures](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/figures/README.md) | figures of the manuscript, with their source code |
185
+ | [Benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md) | Threadfin against Clonotrace, clone2vec, Benisse, CoNGA and scirpy |
186
+ | [Changelog](https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md) | what changed in each version |
187
+
188
+ ## Citation
189
+
190
+ A manuscript describing Threadfin is in preparation. Until it is available, please cite this repository
191
+ ([CITATION.cff](https://github.com/Reynold4k/Threadfin/blob/main/CITATION.cff)) and the tools Threadfin builds on: Dandelion (Suo *et al.*, *Nat.
192
+ Biotechnol.* 2024) for clone definition, Scanpy (Wolf *et al.*, *Genome Biol.* 2018) and UMAP (McInnes
193
+ *et al.*, *J. Open Source Softw.* 2018).
194
+
195
+ ## How Threadfin compares with related tools
196
+
197
+ Clonotrace, clone2vec, Benisse and CoNGA also combine lineage and transcriptome, and answer related but
198
+ different questions. On the same data and clones ([benchmark](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/benchmarking/README.md), with a
199
+ one-page overview): Threadfin and Benisse represent every clone with two or more cells by default
200
+ (clone2vec starts at three cells, Clonotrace at ten), and Threadfin's test of clonal coherence keeps its
201
+ error rate when samples differ, where per-clone graph scores and cell-level tests do not. For recovering
202
+ measured clone annotations Threadfin is comparable to clone2vec and to a simple mean of the cells'
203
+ coordinates, and better than Clonotrace at its default and than Benisse; in simulation, clone2vec groups clones by their
204
+ planted programme and tells mixed from in-between clones more accurately. Threadfin needs a fraction of the
205
+ others' time (its clone profiles take seconds; clone2vec about 30 times longer, Clonotrace 300 to 2,400
206
+ times) and finished every run without help; a million cells take about an hour on 8 cores
207
+ ([scalability](https://github.com/Reynold4k/Threadfin/blob/main/manuscript/analyses/technical_validation/scalability/README.md)).
208
+ The benchmark reports every result, including those where Threadfin is not the best.
209
+
210
+ ## Related tools
211
+
212
+ * [Dandelion](https://github.com/zktuong/dandelion) — single-cell immune receptor analysis; Threadfin's
213
+ clone definition.
214
+ * [Clonotrace](https://github.com/yuntianf/Clonotrace) — distances between expanded clones on the cell-state
215
+ graph after label spreading.
216
+ * [clone2vec](https://github.com/kharchenkolab/clone2vec) — clone embeddings learned from which clones'
217
+ cells are neighbours.
218
+ * [Benisse](https://github.com/wooyongc/Benisse) — a joint space of BCR sequences and expression.
219
+ * [CoNGA](https://github.com/phbradley/conga) — graph-vs-graph analysis of T-cell receptor and expression
220
+ similarity.
221
+ * [Scirpy](https://github.com/scverse/scirpy) — single-cell immune receptor analysis in the scverse
222
+ ecosystem; Threadfin reads its AnnData and MuData objects.
223
+ * [Scanpy](https://github.com/scverse/scanpy) and [AnnData](https://github.com/scverse/anndata) — the data
224
+ structures and single-cell tools Threadfin works with.
225
+ * [Immcantation](https://immcantation.readthedocs.io) — B-cell receptor repertoire analysis, including
226
+ clonal lineage reconstruction.
227
+
228
+ ## Support
229
+
230
+ Please report bugs and ask questions through [GitHub issues](https://github.com/Reynold4k/Threadfin/issues).
231
+
232
+ ## License
233
+
234
+ MIT; see [LICENSE](https://github.com/Reynold4k/Threadfin/blob/main/LICENSE).
@@ -0,0 +1,73 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "threadfin"
7
+ version = "4.5.0"
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
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [
13
+ { name = "Chen Satoshi", email = "103236530+Reynold4k@users.noreply.github.com" },
14
+ ]
15
+ keywords = ["single-cell", "scRNA-seq", "BCR", "VDJ", "B cell", "clone", "clonal lineage",
16
+ "germinal center", "immunology", "repertoire"]
17
+ classifiers = [
18
+ "Intended Audience :: Science/Research",
19
+ "License :: OSI Approved :: MIT License",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Programming Language :: Python :: 3.14",
26
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
27
+ ]
28
+ dependencies = [
29
+ "anndata>=0.10",
30
+ "numpy>=1.24",
31
+ "pandas>=2.0",
32
+ "scipy>=1.10",
33
+ "scikit-learn>=1.3",
34
+ "joblib>=1.2", # parallel clone-map search and programme bootstrap (n_jobs)
35
+ "scanpy>=1.10",
36
+ "matplotlib>=3.7",
37
+ "igraph>=0.10",
38
+ "leidenalg>=0.10",
39
+ "umap-learn>=0.5.5", # older releases import pkg_resources, absent from new environments
40
+ "pynndescent>=0.5.8", # likewise
41
+ "harmonypy>=0.0.9; platform_system != 'Windows'",
42
+ # harmonypy 2.x ships no Windows wheels and does not compile with MSVC; 0.2 and earlier are pure Python
43
+ "harmonypy>=0.0.9,<2; platform_system == 'Windows'",
44
+ ]
45
+
46
+ [project.optional-dependencies]
47
+ # clone definition with Dandelion; sc-dandelion 0.5.7 uses matplotlib.cm.get_cmap, removed in matplotlib 3.9
48
+ dandelion = ["sc-dandelion>=0.5.7", "matplotlib>=3.7,<3.9"]
49
+ seq = ["parasail>=1.3"] # faster CDR3 alignment for the legacy v3 functions
50
+ data = ["mudata>=0.3", "awkward>=2"] # reading scirpy/MuData example data
51
+ test = ["pytest>=7", "pytest-cov>=4"]
52
+ benchmark = ["clone2vec>=0.1", "psutil>=5"]
53
+
54
+ [project.urls]
55
+ Homepage = "https://github.com/Reynold4k/Threadfin"
56
+ Repository = "https://github.com/Reynold4k/Threadfin"
57
+ Issues = "https://github.com/Reynold4k/Threadfin/issues"
58
+ Documentation = "https://github.com/Reynold4k/Threadfin/blob/main/docs/README.md"
59
+ Changelog = "https://github.com/Reynold4k/Threadfin/blob/main/CHANGELOG.md"
60
+
61
+ [tool.setuptools.packages.find]
62
+ include = ["threadfin*"]
63
+
64
+ [tool.pytest.ini_options]
65
+ testpaths = ["tests"]
66
+ filterwarnings = [
67
+ "ignore::DeprecationWarning",
68
+ "ignore::FutureWarning",
69
+ ]
70
+
71
+ [tool.ruff]
72
+ line-length = 120
73
+ target-version = "py310"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,13 @@
1
+ """docs/API.md is generated from the docstrings; it must match the code it describes."""
2
+
3
+ import importlib.util
4
+ from pathlib import Path
5
+
6
+ DOCS = Path(__file__).resolve().parents[1] / "docs"
7
+
8
+
9
+ def test_api_reference_is_current():
10
+ spec = importlib.util.spec_from_file_location("make_api_reference", DOCS / "make_api_reference.py")
11
+ mod = importlib.util.module_from_spec(spec)
12
+ spec.loader.exec_module(mod)
13
+ assert (DOCS / "API.md").read_text(encoding="utf-8") == mod.render(), "run: python docs/make_api_reference.py"