actinn-jax 0.3.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 (51) hide show
  1. actinn_jax-0.3.0/LICENSE +25 -0
  2. actinn_jax-0.3.0/MANIFEST.in +23 -0
  3. actinn_jax-0.3.0/PKG-INFO +453 -0
  4. actinn_jax-0.3.0/README.md +410 -0
  5. actinn_jax-0.3.0/actinn_jax/__init__.py +57 -0
  6. actinn_jax-0.3.0/actinn_jax/actinn_predict.py +597 -0
  7. actinn_jax-0.3.0/actinn_jax/actinn_utils.py +240 -0
  8. actinn_jax-0.3.0/actinn_jax/cli.py +139 -0
  9. actinn_jax-0.3.0/actinn_jax/embed.py +84 -0
  10. actinn_jax-0.3.0/actinn_jax/hierarchy.py +638 -0
  11. actinn_jax-0.3.0/actinn_jax/novelty.py +136 -0
  12. actinn_jax-0.3.0/actinn_jax/references/README.md +126 -0
  13. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/build_info.json +52 -0
  14. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/coarse.json +1 -0
  15. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/coarse.npz +0 -0
  16. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Embryonic cell.json +1 -0
  17. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Embryonic cell.npz +0 -0
  18. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Endothelial cell.json +1 -0
  19. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Endothelial cell.npz +0 -0
  20. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Epithelial cell.json +1 -0
  21. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Epithelial cell.npz +0 -0
  22. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Fibroblast.json +1 -0
  23. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Fibroblast.npz +0 -0
  24. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Glial cell.json +1 -0
  25. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Glial cell.npz +0 -0
  26. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Immune cell.json +1 -0
  27. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Immune cell.npz +0 -0
  28. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Muscle cell.json +1 -0
  29. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Muscle cell.npz +0 -0
  30. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Neuron.json +1 -0
  31. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Neuron.npz +0 -0
  32. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Perivascular cell.json +1 -0
  33. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/fine_Perivascular cell.npz +0 -0
  34. actinn_jax-0.3.0/actinn_jax/references/panhuman_distill_v1/manifest.json +1 -0
  35. actinn_jax-0.3.0/actinn_jax/registry.py +205 -0
  36. actinn_jax-0.3.0/actinn_jax.egg-info/PKG-INFO +453 -0
  37. actinn_jax-0.3.0/actinn_jax.egg-info/SOURCES.txt +49 -0
  38. actinn_jax-0.3.0/actinn_jax.egg-info/dependency_links.txt +1 -0
  39. actinn_jax-0.3.0/actinn_jax.egg-info/entry_points.txt +2 -0
  40. actinn_jax-0.3.0/actinn_jax.egg-info/not-zip-safe +1 -0
  41. actinn_jax-0.3.0/actinn_jax.egg-info/requires.txt +23 -0
  42. actinn_jax-0.3.0/actinn_jax.egg-info/top_level.txt +1 -0
  43. actinn_jax-0.3.0/examples/build_reference.py +44 -0
  44. actinn_jax-0.3.0/examples/detect_novel_celltypes.py +54 -0
  45. actinn_jax-0.3.0/examples/quickstart_annotate.py +39 -0
  46. actinn_jax-0.3.0/pyproject.toml +73 -0
  47. actinn_jax-0.3.0/setup.cfg +4 -0
  48. actinn_jax-0.3.0/tests/conftest.py +36 -0
  49. actinn_jax-0.3.0/tests/test_actinn.py +171 -0
  50. actinn_jax-0.3.0/tests/test_hierarchy.py +299 -0
  51. actinn_jax-0.3.0/tests/test_novelty.py +49 -0
@@ -0,0 +1,25 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ian Driver
4
+
5
+ This project is a reimplementation of ACTINN (Ma & Pellegrini, Bioinformatics
6
+ 2020; https://github.com/mafeiyang/ACTINN), which is also released under the MIT
7
+ License.
8
+
9
+ Permission is hereby granted, free of charge, to any person obtaining a copy
10
+ of this software and associated documentation files (the "Software"), to deal
11
+ in the Software without restriction, including without limitation the rights
12
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13
+ copies of the Software, and to permit persons to whom the Software is
14
+ furnished to do so, subject to the following conditions:
15
+
16
+ The above copyright notice and this permission notice shall be included in all
17
+ copies or substantial portions of the Software.
18
+
19
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25
+ SOFTWARE.
@@ -0,0 +1,23 @@
1
+ # Controls the SOURCE distribution. `include-package-data = false` in pyproject.toml only
2
+ # governs the wheel -- sdists are assembled by different rules, and without this file the
3
+ # sdist was 110 MB (all bundled references), over PyPI's 100 MB per-file limit even though
4
+ # the wheel was fine at 15 MB.
5
+ #
6
+ # The large references are downloaded from Zenodo at runtime (actinn_jax/registry.py); only
7
+ # the small default one is distributed.
8
+
9
+ prune actinn_jax/references
10
+ recursive-include actinn_jax/references/panhuman_distill_v1 *.npz *.json
11
+ include actinn_jax/references/README.md
12
+
13
+ include LICENSE
14
+ include README.md
15
+ recursive-include tests *.py
16
+ recursive-include examples *.py
17
+
18
+ # Never ship a local dev environment, build leftovers, or caches.
19
+ prune .venv
20
+ prune build
21
+ prune dist
22
+ prune .github
23
+ global-exclude *.py[cod] __pycache__/* .DS_Store
@@ -0,0 +1,453 @@
1
+ Metadata-Version: 2.4
2
+ Name: actinn-jax
3
+ Version: 0.3.0
4
+ Summary: Fast JAX reimplementation of ACTINN for single-cell cell-type reference mapping
5
+ Author-email: Ian Driver <driver.ian@gmail.com>
6
+ License: MIT
7
+ Keywords: single-cell,cell-type-annotation,ACTINN,jax,scanpy
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Intended Audience :: Science/Research
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Natural Language :: English
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Operating System :: MacOS :: MacOS X
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Operating System :: POSIX :: Linux
18
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: numpy>=1.15
23
+ Requires-Dist: scipy>=1.7
24
+ Requires-Dist: anndata>=0.6.22
25
+ Requires-Dist: pandas>=1.3
26
+ Requires-Dist: h5py
27
+ Requires-Dist: scanpy>=1.8
28
+ Requires-Dist: jax>=0.4.0
29
+ Requires-Dist: jaxlib>=0.4.0
30
+ Requires-Dist: optax>=0.1.5
31
+ Provides-Extra: metal
32
+ Requires-Dist: jax-metal; extra == "metal"
33
+ Provides-Extra: test
34
+ Requires-Dist: pytest; extra == "test"
35
+ Provides-Extra: notebooks
36
+ Requires-Dist: jupyterlab; extra == "notebooks"
37
+ Requires-Dist: ipykernel; extra == "notebooks"
38
+ Requires-Dist: matplotlib; extra == "notebooks"
39
+ Requires-Dist: pronto; extra == "notebooks"
40
+ Requires-Dist: leidenalg; extra == "notebooks"
41
+ Requires-Dist: igraph; extra == "notebooks"
42
+ Dynamic: license-file
43
+
44
+ # actinn-jax
45
+
46
+ Fast, dependency-light cell-type **reference mapping** for single-cell data: train
47
+ on a labeled reference dataset, then annotate any query dataset.
48
+
49
+ ## ⭐ Annotate single-cell data — fast, on CPU
50
+
51
+ Pre-trained organism-wide references ship with the package, so unknown data works out of
52
+ the box. From the command line, with no arguments to choose:
53
+
54
+ ```bash
55
+ actinn-jax annotate my_data.h5ad --min-prob 0.5 -o annotations.csv
56
+ ```
57
+
58
+ That infers the organism from the query's gene ids and loads the matching reference.
59
+ `actinn-jax references` lists what is installed. From Python:
60
+
61
+ ```python
62
+ import scanpy as sc, actinn_jax as aj
63
+
64
+ for r in aj.list_references(): # what's available, and for what
65
+ print(r["name"], r["organism"], r["n_classes"])
66
+
67
+ adata = sc.read_h5ad("my_data.h5ad") # raw counts
68
+ model = aj.bundled_reference("panhuman_distill_v1") # pre-trained, CPU-only
69
+ adata = aj.annotate(adata, model, min_prob=0.5) # -> obs['celltype', _coarse, _probability]
70
+ ```
71
+
72
+ Annotating with a reference for the wrong organism raises rather than returning
73
+ meaningless labels.
74
+
75
+ ### Where the references live
76
+
77
+ `panhuman_distill_v1` (16 MB, human) ships inside the wheel, so `pip install actinn-jax`
78
+ annotates human data offline with nothing to download. The census-scale references are
79
+ tens of MB each and are **fetched once on first use** from Zenodo
80
+ ([10.5281/zenodo.21688151](https://doi.org/10.5281/zenodo.21688151)), then cached in
81
+ `~/.cache/actinn-jax/` — `bundled_reference("broad_mouse_v1")` works whether or not it has
82
+ been downloaded before (~40 s on a cold cache, instant after). Each archive is
83
+ checksum-verified before it is unpacked.
84
+
85
+ For a tutorial or a workshop on a slow connection, pull them ahead of time:
86
+
87
+ ```bash
88
+ actinn-jax fetch # everything
89
+ actinn-jax fetch broad_mouse_v1 # or just one
90
+ actinn-jax references # installed / cached / available
91
+ actinn-jax cache --clear # free the space again
92
+ ```
93
+
94
+ In a notebook the same thing is one call, and it is safe to re-run:
95
+
96
+ ```python
97
+ from actinn_jax import registry
98
+ registry.fetch_reference("broad_mouse_v1") # no-op once cached
99
+ ```
100
+
101
+ Point `ACTINN_JAX_REFERENCE_URL` at a mirror to serve them from somewhere else, and
102
+ `ACTINN_JAX_CACHE` to relocate the cache (useful on a shared cluster filesystem).
103
+
104
+ Under the hood this is a **two-stage workflow**: a coarse→fine cell-type hierarchy is
105
+ discovered *once, offline*, and a small actinn-jax model trained on it annotates new data
106
+ in **milliseconds on a CPU — no GPU at inference**.
107
+
108
+ `min_prob` is an **abstain threshold**: cells whose confidence is below it are labeled
109
+ `"unknown"` instead of being force-mapped to the nearest reference type — so genuinely
110
+ novel cell types get flagged rather than mislabeled. Held-out calibration (10% of cell
111
+ types held out entirely as out-of-distribution):
112
+
113
+ | `min_prob` | accuracy (kept) | coverage | OOD flagged as unknown |
114
+ |-----------:|----------------:|---------:|-----------------------:|
115
+ | 0.0 (off) | 0.55 | 100% | 0% |
116
+ | 0.5 | 0.80 | 46% | 75% |
117
+ | 0.7 | 0.86 | 30% | 88% |
118
+
119
+ Breadth vs. precision is a deliberate trade: ~800-way annotation from a small per-type
120
+ sample is far harder than a narrow atlas (many near-duplicate subtypes, e.g. cortical
121
+ neuron layers), so raw accuracy is lower than a focused reference — the abstain threshold
122
+ recovers precision on the cells it keeps. For a narrower, higher-accuracy reference on
123
+ your own cell types, build one (below).
124
+
125
+ The abstain threshold above is for the ~800-type census reference; each bundled reference
126
+ reports its own calibration in `build_info.json`, and `broad_mouse_v1`'s is notably better
127
+ (0.88 accuracy at 82% coverage).
128
+
129
+ **Build your own reference** (the only step that may use a GPU; install `scprint`):
130
+
131
+ ```python
132
+ from actinn_jax.embed import scprint_embed
133
+ emb = scprint_embed(ref_adata) # GPU/MPS, once
134
+ model = aj.build_hierarchical_reference(ref_adata, "cell_type", emb)
135
+ model.save("my_reference") # then annotate on CPU
136
+ ```
137
+
138
+ **`refine_to_query`** masks the broad reference down to just the classes your query's own
139
+ predictions actually support (no ground truth, no retraining, sub-second):
140
+
141
+ ```python
142
+ refined = aj.refine_to_query(model, adata)
143
+ adata = aj.annotate(adata, refined)
144
+ ```
145
+
146
+ Measured on real data (see
147
+ [actinn-jax-benchmark's REFINE.md](https://github.com/iandriver/actinn-jax-benchmark/blob/main/docs/REFINE.md)):
148
+ this is a safe, free pruning pass — it reliably protects real types and never made
149
+ accuracy worse in testing — but it's **not a fix** for the large-reference accuracy gap.
150
+ The classes actually causing confusion are the model's genuinely-confusable siblings of
151
+ real types, and they carry the same confidence signature as real rare ones, so no
152
+ threshold built from the classifier's own output cleanly separates them. **Retraining on
153
+ a narrower, focused reference (`build_reference.py` above) is the reliable way to close
154
+ that gap** — it measurably outperforms masking because it reshapes the decision boundary
155
+ rather than restricting a frozen one's candidate set.
156
+
157
+ **`refine_to_tissue`** uses a stronger, label-free prior: a sample is (mostly) from one
158
+ tissue, and a liver sample should not be labeled with lung-specific epithelium. It prunes
159
+ the candidate classes to those the CELLxGENE census records in that tissue, while keeping
160
+ **pan-tissue** types (immune, endothelial, stromal) available everywhere — so
161
+ liver-resident T cells and macrophages are unaffected. The broad reference ships with a
162
+ per-class tissue map (`tissue_general` from ~62 M census cells) baked in, so this is
163
+ offline and instant:
164
+
165
+ ```python
166
+ refined = aj.refine_to_tissue(model, tissue='liver') # or ['liver','blood'] for mixed
167
+ adata = aj.annotate(adata, refined)
168
+ # or read the tissue from adata.obs['tissue'/'tissue_general'] automatically:
169
+ refined = aj.refine_to_tissue(model, adata=adata) # tissue inferred from obs
170
+ ```
171
+
172
+ On a real liver query this roughly **halves** the label set — it removes the cross-tissue
173
+ misfires (cardiac muscle, alveolar fibroblast, colonocyte, adrenal cortex…) that the broad
174
+ 798-type model otherwise scatters in, while leaving hepatocyte / LSEC / stellate counts
175
+ essentially unchanged. It composes with `refine_to_query` (a class must be both evidenced
176
+ *and* tissue-plausible):
177
+
178
+ ```python
179
+ refined = aj.refine_to_query(model, adata, tissue='liver') # tissue='auto' reads obs
180
+ ```
181
+
182
+ Common synonyms (`PBMC`→blood, `hepatic`→liver, …) are recognized; a tissue not in the
183
+ reference's vocabulary, or a reference with no tissue map, simply imposes no filter.
184
+
185
+ ## Finding novel / unknown cell types
186
+
187
+ A cell type the reference has never seen doesn't show up as a few scattered uncertain
188
+ cells — it shows up as a **coherent group the reference can't confidently explain**.
189
+ `detect_novel_celltypes` looks for exactly that: clusters that are both large enough to
190
+ be a real population and predominantly low-confidence. (This is cluster-level rejection —
191
+ distinct from the per-cell `min_prob` abstain, which flags individual uncertain cells.)
192
+
193
+ ```python
194
+ evidence, markers = aj.detect_novel_celltypes(
195
+ model, adata,
196
+ cluster_key='leiden', # your clustering; omit to auto-cluster (needs leidenalg)
197
+ min_cells=10, # size floor for calling something novel — lower to go rarer
198
+ )
199
+ evidence[evidence.novel] # candidate novel populations, most-suspect first
200
+ markers['novel_1'] # its top marker genes (vs the rest of the dataset)
201
+ adata.obs['novel'] # 'novel_1'… on flagged cells, '' otherwise
202
+ ```
203
+
204
+ `min_cells` is the tunable **minimum population size** — the default (10) separates a real
205
+ novel type from noise/doublets; lower it (`min_cells=5`) to surface rarer candidates, raise
206
+ it to be stricter. `evidence` also reports each cluster's `nearest_label` (what the
207
+ reference *would* have called it) and `frac_low_conf`.
208
+
209
+ **Validated on a real discovery.** In the Krasnow *et al.* (2020) human lung atlas we
210
+ trained a reference but **withheld the pulmonary ionocyte** — itself a landmark 2018
211
+ novel-cell-type discovery (Montoro/Plasschaert) — then ran `detect_novel_celltypes`. Of all
212
+ 57 populations, the 22 withheld ionocytes were the **only** cluster flagged (86% low
213
+ confidence, median 0.30; the reference would have mislabeled them "B cell"), and the
214
+ recovered markers were led by **ASCL3** (the ionocyte master transcription factor) and
215
+ **ATP6V0B** (the V-ATPase subunit ionocytes are named for). Raising `min_cells` above 22
216
+ correctly drops the flag — the knob does what it says. The full walkthrough (with the
217
+ t-SNE highlight of the flagged population) is in
218
+ [`examples/novel_celltypes.ipynb`](https://github.com/iandriver/actinn-jax/blob/main/examples/novel_celltypes.ipynb); a script version is
219
+ [`examples/detect_novel_celltypes.py`](https://github.com/iandriver/actinn-jax/blob/main/examples/detect_novel_celltypes.py).
220
+
221
+ ## Focused reference: liver (HLiCA)
222
+
223
+ `liver_hlica_v2` ships a **48-type, 7-lineage liver reference** built from
224
+ [HLiCA](https://doi.org/10.64898/2026.06.30.735539) (Edgar, Portman, Hu et al. 2026),
225
+ a 522,730-cell, 110-donor, expert-curated integrated human liver atlas — including
226
+ hepatocyte and endothelial **zonation** (periportal/pericentral), plasmacytoid dendritic
227
+ cells, and HLiCA's own novel-cell-type findings (NRXN1+ stromal cells, CUX2+ hepatic
228
+ stellate cells, MAMLD1+ trans monocytes, TREM2+ macrophages). This is exactly the
229
+ `refine_to_query` → `build_reference.py` recommendation above, executed for real: on a
230
+ held-out study, this focused reference reaches **exact-CL 0.72 / ontology 0.86**, vs.
231
+ **0.23 / 0.58** for the broad 798-type reference on the same cells (see
232
+ [actinn-jax-benchmark's HLICA_LIVER.md](https://github.com/iandriver/actinn-jax-benchmark/blob/main/docs/HLICA_LIVER.md)
233
+ and
234
+ [HLICA_EDGE_CASES.md](https://github.com/iandriver/actinn-jax-benchmark/blob/main/docs/HLICA_EDGE_CASES.md)
235
+ for the full cross-study validation and how v2 fixed two coverage gaps found by checking
236
+ the paper's own stated edge cases against v1).
237
+
238
+ ```python
239
+ model = aj.bundled_reference("liver_hlica_v2")
240
+ adata = aj.annotate(adata, model)
241
+ ```
242
+
243
+ (`liver_hlica_v1`, 38 types, also ships — for anyone who wants the smaller taxonomy.)
244
+
245
+ Data used under CC-BY 4.0; please cite the original paper if you use this reference.
246
+
247
+ **Runnable notebooks:**
248
+ [`examples/annotate_with_timing.ipynb`](https://github.com/iandriver/actinn-jax/blob/main/examples/annotate_with_timing.ipynb) annotates a
249
+ 65k-cell human lung atlas end-to-end — load, throughput (cells/s), exact vs
250
+ **ontology-aware** concordance, and the abstain sweep.
251
+ [`examples/liver_zonation.ipynb`](https://github.com/iandriver/actinn-jax/blob/main/examples/liver_zonation.ipynb) shows **fine-label
252
+ mapping around hepatocyte zonation** — mapping a liver dataset onto the portal→mid→central
253
+ axis, with a confusion heatmap and ordinal (within-1-zone) scoring. See also
254
+ [`examples/quickstart_annotate.py`](https://github.com/iandriver/actinn-jax/blob/main/examples/quickstart_annotate.py) and
255
+ [`examples/build_reference.py`](https://github.com/iandriver/actinn-jax/blob/main/examples/build_reference.py). The *why* —
256
+ accuracy/speed/memory benchmarks and the design rationale — lives in the companion
257
+ [actinn-jax-benchmark](https://github.com/iandriver/actinn-jax-benchmark) repo
258
+ ([model-flow mini-paper](https://github.com/iandriver/actinn-jax-benchmark/blob/main/docs/MODEL_FLOW.md)).
259
+
260
+ ---
261
+
262
+
263
+ `actinn-jax` is a from-scratch **JAX** reimplementation of
264
+ [ACTINN](https://github.com/mafeiyang/ACTINN.git) (Ma, Pellegrini et al.). The
265
+ original ACTINN was written in TensorFlow 1.x; this version replaces it with a
266
+ small JIT-compiled JAX MLP and a sparse-aware preprocessing pipeline, adds a
267
+ cached "train once, map many" reference model, and scales to atlas-sized data.
268
+
269
+ ## Attribution
270
+
271
+ This package is based entirely on the ACTINN method. If you use it, please cite
272
+ the original work:
273
+
274
+ > Feiyang Ma, Matteo Pellegrini. **ACTINN: automated identification of cell types
275
+ > in single cell RNA sequencing.** *Bioinformatics*, 2020.
276
+ > https://doi.org/10.1093/bioinformatics/btz592
277
+
278
+ Original ACTINN implementation: https://github.com/mafeiyang/ACTINN
279
+
280
+ ## Installation
281
+
282
+ The classifier is a small MLP in JAX — **no TensorFlow dependency** — so a plain
283
+ CPU install works everywhere and needs no special wheels.
284
+
285
+ ### With `uv` (recommended)
286
+
287
+ [`uv`](https://docs.astral.sh/uv/) resolves the scientific stack (JAX, scanpy) fast
288
+ and pins a compatible Python for you:
289
+
290
+ ```bash
291
+ git clone https://github.com/iandriver/actinn-jax.git
292
+ cd actinn-jax
293
+ uv venv --python 3.12 # create .venv on a supported Python
294
+ uv pip install -e . # install actinn-jax + deps into it
295
+ source .venv/bin/activate # (or: `uv run python -c "import actinn_jax"`)
296
+ ```
297
+
298
+ ### With `pip`
299
+
300
+ ```bash
301
+ git clone https://github.com/iandriver/actinn-jax.git
302
+ cd actinn-jax
303
+ python3.12 -m venv .venv && source .venv/bin/activate
304
+ pip install -e .
305
+ ```
306
+
307
+ Published builds also install straight from PyPI once released: `pip install actinn-jax`.
308
+
309
+ ### Running the example notebooks
310
+
311
+ The [`examples/`](https://github.com/iandriver/actinn-jax/blob/main/examples/) notebooks need a few extra packages (Jupyter,
312
+ matplotlib, the `pronto` ontology reader). Install the `notebooks` extra and
313
+ launch JupyterLab:
314
+
315
+ ```bash
316
+ uv pip install -e ".[notebooks]" # or: pip install -e ".[notebooks]"
317
+ uv run jupyter lab examples/ # or: jupyter lab examples/
318
+ ```
319
+
320
+ Each notebook has a `QUERY = '...'` line near the top — point it at your own
321
+ `.h5ad` (raw counts). No GPU or extra download is required: the pre-trained
322
+ references ship with the package.
323
+
324
+ ### Requirements
325
+
326
+ 1. [JAX](https://docs.jax.dev/en/latest/installation.html) — CPU by default, runs everywhere
327
+ 2. [scanpy](https://scanpy.readthedocs.io/) / [anndata](https://anndata.readthedocs.io/)
328
+ 3. Python 3.10–3.12 (3.13+ may lack JAX/scanpy wheels)
329
+
330
+ The model is small enough that the **CPU path is fast and is recommended**. On
331
+ Apple Silicon an experimental GPU backend is available via `uv pip install -e .[metal]`
332
+ (installs `jax-metal`), but for this model size it is not generally faster than CPU.
333
+
334
+ ## Input data
335
+
336
+ `actinn-jax` expects **raw integer counts**. For CELLxGENE-style objects where
337
+ `.X` is normalized and raw counts live in `.raw`, the default `use_raw='auto'`
338
+ picks the raw counts automatically. Genes are matched by `var_names`
339
+ (case-insensitive); the reference and query must share gene-name format.
340
+
341
+ ### Gene identifiers are matched automatically
342
+
343
+ Genes are matched by identifier, so query and reference must use the **same
344
+ identifier type**. The bundled references (`broad_human_v1`, `liver_hlica_v2`, …)
345
+ are keyed by **Ensembl gene IDs** (`ENSG…`). **You usually don't need to do
346
+ anything:** if your query's `var_names` are gene **symbols** (`A1BG`, `CD3D`, …)
347
+ and don't match, `actinn-jax` automatically falls back to the best-matching
348
+ `.var` column (`Ensembl_id`, `gene_ids`, `feature_id`, …) and prints a one-line
349
+ notice of which column it used.
350
+
351
+ If no identifier matches at all (neither `var_names` nor any `.var` column), it
352
+ raises a clear error rather than silently returning **one constant label** for
353
+ every cell (the classic symptom of an unmatched gene set). To force a specific
354
+ identifier yourself:
355
+
356
+ ```python
357
+ adata.var_names = adata.var['Ensembl_id'].astype(str).values # or 'gene_ids', etc.
358
+ adata.var_names_make_unique()
359
+ adata = aj.annotate(adata, model)
360
+ ```
361
+
362
+ (Symbol-keyed references work fine too — just make the *query* resolvable to the
363
+ *reference*. Check overlap with `set(adata.var_names) & set(model.coarse.norm_genes)`.)
364
+
365
+ ## Usage
366
+
367
+ ### One-off: train and predict in a single call
368
+
369
+ ```python
370
+ import actinn_jax as aj
371
+
372
+ adata, params = aj.celltype_predict_actinn(
373
+ adata, # query AnnData (raw counts)
374
+ 'reference.h5ad', # labeled reference
375
+ '/path/to/output_dir',
376
+ train_label_name='cell_type',
377
+ output_label_name='celltype_pred',
378
+ )
379
+ ```
380
+
381
+ Predictions are written to `adata.obs['celltype_pred']` and confidences to
382
+ `adata.obs['celltype_pred_probability']`.
383
+
384
+ ### Reference mapping: train once, map many queries (fastest)
385
+
386
+ ```python
387
+ import actinn_jax as aj
388
+
389
+ # Train once and cache to disk (weights .npz + metadata .json).
390
+ model = aj.train_reference('reference.h5ad', train_label_name='cell_type')
391
+ model.save('/path/to/my_reference')
392
+
393
+ # Later / elsewhere: load and annotate any number of queries, no retraining.
394
+ model = aj.ReferenceModel.load('/path/to/my_reference')
395
+ adata, _ = aj.predict(adata, model, output_label_name='celltype_pred')
396
+ ```
397
+
398
+ ### Large / atlas-scale references
399
+
400
+ ```python
401
+ # Balance + cap training cells per class (bounds memory, speeds up training);
402
+ # prediction runs in cell chunks so huge queries never fully densify.
403
+ model = aj.train_reference(
404
+ 'big_atlas.h5ad',
405
+ train_label_name='cell_type',
406
+ max_cells_per_label=500, # subsample per class
407
+ )
408
+ adata, _ = aj.predict(adata, model, chunk_size=50000)
409
+ ```
410
+
411
+ ### Standardization (opt-in accuracy boost)
412
+
413
+ `standardize=True` z-scores each gene with the reference's frozen mean/std and
414
+ applies the same transform to every query — a cheap domain-alignment into the
415
+ reference feature space (the CPU-transferable idea behind scANVI+scArches).
416
+ Across the Open Problems `label_projection` datasets it lifts mean accuracy
417
+ +0.3 pt and macro-F1 +1.1 pt, with the largest gains on batch-shifted and
418
+ fine-grained references (e.g. Tabula Sapiens +1.8 pt accuracy, GTEx macro-F1
419
+ +7.9 pt). See `docs/PREPROC_ABLATION.md` in the benchmark repo.
420
+
421
+ ```python
422
+ model = aj.train_reference('reference.h5ad', train_label_name='cell_type',
423
+ standardize=True) # scaler saved with the model
424
+ ```
425
+
426
+ It is **opt-in** (default `False`) because it shifts the softmax probability
427
+ calibration, which the two-stage refine / abstain thresholds are tuned against;
428
+ use it for a one-stage accuracy win, or re-tune those thresholds before combining.
429
+
430
+ ## How it works
431
+
432
+ - **Sparse-aware preprocessing** — gene-name matching and intersection happen on
433
+ the sparse matrix; only the shared-gene submatrix is densified.
434
+ - **Normalization** follows ACTINN: per-cell library-size normalize to 1e4,
435
+ `log2(x+1)`, then expr- and CV-percentile gene filtering. Optional per-gene
436
+ standardization (`standardize=True`) aligns the query into the reference's
437
+ feature space for an accuracy boost.
438
+ - **Model** — a 4-layer MLP (100→50→25→n_types), Glorot init, Adam with
439
+ exponential-decay schedule, trained with a JIT-compiled epoch step.
440
+ - **Cached `ReferenceModel`** stores the trained weights, gene set, and label
441
+ mapping so queries are projected onto the reference's fixed gene space.
442
+
443
+ ## Tests & benchmarks
444
+
445
+ ```bash
446
+ uv pip install -e ".[test]" # or: pip install -e ".[test]"
447
+ pytest # synthetic-data unit tests
448
+ python benchmark/benchmark.py # timing on synthetic data
449
+ ```
450
+
451
+ ## License
452
+
453
+ MIT. See [LICENSE](https://github.com/iandriver/actinn-jax/blob/main/LICENSE).