lumencell 0.1.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 (252) hide show
  1. lumencell-0.1.0/.github/workflows/ci.yml +174 -0
  2. lumencell-0.1.0/.github/workflows/publish.yml +53 -0
  3. lumencell-0.1.0/.gitignore +32 -0
  4. lumencell-0.1.0/.python-version +1 -0
  5. lumencell-0.1.0/LICENSE +21 -0
  6. lumencell-0.1.0/Makefile +103 -0
  7. lumencell-0.1.0/PKG-INFO +110 -0
  8. lumencell-0.1.0/README.md +78 -0
  9. lumencell-0.1.0/benchmarks/baseline.json +1020 -0
  10. lumencell-0.1.0/benchmarks/case_studies/results/sheih2020-2026-11-20.json +5989 -0
  11. lumencell-0.1.0/benchmarks/case_studies/sheih2020.py +55 -0
  12. lumencell-0.1.0/benchmarks/inspection/barcode_join.py +71 -0
  13. lumencell-0.1.0/benchmarks/inspection/daniel2022_formats.py +235 -0
  14. lumencell-0.1.0/benchmarks/inspection/daniel2022_metadata.py +118 -0
  15. lumencell-0.1.0/benchmarks/results/clonal-calibration-2026-11-13.json +1754 -0
  16. lumencell-0.1.0/benchmarks/results/clonal-calibration-n2-amended-2026-11-17.json +1769 -0
  17. lumencell-0.1.0/benchmarks/results/real-2026-11-10.json +156 -0
  18. lumencell-0.1.0/benchmarks/results/real-2026-11-13.json +264 -0
  19. lumencell-0.1.0/benchmarks/results/real-2026-11-17.json +318 -0
  20. lumencell-0.1.0/benchmarks/results/real-2026-11-20.json +444 -0
  21. lumencell-0.1.0/benchmarks/results/verdict-calibration-2026-11-17.json +1932 -0
  22. lumencell-0.1.0/benchmarks/results/verdict-verification-2026-11-17.json +2257 -0
  23. lumencell-0.1.0/benchmarks/thresholds.toml +522 -0
  24. lumencell-0.1.0/contracts/lcb1/fixture.json +129 -0
  25. lumencell-0.1.0/contracts/lcb1/fixture.lcb +0 -0
  26. lumencell-0.1.0/contracts/lcb1/generate.py +76 -0
  27. lumencell-0.1.0/contracts/openapi.json +4540 -0
  28. lumencell-0.1.0/docs/HANDOFF.md +211 -0
  29. lumencell-0.1.0/docs/backend-robustness-2.md +443 -0
  30. lumencell-0.1.0/docs/benchmarks.md +35 -0
  31. lumencell-0.1.0/docs/case-studies/sheih-2020.md +544 -0
  32. lumencell-0.1.0/docs/results.md +62 -0
  33. lumencell-0.1.0/docs/superpowers/HANDOFF.md +1663 -0
  34. lumencell-0.1.0/docs/superpowers/plans/2026-11-12-phase-1-clonotypes.md +915 -0
  35. lumencell-0.1.0/docs/superpowers/plans/2026-11-12-phase-2-robustness.md +714 -0
  36. lumencell-0.1.0/docs/superpowers/plans/2026-11-12-phase-3-tcell-data.md +1439 -0
  37. lumencell-0.1.0/docs/superpowers/research/2026-11-12-clonal-metrics.md +227 -0
  38. lumencell-0.1.0/docs/superpowers/research/2026-11-12-tcr-datasets.md +142 -0
  39. lumencell-0.1.0/docs/superpowers/research/2026-11-19-daniel2022-metadata.md +393 -0
  40. lumencell-0.1.0/docs/superpowers/research/2026-11-19-sheih-verification.md +62 -0
  41. lumencell-0.1.0/docs/superpowers/research/2026-11-20-daniel2022-declaration.md +195 -0
  42. lumencell-0.1.0/docs/superpowers/specs/2026-11-12-tcell-clonotypes-design.md +740 -0
  43. lumencell-0.1.0/pyproject.toml +98 -0
  44. lumencell-0.1.0/src/lumencell/__init__.py +3 -0
  45. lumencell-0.1.0/src/lumencell/api/__init__.py +1 -0
  46. lumencell-0.1.0/src/lumencell/api/app.py +49 -0
  47. lumencell-0.1.0/src/lumencell/api/binary.py +160 -0
  48. lumencell-0.1.0/src/lumencell/api/convert.py +39 -0
  49. lumencell-0.1.0/src/lumencell/api/dataset_view.py +363 -0
  50. lumencell-0.1.0/src/lumencell/api/errors.py +69 -0
  51. lumencell-0.1.0/src/lumencell/api/models.py +605 -0
  52. lumencell-0.1.0/src/lumencell/api/routes.py +362 -0
  53. lumencell-0.1.0/src/lumencell/api/runs.py +546 -0
  54. lumencell-0.1.0/src/lumencell/api/session.py +329 -0
  55. lumencell-0.1.0/src/lumencell/api/state.py +62 -0
  56. lumencell-0.1.0/src/lumencell/bench/__init__.py +1 -0
  57. lumencell-0.1.0/src/lumencell/bench/builders/__init__.py +1 -0
  58. lumencell-0.1.0/src/lumencell/bench/builders/common.py +142 -0
  59. lumencell-0.1.0/src/lumencell/bench/builders/daniel2022.py +621 -0
  60. lumencell-0.1.0/src/lumencell/bench/builders/sheih2020.py +293 -0
  61. lumencell-0.1.0/src/lumencell/bench/calibration.py +359 -0
  62. lumencell-0.1.0/src/lumencell/bench/case_study.py +516 -0
  63. lumencell-0.1.0/src/lumencell/bench/datasets.py +359 -0
  64. lumencell-0.1.0/src/lumencell/bench/download.py +216 -0
  65. lumencell-0.1.0/src/lumencell/bench/gates.py +112 -0
  66. lumencell-0.1.0/src/lumencell/bench/metrics.py +185 -0
  67. lumencell-0.1.0/src/lumencell/bench/real_clonal.py +145 -0
  68. lumencell-0.1.0/src/lumencell/bench/report.py +195 -0
  69. lumencell-0.1.0/src/lumencell/bench/runner.py +327 -0
  70. lumencell-0.1.0/src/lumencell/bench/synth.py +324 -0
  71. lumencell-0.1.0/src/lumencell/bench/synth_clones.py +194 -0
  72. lumencell-0.1.0/src/lumencell/bench/synth_controls.py +106 -0
  73. lumencell-0.1.0/src/lumencell/bench/truth.py +86 -0
  74. lumencell-0.1.0/src/lumencell/bench/verdict_calibration.py +439 -0
  75. lumencell-0.1.0/src/lumencell/cli.py +755 -0
  76. lumencell-0.1.0/src/lumencell/clonal/__init__.py +33 -0
  77. lumencell-0.1.0/src/lumencell/clonal/isolation.py +60 -0
  78. lumencell-0.1.0/src/lumencell/clonal/labels.py +99 -0
  79. lumencell-0.1.0/src/lumencell/clonal/scores.py +574 -0
  80. lumencell-0.1.0/src/lumencell/data/__init__.py +1 -0
  81. lumencell-0.1.0/src/lumencell/data/fingerprint.py +52 -0
  82. lumencell-0.1.0/src/lumencell/data/loader.py +219 -0
  83. lumencell-0.1.0/src/lumencell/engine/__init__.py +1 -0
  84. lumencell-0.1.0/src/lumencell/engine/compare.py +76 -0
  85. lumencell-0.1.0/src/lumencell/engine/context.py +150 -0
  86. lumencell-0.1.0/src/lumencell/engine/graph.py +34 -0
  87. lumencell-0.1.0/src/lumencell/engine/lineages.py +74 -0
  88. lumencell-0.1.0/src/lumencell/engine/methods/__init__.py +1 -0
  89. lumencell-0.1.0/src/lumencell/engine/methods/base.py +51 -0
  90. lumencell-0.1.0/src/lumencell/engine/methods/paga_dpt.py +244 -0
  91. lumencell-0.1.0/src/lumencell/engine/methods/palantir_adapter.py +249 -0
  92. lumencell-0.1.0/src/lumencell/engine/methods/scfates_adapter.py +334 -0
  93. lumencell-0.1.0/src/lumencell/engine/projection.py +133 -0
  94. lumencell-0.1.0/src/lumencell/engine/registry.py +70 -0
  95. lumencell-0.1.0/src/lumencell/engine/roots.py +362 -0
  96. lumencell-0.1.0/src/lumencell/engine/schema.py +250 -0
  97. lumencell-0.1.0/src/lumencell/engine/stability.py +452 -0
  98. lumencell-0.1.0/src/lumencell/engine/store.py +341 -0
  99. lumencell-0.1.0/src/lumencell/engine/topology.py +114 -0
  100. lumencell-0.1.0/src/lumencell/engine/tree_support.py +285 -0
  101. lumencell-0.1.0/src/lumencell/engine/trends.py +181 -0
  102. lumencell-0.1.0/src/lumencell/export.py +58 -0
  103. lumencell-0.1.0/src/lumencell/jobs/__init__.py +1 -0
  104. lumencell-0.1.0/src/lumencell/jobs/manager.py +409 -0
  105. lumencell-0.1.0/src/lumencell/jobs/worker.py +305 -0
  106. lumencell-0.1.0/src/lumencell/prep/__init__.py +1 -0
  107. lumencell-0.1.0/src/lumencell/prep/cache.py +339 -0
  108. lumencell-0.1.0/src/lumencell/prep/cell_cycle_data/human_mouse_orthologs.tsv +105 -0
  109. lumencell-0.1.0/src/lumencell/prep/cell_cycle_data/tirosh2016.tsv +104 -0
  110. lumencell-0.1.0/src/lumencell/prep/cell_cycle_genes.py +118 -0
  111. lumencell-0.1.0/src/lumencell/prep/housekeeping.py +246 -0
  112. lumencell-0.1.0/src/lumencell/prep/pipeline.py +44 -0
  113. lumencell-0.1.0/src/lumencell/prep/stages.py +471 -0
  114. lumencell-0.1.0/src/lumencell/py.typed +0 -0
  115. lumencell-0.1.0/src/lumencell/server.py +80 -0
  116. lumencell-0.1.0/src/lumencell/trust/__init__.py +0 -0
  117. lumencell-0.1.0/src/lumencell/trust/cell_cycle.py +91 -0
  118. lumencell-0.1.0/src/lumencell/trust/clonal.py +324 -0
  119. lumencell-0.1.0/src/lumencell/trust/constants.py +40 -0
  120. lumencell-0.1.0/src/lumencell/trust/stability.py +132 -0
  121. lumencell-0.1.0/src/lumencell/trust/verdict.py +97 -0
  122. lumencell-0.1.0/src/lumencell/web_dist/assets/array-utils-flat-BL8Cekj1.js +13 -0
  123. lumencell-0.1.0/src/lumencell/web_dist/assets/array-utils-flat-BL8Cekj1.js.map +1 -0
  124. lumencell-0.1.0/src/lumencell/web_dist/assets/expression-C4x9yiMU.js +368 -0
  125. lumencell-0.1.0/src/lumencell/web_dist/assets/expression-C4x9yiMU.js.map +1 -0
  126. lumencell-0.1.0/src/lumencell/web_dist/assets/get-attribute-from-layouts-Dd2gixpo.js +2 -0
  127. lumencell-0.1.0/src/lumencell/web_dist/assets/get-attribute-from-layouts-Dd2gixpo.js.map +1 -0
  128. lumencell-0.1.0/src/lumencell/web_dist/assets/index-BUNqjr2M.css +2 -0
  129. lumencell-0.1.0/src/lumencell/web_dist/assets/index-sUUbyycK.js +5670 -0
  130. lumencell-0.1.0/src/lumencell/web_dist/assets/index-sUUbyycK.js.map +1 -0
  131. lumencell-0.1.0/src/lumencell/web_dist/assets/webgl-Bqe1kBnB.js +345 -0
  132. lumencell-0.1.0/src/lumencell/web_dist/assets/webgl-Bqe1kBnB.js.map +1 -0
  133. lumencell-0.1.0/src/lumencell/web_dist/index.html +16 -0
  134. lumencell-0.1.0/tests/__init__.py +0 -0
  135. lumencell-0.1.0/tests/api/__init__.py +0 -0
  136. lumencell-0.1.0/tests/api/test_cache_healing.py +196 -0
  137. lumencell-0.1.0/tests/api/test_clonal_settings.py +437 -0
  138. lumencell-0.1.0/tests/api/test_clonal_trust.py +467 -0
  139. lumencell-0.1.0/tests/api/test_contract.py +98 -0
  140. lumencell-0.1.0/tests/api/test_disconnected_graph.py +44 -0
  141. lumencell-0.1.0/tests/api/test_robustness_trust.py +498 -0
  142. lumencell-0.1.0/tests/api/test_routes.py +579 -0
  143. lumencell-0.1.0/tests/api/test_server.py +180 -0
  144. lumencell-0.1.0/tests/clonal/__init__.py +0 -0
  145. lumencell-0.1.0/tests/clonal/test_calibration.py +90 -0
  146. lumencell-0.1.0/tests/clonal/test_calibration_counts.py +340 -0
  147. lumencell-0.1.0/tests/clonal/test_calibration_n2_amended.py +77 -0
  148. lumencell-0.1.0/tests/clonal/test_labels.py +85 -0
  149. lumencell-0.1.0/tests/clonal/test_n2_split.py +184 -0
  150. lumencell-0.1.0/tests/clonal/test_properties.py +281 -0
  151. lumencell-0.1.0/tests/clonal/test_scores.py +566 -0
  152. lumencell-0.1.0/tests/conftest.py +34 -0
  153. lumencell-0.1.0/tests/contracts/__init__.py +0 -0
  154. lumencell-0.1.0/tests/contracts/test_lcb1.py +178 -0
  155. lumencell-0.1.0/tests/golden/__init__.py +0 -0
  156. lumencell-0.1.0/tests/golden/test_synthetic.py +68 -0
  157. lumencell-0.1.0/tests/real/__init__.py +0 -0
  158. lumencell-0.1.0/tests/real/test_real_datasets.py +63 -0
  159. lumencell-0.1.0/tests/test_wheel.py +15 -0
  160. lumencell-0.1.0/tests/unit/__init__.py +0 -0
  161. lumencell-0.1.0/tests/unit/daniel_fixture.py +201 -0
  162. lumencell-0.1.0/tests/unit/test_barcode_join.py +134 -0
  163. lumencell-0.1.0/tests/unit/test_builders_common.py +250 -0
  164. lumencell-0.1.0/tests/unit/test_cache_admin.py +343 -0
  165. lumencell-0.1.0/tests/unit/test_case_study.py +789 -0
  166. lumencell-0.1.0/tests/unit/test_case_study_declaration.py +136 -0
  167. lumencell-0.1.0/tests/unit/test_case_study_writeup.py +196 -0
  168. lumencell-0.1.0/tests/unit/test_cell_cycle_check.py +108 -0
  169. lumencell-0.1.0/tests/unit/test_cell_cycle_genes.py +136 -0
  170. lumencell-0.1.0/tests/unit/test_cli.py +157 -0
  171. lumencell-0.1.0/tests/unit/test_clonal_agreement.py +431 -0
  172. lumencell-0.1.0/tests/unit/test_clonal_settings.py +179 -0
  173. lumencell-0.1.0/tests/unit/test_commands.py +448 -0
  174. lumencell-0.1.0/tests/unit/test_compare.py +83 -0
  175. lumencell-0.1.0/tests/unit/test_daniel2022.py +746 -0
  176. lumencell-0.1.0/tests/unit/test_daniel_inspection.py +488 -0
  177. lumencell-0.1.0/tests/unit/test_datasets.py +644 -0
  178. lumencell-0.1.0/tests/unit/test_disconnected_graph.py +121 -0
  179. lumencell-0.1.0/tests/unit/test_gates.py +285 -0
  180. lumencell-0.1.0/tests/unit/test_isolation.py +311 -0
  181. lumencell-0.1.0/tests/unit/test_jobs.py +813 -0
  182. lumencell-0.1.0/tests/unit/test_loader.py +166 -0
  183. lumencell-0.1.0/tests/unit/test_makefile.py +16 -0
  184. lumencell-0.1.0/tests/unit/test_metrics.py +158 -0
  185. lumencell-0.1.0/tests/unit/test_paga_dpt.py +97 -0
  186. lumencell-0.1.0/tests/unit/test_palantir.py +94 -0
  187. lumencell-0.1.0/tests/unit/test_prep.py +477 -0
  188. lumencell-0.1.0/tests/unit/test_prep_cache.py +353 -0
  189. lumencell-0.1.0/tests/unit/test_projection.py +39 -0
  190. lumencell-0.1.0/tests/unit/test_real_clonal.py +581 -0
  191. lumencell-0.1.0/tests/unit/test_roots.py +310 -0
  192. lumencell-0.1.0/tests/unit/test_runner_clonal.py +409 -0
  193. lumencell-0.1.0/tests/unit/test_runner_stability.py +301 -0
  194. lumencell-0.1.0/tests/unit/test_scfates.py +110 -0
  195. lumencell-0.1.0/tests/unit/test_schema.py +163 -0
  196. lumencell-0.1.0/tests/unit/test_sheih2020.py +526 -0
  197. lumencell-0.1.0/tests/unit/test_stability.py +419 -0
  198. lumencell-0.1.0/tests/unit/test_stability_trust.py +154 -0
  199. lumencell-0.1.0/tests/unit/test_store.py +393 -0
  200. lumencell-0.1.0/tests/unit/test_synth.py +127 -0
  201. lumencell-0.1.0/tests/unit/test_synth_clones.py +389 -0
  202. lumencell-0.1.0/tests/unit/test_synth_controls.py +187 -0
  203. lumencell-0.1.0/tests/unit/test_tree_support.py +348 -0
  204. lumencell-0.1.0/tests/unit/test_trends.py +230 -0
  205. lumencell-0.1.0/tests/unit/test_trust_constants.py +99 -0
  206. lumencell-0.1.0/tests/unit/test_trust_verdict.py +111 -0
  207. lumencell-0.1.0/tests/unit/test_verdict_calibration.py +424 -0
  208. lumencell-0.1.0/uv.lock +2710 -0
  209. lumencell-0.1.0/web/e2e/slice.spec.ts +78 -0
  210. lumencell-0.1.0/web/eslint.config.js +18 -0
  211. lumencell-0.1.0/web/index.html +12 -0
  212. lumencell-0.1.0/web/package-lock.json +5889 -0
  213. lumencell-0.1.0/web/package.json +59 -0
  214. lumencell-0.1.0/web/playwright.config.ts +35 -0
  215. lumencell-0.1.0/web/src/App.test.tsx +111 -0
  216. lumencell-0.1.0/web/src/App.tsx +81 -0
  217. lumencell-0.1.0/web/src/api/client.ts +105 -0
  218. lumencell-0.1.0/web/src/api/events.ts +38 -0
  219. lumencell-0.1.0/web/src/api/generated/index.ts +3 -0
  220. lumencell-0.1.0/web/src/api/generated/types.gen.ts +2517 -0
  221. lumencell-0.1.0/web/src/api/lcb1.test.ts +88 -0
  222. lumencell-0.1.0/web/src/api/lcb1.ts +143 -0
  223. lumencell-0.1.0/web/src/api/queries.ts +244 -0
  224. lumencell-0.1.0/web/src/components/GenePanel.tsx +263 -0
  225. lumencell-0.1.0/web/src/components/GeneSearch.tsx +55 -0
  226. lumencell-0.1.0/web/src/components/Header.tsx +34 -0
  227. lumencell-0.1.0/web/src/components/Legend.tsx +41 -0
  228. lumencell-0.1.0/web/src/components/Scatter.tsx +293 -0
  229. lumencell-0.1.0/web/src/components/Sidebar.tsx +164 -0
  230. lumencell-0.1.0/web/src/components/trajectory/Compare.tsx +62 -0
  231. lumencell-0.1.0/web/src/components/trajectory/LineageTree.tsx +96 -0
  232. lumencell-0.1.0/web/src/components/trajectory/PrepProgress.tsx +68 -0
  233. lumencell-0.1.0/web/src/components/trajectory/PseudotimeFilter.tsx +45 -0
  234. lumencell-0.1.0/web/src/components/trajectory/RootPicker.tsx +124 -0
  235. lumencell-0.1.0/web/src/components/trajectory/Runs.tsx +112 -0
  236. lumencell-0.1.0/web/src/components/trajectory/TrajectoryPanel.tsx +43 -0
  237. lumencell-0.1.0/web/src/components/trajectory/TrustPanel.tsx +108 -0
  238. lumencell-0.1.0/web/src/components/ui.tsx +72 -0
  239. lumencell-0.1.0/web/src/components/useCellColors.ts +162 -0
  240. lumencell-0.1.0/web/src/index.css +94 -0
  241. lumencell-0.1.0/web/src/lib/colors.ts +122 -0
  242. lumencell-0.1.0/web/src/lib/geometry.ts +72 -0
  243. lumencell-0.1.0/web/src/lib/lib.test.ts +91 -0
  244. lumencell-0.1.0/web/src/main.tsx +20 -0
  245. lumencell-0.1.0/web/src/state/ui.ts +67 -0
  246. lumencell-0.1.0/web/src/test/fixtures.ts +123 -0
  247. lumencell-0.1.0/web/src/test/setup.ts +7 -0
  248. lumencell-0.1.0/web/tsconfig.app.json +26 -0
  249. lumencell-0.1.0/web/tsconfig.json +8 -0
  250. lumencell-0.1.0/web/tsconfig.node.json +26 -0
  251. lumencell-0.1.0/web/tsconfig.test.json +9 -0
  252. lumencell-0.1.0/web/vite.config.ts +30 -0
@@ -0,0 +1,174 @@
1
+ name: CI
2
+
3
+ # The same gate as `make ci` locally: Python lint, types and tests, the API
4
+ # contract check, the web app's lint, types, tests and build, and the Playwright
5
+ # end-to-end test against the real server.
6
+ on:
7
+ pull_request:
8
+ push:
9
+ branches: [main]
10
+
11
+ concurrency:
12
+ group: ci-${{ github.ref }}
13
+ # A newer push to a pull request replaces its run; every push to main keeps its own result.
14
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ jobs:
20
+ ci:
21
+ name: make ci
22
+ runs-on: ubuntu-latest
23
+ timeout-minutes: 45
24
+ env:
25
+ UV_LOCKED: "1" # fail on a uv.lock that is out of date instead of resolving it again
26
+ steps:
27
+ - uses: actions/checkout@v7
28
+
29
+ # Python 3.13, from .python-version.
30
+ - uses: astral-sh/setup-uv@v10.3.3
31
+ with:
32
+ enable-cache: true
33
+ cache-dependency-glob: uv.lock
34
+
35
+ - uses: actions/setup-node@v7
36
+ with:
37
+ node-version: 22
38
+ cache: npm
39
+ cache-dependency-path: web/package-lock.json
40
+
41
+ - name: Install dependencies
42
+ run: make install
43
+
44
+ # Their tests skip when the import fails, which would pass CI without them.
45
+ - name: Check that the Palantir and scFates adapters can import their packages
46
+ run: uv run python -c "import palantir, scFates"
47
+
48
+ # Restore and save are separate steps because actions/cache saves only when
49
+ # the whole job succeeds, so main never got a cache. Pull requests can
50
+ # restore a cache saved on main, but main cannot restore one saved by a PR.
51
+ - name: Restore the Playwright browser cache
52
+ id: playwright-cache
53
+ uses: actions/cache/restore@v6
54
+ with:
55
+ path: ~/.cache/ms-playwright
56
+ key: playwright-${{ runner.os }}-${{ hashFiles('web/package-lock.json') }}
57
+
58
+ # From Playwright's download server; no apt involved.
59
+ - name: Install Playwright Chromium
60
+ id: chromium
61
+ if: steps.playwright-cache.outputs.cache-hit != 'true'
62
+ working-directory: web
63
+ run: npx playwright install chromium
64
+
65
+ # Saved straight after the download, so a failure later in the job still
66
+ # leaves a cache. Never after a failed download: a cache key cannot be overwritten.
67
+ - name: Save the Playwright browser cache
68
+ if: always() && steps.chromium.outcome == 'success'
69
+ uses: actions/cache/save@v6
70
+ with:
71
+ path: ~/.cache/ms-playwright
72
+ key: ${{ steps.playwright-cache.outputs.cache-primary-key }}
73
+
74
+ # Uses apt, whose Ubuntu mirrors sometimes fail to resolve on the runner. Each
75
+ # try is capped at 3 minutes (a healthy one takes under a minute) and runs as
76
+ # root, so the timeout can stop apt and release its locks before the next try.
77
+ - name: Install Playwright's system libraries
78
+ working-directory: web
79
+ timeout-minutes: 15
80
+ run: |
81
+ for try in 1 2 3; do
82
+ status=0
83
+ sudo env "PATH=$PATH" timeout --kill-after=30s 3m npx playwright install-deps chromium || status=$?
84
+ if [ "$status" -eq 0 ]; then
85
+ exit 0
86
+ fi
87
+ if [ "$try" -lt 3 ]; then
88
+ echo "::warning::Installing Playwright's system libraries failed (try $try of 3, exit $status). Retrying in $((try * 30)) s."
89
+ sleep $((try * 30))
90
+ fi
91
+ done
92
+ echo "::error::Could not install Playwright's system libraries after 3 tries (last exit $status; 124 or 137 means it hit the 3-minute limit). apt could not reach Ubuntu's mirrors; see the log above."
93
+ exit 1
94
+
95
+ # typer forces rich's terminal styling when GITHUB_ACTIONS is set, which splits
96
+ # option names in CLI errors with colour codes; the CLI tests read plain text,
97
+ # as on a developer's machine. Nothing in `make ci` needs the variable.
98
+ - name: make ci
99
+ run: env -u GITHUB_ACTIONS make ci
100
+
101
+ - name: Keep the Playwright traces of a failed run
102
+ if: failure()
103
+ uses: actions/upload-artifact@v7
104
+ with:
105
+ name: playwright-results
106
+ path: web/test-results/
107
+ if-no-files-found: ignore
108
+
109
+ # The wheel is what users install: build it with the web app, then run it with
110
+ # no Node and none of the dev tools, and check that it serves the app and the API.
111
+ wheel:
112
+ name: build the wheel
113
+ runs-on: ubuntu-latest
114
+ timeout-minutes: 20
115
+ env:
116
+ UV_LOCKED: "1"
117
+ steps:
118
+ - uses: actions/checkout@v7
119
+ - uses: astral-sh/setup-uv@v10.3.3
120
+ with:
121
+ enable-cache: true
122
+ cache-dependency-glob: uv.lock
123
+ - uses: actions/setup-node@v7
124
+ with:
125
+ node-version: 22
126
+ cache: npm
127
+ cache-dependency-path: web/package-lock.json
128
+ - run: cd web && npm ci
129
+ - run: make web-dist
130
+ - run: uv build
131
+ - run: uv run pytest tests/test_wheel.py
132
+ - uses: actions/upload-artifact@v7
133
+ with:
134
+ name: dist
135
+ path: dist/
136
+ if-no-files-found: error
137
+
138
+ wheel-demo:
139
+ name: run the wheel without Node
140
+ needs: wheel
141
+ runs-on: ubuntu-latest
142
+ timeout-minutes: 20
143
+ container: python:3.13-slim
144
+ steps:
145
+ - uses: actions/download-artifact@v8
146
+ with:
147
+ name: dist
148
+ path: dist/
149
+ - run: pip install dist/*.whl
150
+ - name: Start the demo and wait for the app and the API
151
+ run: |
152
+ lumencell demo --no-browser --port 8799 > demo.log 2>&1 &
153
+ pid=$!
154
+ for i in $(seq 60); do
155
+ if python - <<'PY'
156
+ import sys, urllib.request
157
+ get = lambda p: urllib.request.urlopen("http://127.0.0.1:8799" + p, timeout=5).read().decode()
158
+ try:
159
+ ok = '<div id="root">' in get("/") and "n_obs" in get("/api/v1/dataset")
160
+ except OSError:
161
+ ok = False
162
+ sys.exit(0 if ok else 1)
163
+ PY
164
+ then
165
+ kill $pid
166
+ echo "demo served the app and the API"
167
+ exit 0
168
+ fi
169
+ sleep 5
170
+ done
171
+ cat demo.log
172
+ kill $pid
173
+ echo "::error::the demo did not serve the app and the API within 5 minutes"
174
+ exit 1
@@ -0,0 +1,53 @@
1
+ name: Publish
2
+
3
+ # Push a tag like v0.1.0 to publish that version to PyPI (trusted publishing, no tokens).
4
+ on:
5
+ push:
6
+ tags: ["v*"]
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ build:
13
+ runs-on: ubuntu-latest
14
+ timeout-minutes: 20
15
+ env:
16
+ UV_LOCKED: "1"
17
+ steps:
18
+ - uses: actions/checkout@v7
19
+ - uses: astral-sh/setup-uv@v10.3.3
20
+ - uses: actions/setup-node@v7
21
+ with:
22
+ node-version: 22
23
+ cache: npm
24
+ cache-dependency-path: web/package-lock.json
25
+ - name: Check that the tag matches the package version
26
+ run: |
27
+ version=$(uv run python -c "import lumencell; print(lumencell.__version__)")
28
+ if [ "v$version" != "$GITHUB_REF_NAME" ]; then
29
+ echo "::error::tag $GITHUB_REF_NAME does not match lumencell.__version__ $version"
30
+ exit 1
31
+ fi
32
+ - run: cd web && npm ci
33
+ - run: make web-dist
34
+ - run: uv build
35
+ - run: uv run pytest tests/test_wheel.py
36
+ - uses: actions/upload-artifact@v7
37
+ with:
38
+ name: dist
39
+ path: dist/
40
+ if-no-files-found: error
41
+
42
+ publish:
43
+ needs: build
44
+ runs-on: ubuntu-latest
45
+ environment: pypi
46
+ permissions:
47
+ id-token: write
48
+ steps:
49
+ - uses: actions/download-artifact@v8
50
+ with:
51
+ name: dist
52
+ path: dist/
53
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,32 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ .venv/
5
+ .pytest_cache/
6
+ .mypy_cache/
7
+ .ruff_cache/
8
+ .hypothesis/
9
+ dist/
10
+ build/
11
+ *.egg-info/
12
+
13
+ # Web
14
+ web/node_modules/
15
+ web/dist/
16
+ web/coverage/
17
+ web/test-results/
18
+ web/playwright-report/
19
+ src/lumencell/web_dist/
20
+
21
+ # Data and local caches
22
+ *.h5ad
23
+ !tests/fixtures/*.h5ad
24
+ .lumencell/
25
+
26
+ # OS / editors
27
+ .DS_Store
28
+ .idea/
29
+ .vscode/
30
+
31
+ # Local tooling
32
+ .claude/
@@ -0,0 +1 @@
1
+ 3.13
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 shreyandhawa
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,103 @@
1
+ .PHONY: install py-install web-install py-lint py-typecheck py-test py-ci web-lint web-typecheck web-test web-build web-ci web-e2e ci fmt dev-web web-dist dev-server contract contract-check py-test-all bench-synth bench-baseline bench-real
2
+
3
+ install: py-install web-install
4
+
5
+ py-install:
6
+ uv sync --all-extras
7
+
8
+ web-install:
9
+ cd web && npm ci
10
+
11
+ # ---- Python ---------------------------------------------------------------
12
+
13
+ py-lint:
14
+ uv run ruff check .
15
+ uv run ruff format --check .
16
+
17
+ py-typecheck:
18
+ uv run mypy
19
+
20
+ py-test:
21
+ uv run pytest -m "not real_data and not slow"
22
+
23
+ # Everything that runs offline, including slow calibration and benchmark tests.
24
+ py-test-all:
25
+ uv run pytest -m "not real_data"
26
+
27
+ py-ci: py-lint py-typecheck py-test
28
+
29
+ # ---- Web ------------------------------------------------------------------
30
+
31
+ web-lint:
32
+ cd web && npm run -s lint
33
+
34
+ web-typecheck:
35
+ cd web && npm run -s typecheck
36
+
37
+ web-test:
38
+ cd web && npm run -s test
39
+
40
+ web-build:
41
+ cd web && npm run -s build
42
+
43
+ web-ci: web-lint web-typecheck web-test web-build
44
+
45
+ # End to end: the real server serving the built app, driven by Playwright (Chromium).
46
+ web-e2e: web-build
47
+ cd web && npx playwright test
48
+
49
+ # ---- API contract ---------------------------------------------------------
50
+ # contracts/openapi.json is generated from api/models.py, and the TypeScript
51
+ # types are generated from it. `contract` regenerates both; `contract-check`
52
+ # fails if either committed file is stale.
53
+
54
+ contract:
55
+ uv run python -m lumencell.api.app contracts/openapi.json
56
+ cd web && npm run -s gen:api
57
+
58
+ contract-check:
59
+ @tmp=$$(mktemp -d); \
60
+ uv run python -m lumencell.api.app $$tmp/openapi.json > /dev/null && \
61
+ diff -u contracts/openapi.json $$tmp/openapi.json > /dev/null || { echo "contracts/openapi.json is stale: run make contract"; exit 1; }; \
62
+ (cd web && npx openapi-ts -i ../contracts/openapi.json -o $$tmp/generated -p @hey-api/typescript --no-log-file -s) && \
63
+ diff -ru web/src/api/generated $$tmp/generated > /dev/null || { echo "web/src/api/generated is stale: run make contract"; exit 1; }; \
64
+ rm -rf $$tmp; echo "API contract is up to date"
65
+
66
+ # ---- Benchmarks -----------------------------------------------------------
67
+
68
+ BENCH_METHODS ?= paga_dpt,palantir,scfates_ppt
69
+
70
+ # Full synthetic matrix: reports gates, fails on regressions against the baseline.
71
+ bench-synth:
72
+ uv run lumencell bench synth --methods $(BENCH_METHODS)
73
+
74
+ # Re-measure and replace benchmarks/baseline.json (commit the result deliberately).
75
+ bench-baseline:
76
+ uv run lumencell bench synth --methods $(BENCH_METHODS) --write-baseline
77
+
78
+ # Real datasets (download first: uv run lumencell bench fetch all). A release gate, not CI.
79
+ bench-real:
80
+ uv run pytest -m real_data -q
81
+ uv run lumencell bench real
82
+
83
+ # ---- Everything -----------------------------------------------------------
84
+
85
+ # web-dist first: tests/test_wheel.py needs the built app.
86
+ ci: web-dist py-ci contract-check web-ci web-e2e
87
+
88
+ fmt:
89
+ uv run ruff format .
90
+ uv run ruff check --fix .
91
+
92
+ dev-web:
93
+ cd web && npm run dev
94
+
95
+ # Build the web app and bundle it into the Python package, so `lumencell launch` serves it.
96
+ web-dist: web-build
97
+ rm -rf src/lumencell/web_dist
98
+ cp -R web/dist src/lumencell/web_dist
99
+
100
+ # Run the server on a synthetic dataset for development (web: make dev-web in another shell).
101
+ dev-server:
102
+ uv run lumencell synth .lumencell/dev.h5ad --store-root
103
+ uv run lumencell launch .lumencell/dev.h5ad --no-browser
@@ -0,0 +1,110 @@
1
+ Metadata-Version: 2.5
2
+ Name: lumencell
3
+ Version: 0.1.0
4
+ Summary: Interactive explorer for single-cell pseudotime and lineage trajectories.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Classifier: Intended Audience :: Science/Research
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
10
+ Requires-Python: >=3.12
11
+ Requires-Dist: anndata>=0.12
12
+ Requires-Dist: certifi>=2024.2
13
+ Requires-Dist: fastapi>=0.115
14
+ Requires-Dist: igraph>=0.11
15
+ Requires-Dist: numpy>=2.0
16
+ Requires-Dist: pandas>=2.2
17
+ Requires-Dist: platformdirs>=4.3
18
+ Requires-Dist: pydantic>=2.9
19
+ Requires-Dist: scanpy<1.13,>=1.12
20
+ Requires-Dist: scikit-misc>=0.5
21
+ Requires-Dist: scipy>=1.13
22
+ Requires-Dist: typer>=0.15
23
+ Requires-Dist: uvicorn>=0.30
24
+ Provides-Extra: all
25
+ Requires-Dist: palantir<1.5,>=1.4; extra == 'all'
26
+ Requires-Dist: scfates<1.3,>=1.2; extra == 'all'
27
+ Provides-Extra: palantir
28
+ Requires-Dist: palantir<1.5,>=1.4; extra == 'palantir'
29
+ Provides-Extra: scfates
30
+ Requires-Dist: scfates<1.3,>=1.2; extra == 'scfates'
31
+ Description-Content-Type: text/markdown
32
+
33
+ # lumenCell
34
+
35
+ Interactive explorer for pseudotime and lineage trajectories in single-cell RNA-seq data.
36
+
37
+ `lumencell launch data.h5ad` prepares the data in the background, asks where the
38
+ trajectory starts, runs a trajectory method, and lets you inspect lineages, gene
39
+ trends along pseudotime and how far to trust the result, in the browser.
40
+
41
+ Results so far: [docs/results.md](docs/results.md)
42
+
43
+ > Early development (M1). Usable on real data, but every method is still labelled
44
+ > experimental: see the benchmark below.
45
+
46
+ ## Principles
47
+
48
+ - **The root is never guessed.** Pseudotime is measured from a start you choose
49
+ (`--root cluster:<column>=<value>`, a cell, or a root stored in the file).
50
+ Suggestions come with their evidence and are never applied for you.
51
+ - **Inference runs in PCA / diffusion space, never on the UMAP.** Curves drawn on a
52
+ 2-D embedding are projections, labelled as such, with a fidelity check.
53
+ - **Accuracy is measured, not assumed.** Every method is benchmarked against known
54
+ trajectories, and a method that misses any gate is marked experimental in the app.
55
+ - **Your file is never modified.** Results live in a cache; `lumencell export`
56
+ writes them into a copy.
57
+
58
+ ## Quick start
59
+
60
+ ```bash
61
+ pip install lumencell
62
+ lumencell demo
63
+ ```
64
+
65
+ `lumencell demo` opens a small synthetic dataset with a stored root. For your own data:
66
+
67
+ ```bash
68
+ lumencell launch your-data.h5ad --root "cluster:clusters=Ductal"
69
+ ```
70
+
71
+ `X` (or `layers["counts"]` / `.raw`) should hold raw counts, or log-normalised values.
72
+
73
+ Other commands: `lumencell prepare` (precompute), `lumencell roots` (suggestions),
74
+ `lumencell run` (run from the terminal; add `--clone-key` with `--donor-key` or `--single-donor`,
75
+ and optionally `--strata`, to score the run against clone labels), `lumencell export` (write results into a
76
+ copy of the file), `lumencell synth` (synthetic data with a known trajectory; `--fate-bias` adds
77
+ clone and donor columns).
78
+
79
+ ## Methods
80
+
81
+ | Method | Install | What it is |
82
+ |---|---|---|
83
+ | PAGA + DPT | core | Diffusion pseudotime with lineages along the PAGA cluster tree (scanpy) |
84
+ | Palantir | `[palantir]` | Waypoint pseudotime and fate probabilities from a Markov chain (Setty et al. 2019) |
85
+ | scFates | `[scfates]` | A principal tree fitted in diffusion space; the drawn curve is the fitted tree |
86
+
87
+ The `palantir` and `scfates` extras pull in GPL-licensed dependencies (mellon,
88
+ elpigraph); lumenCell itself is MIT and only imports them.
89
+
90
+ ## Benchmark
91
+
92
+ Synthetic data (Splatter-style counts from a known tree, no embedding given) runs
93
+ in CI; real datasets are a release gate (`lumencell bench fetch all`, then
94
+ `make bench-real`). Gates and every change to them are in
95
+ [`benchmarks/thresholds.toml`](benchmarks/thresholds.toml).
96
+
97
+ Full tables: [docs/benchmarks.md](docs/benchmarks.md).
98
+
99
+ ## Development
100
+
101
+ Picking the project up? Start with [`docs/HANDOFF.md`](docs/HANDOFF.md): state, decisions, open work.
102
+
103
+ From a clone, with Python 3.13, [uv](https://docs.astral.sh/uv/) and Node 22+:
104
+
105
+ ```bash
106
+ make install # uv sync --all-extras + npm ci (the palantir/scfates extras are optional)
107
+ make web-dist # build the web app into the package
108
+ make ci # lint, types, tests, API contract check, web build, end-to-end test
109
+ make dev-server # API on :8765 with a synthetic dataset; then `make dev-web` for the app on :5173
110
+ ```
@@ -0,0 +1,78 @@
1
+ # lumenCell
2
+
3
+ Interactive explorer for pseudotime and lineage trajectories in single-cell RNA-seq data.
4
+
5
+ `lumencell launch data.h5ad` prepares the data in the background, asks where the
6
+ trajectory starts, runs a trajectory method, and lets you inspect lineages, gene
7
+ trends along pseudotime and how far to trust the result, in the browser.
8
+
9
+ Results so far: [docs/results.md](docs/results.md)
10
+
11
+ > Early development (M1). Usable on real data, but every method is still labelled
12
+ > experimental: see the benchmark below.
13
+
14
+ ## Principles
15
+
16
+ - **The root is never guessed.** Pseudotime is measured from a start you choose
17
+ (`--root cluster:<column>=<value>`, a cell, or a root stored in the file).
18
+ Suggestions come with their evidence and are never applied for you.
19
+ - **Inference runs in PCA / diffusion space, never on the UMAP.** Curves drawn on a
20
+ 2-D embedding are projections, labelled as such, with a fidelity check.
21
+ - **Accuracy is measured, not assumed.** Every method is benchmarked against known
22
+ trajectories, and a method that misses any gate is marked experimental in the app.
23
+ - **Your file is never modified.** Results live in a cache; `lumencell export`
24
+ writes them into a copy.
25
+
26
+ ## Quick start
27
+
28
+ ```bash
29
+ pip install lumencell
30
+ lumencell demo
31
+ ```
32
+
33
+ `lumencell demo` opens a small synthetic dataset with a stored root. For your own data:
34
+
35
+ ```bash
36
+ lumencell launch your-data.h5ad --root "cluster:clusters=Ductal"
37
+ ```
38
+
39
+ `X` (or `layers["counts"]` / `.raw`) should hold raw counts, or log-normalised values.
40
+
41
+ Other commands: `lumencell prepare` (precompute), `lumencell roots` (suggestions),
42
+ `lumencell run` (run from the terminal; add `--clone-key` with `--donor-key` or `--single-donor`,
43
+ and optionally `--strata`, to score the run against clone labels), `lumencell export` (write results into a
44
+ copy of the file), `lumencell synth` (synthetic data with a known trajectory; `--fate-bias` adds
45
+ clone and donor columns).
46
+
47
+ ## Methods
48
+
49
+ | Method | Install | What it is |
50
+ |---|---|---|
51
+ | PAGA + DPT | core | Diffusion pseudotime with lineages along the PAGA cluster tree (scanpy) |
52
+ | Palantir | `[palantir]` | Waypoint pseudotime and fate probabilities from a Markov chain (Setty et al. 2019) |
53
+ | scFates | `[scfates]` | A principal tree fitted in diffusion space; the drawn curve is the fitted tree |
54
+
55
+ The `palantir` and `scfates` extras pull in GPL-licensed dependencies (mellon,
56
+ elpigraph); lumenCell itself is MIT and only imports them.
57
+
58
+ ## Benchmark
59
+
60
+ Synthetic data (Splatter-style counts from a known tree, no embedding given) runs
61
+ in CI; real datasets are a release gate (`lumencell bench fetch all`, then
62
+ `make bench-real`). Gates and every change to them are in
63
+ [`benchmarks/thresholds.toml`](benchmarks/thresholds.toml).
64
+
65
+ Full tables: [docs/benchmarks.md](docs/benchmarks.md).
66
+
67
+ ## Development
68
+
69
+ Picking the project up? Start with [`docs/HANDOFF.md`](docs/HANDOFF.md): state, decisions, open work.
70
+
71
+ From a clone, with Python 3.13, [uv](https://docs.astral.sh/uv/) and Node 22+:
72
+
73
+ ```bash
74
+ make install # uv sync --all-extras + npm ci (the palantir/scfates extras are optional)
75
+ make web-dist # build the web app into the package
76
+ make ci # lint, types, tests, API contract check, web build, end-to-end test
77
+ make dev-server # API on :8765 with a synthetic dataset; then `make dev-web` for the app on :5173
78
+ ```