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.
- lumencell-0.1.0/.github/workflows/ci.yml +174 -0
- lumencell-0.1.0/.github/workflows/publish.yml +53 -0
- lumencell-0.1.0/.gitignore +32 -0
- lumencell-0.1.0/.python-version +1 -0
- lumencell-0.1.0/LICENSE +21 -0
- lumencell-0.1.0/Makefile +103 -0
- lumencell-0.1.0/PKG-INFO +110 -0
- lumencell-0.1.0/README.md +78 -0
- lumencell-0.1.0/benchmarks/baseline.json +1020 -0
- lumencell-0.1.0/benchmarks/case_studies/results/sheih2020-2026-11-20.json +5989 -0
- lumencell-0.1.0/benchmarks/case_studies/sheih2020.py +55 -0
- lumencell-0.1.0/benchmarks/inspection/barcode_join.py +71 -0
- lumencell-0.1.0/benchmarks/inspection/daniel2022_formats.py +235 -0
- lumencell-0.1.0/benchmarks/inspection/daniel2022_metadata.py +118 -0
- lumencell-0.1.0/benchmarks/results/clonal-calibration-2026-11-13.json +1754 -0
- lumencell-0.1.0/benchmarks/results/clonal-calibration-n2-amended-2026-11-17.json +1769 -0
- lumencell-0.1.0/benchmarks/results/real-2026-11-10.json +156 -0
- lumencell-0.1.0/benchmarks/results/real-2026-11-13.json +264 -0
- lumencell-0.1.0/benchmarks/results/real-2026-11-17.json +318 -0
- lumencell-0.1.0/benchmarks/results/real-2026-11-20.json +444 -0
- lumencell-0.1.0/benchmarks/results/verdict-calibration-2026-11-17.json +1932 -0
- lumencell-0.1.0/benchmarks/results/verdict-verification-2026-11-17.json +2257 -0
- lumencell-0.1.0/benchmarks/thresholds.toml +522 -0
- lumencell-0.1.0/contracts/lcb1/fixture.json +129 -0
- lumencell-0.1.0/contracts/lcb1/fixture.lcb +0 -0
- lumencell-0.1.0/contracts/lcb1/generate.py +76 -0
- lumencell-0.1.0/contracts/openapi.json +4540 -0
- lumencell-0.1.0/docs/HANDOFF.md +211 -0
- lumencell-0.1.0/docs/backend-robustness-2.md +443 -0
- lumencell-0.1.0/docs/benchmarks.md +35 -0
- lumencell-0.1.0/docs/case-studies/sheih-2020.md +544 -0
- lumencell-0.1.0/docs/results.md +62 -0
- lumencell-0.1.0/docs/superpowers/HANDOFF.md +1663 -0
- lumencell-0.1.0/docs/superpowers/plans/2026-11-12-phase-1-clonotypes.md +915 -0
- lumencell-0.1.0/docs/superpowers/plans/2026-11-12-phase-2-robustness.md +714 -0
- lumencell-0.1.0/docs/superpowers/plans/2026-11-12-phase-3-tcell-data.md +1439 -0
- lumencell-0.1.0/docs/superpowers/research/2026-11-12-clonal-metrics.md +227 -0
- lumencell-0.1.0/docs/superpowers/research/2026-11-12-tcr-datasets.md +142 -0
- lumencell-0.1.0/docs/superpowers/research/2026-11-19-daniel2022-metadata.md +393 -0
- lumencell-0.1.0/docs/superpowers/research/2026-11-19-sheih-verification.md +62 -0
- lumencell-0.1.0/docs/superpowers/research/2026-11-20-daniel2022-declaration.md +195 -0
- lumencell-0.1.0/docs/superpowers/specs/2026-11-12-tcell-clonotypes-design.md +740 -0
- lumencell-0.1.0/pyproject.toml +98 -0
- lumencell-0.1.0/src/lumencell/__init__.py +3 -0
- lumencell-0.1.0/src/lumencell/api/__init__.py +1 -0
- lumencell-0.1.0/src/lumencell/api/app.py +49 -0
- lumencell-0.1.0/src/lumencell/api/binary.py +160 -0
- lumencell-0.1.0/src/lumencell/api/convert.py +39 -0
- lumencell-0.1.0/src/lumencell/api/dataset_view.py +363 -0
- lumencell-0.1.0/src/lumencell/api/errors.py +69 -0
- lumencell-0.1.0/src/lumencell/api/models.py +605 -0
- lumencell-0.1.0/src/lumencell/api/routes.py +362 -0
- lumencell-0.1.0/src/lumencell/api/runs.py +546 -0
- lumencell-0.1.0/src/lumencell/api/session.py +329 -0
- lumencell-0.1.0/src/lumencell/api/state.py +62 -0
- lumencell-0.1.0/src/lumencell/bench/__init__.py +1 -0
- lumencell-0.1.0/src/lumencell/bench/builders/__init__.py +1 -0
- lumencell-0.1.0/src/lumencell/bench/builders/common.py +142 -0
- lumencell-0.1.0/src/lumencell/bench/builders/daniel2022.py +621 -0
- lumencell-0.1.0/src/lumencell/bench/builders/sheih2020.py +293 -0
- lumencell-0.1.0/src/lumencell/bench/calibration.py +359 -0
- lumencell-0.1.0/src/lumencell/bench/case_study.py +516 -0
- lumencell-0.1.0/src/lumencell/bench/datasets.py +359 -0
- lumencell-0.1.0/src/lumencell/bench/download.py +216 -0
- lumencell-0.1.0/src/lumencell/bench/gates.py +112 -0
- lumencell-0.1.0/src/lumencell/bench/metrics.py +185 -0
- lumencell-0.1.0/src/lumencell/bench/real_clonal.py +145 -0
- lumencell-0.1.0/src/lumencell/bench/report.py +195 -0
- lumencell-0.1.0/src/lumencell/bench/runner.py +327 -0
- lumencell-0.1.0/src/lumencell/bench/synth.py +324 -0
- lumencell-0.1.0/src/lumencell/bench/synth_clones.py +194 -0
- lumencell-0.1.0/src/lumencell/bench/synth_controls.py +106 -0
- lumencell-0.1.0/src/lumencell/bench/truth.py +86 -0
- lumencell-0.1.0/src/lumencell/bench/verdict_calibration.py +439 -0
- lumencell-0.1.0/src/lumencell/cli.py +755 -0
- lumencell-0.1.0/src/lumencell/clonal/__init__.py +33 -0
- lumencell-0.1.0/src/lumencell/clonal/isolation.py +60 -0
- lumencell-0.1.0/src/lumencell/clonal/labels.py +99 -0
- lumencell-0.1.0/src/lumencell/clonal/scores.py +574 -0
- lumencell-0.1.0/src/lumencell/data/__init__.py +1 -0
- lumencell-0.1.0/src/lumencell/data/fingerprint.py +52 -0
- lumencell-0.1.0/src/lumencell/data/loader.py +219 -0
- lumencell-0.1.0/src/lumencell/engine/__init__.py +1 -0
- lumencell-0.1.0/src/lumencell/engine/compare.py +76 -0
- lumencell-0.1.0/src/lumencell/engine/context.py +150 -0
- lumencell-0.1.0/src/lumencell/engine/graph.py +34 -0
- lumencell-0.1.0/src/lumencell/engine/lineages.py +74 -0
- lumencell-0.1.0/src/lumencell/engine/methods/__init__.py +1 -0
- lumencell-0.1.0/src/lumencell/engine/methods/base.py +51 -0
- lumencell-0.1.0/src/lumencell/engine/methods/paga_dpt.py +244 -0
- lumencell-0.1.0/src/lumencell/engine/methods/palantir_adapter.py +249 -0
- lumencell-0.1.0/src/lumencell/engine/methods/scfates_adapter.py +334 -0
- lumencell-0.1.0/src/lumencell/engine/projection.py +133 -0
- lumencell-0.1.0/src/lumencell/engine/registry.py +70 -0
- lumencell-0.1.0/src/lumencell/engine/roots.py +362 -0
- lumencell-0.1.0/src/lumencell/engine/schema.py +250 -0
- lumencell-0.1.0/src/lumencell/engine/stability.py +452 -0
- lumencell-0.1.0/src/lumencell/engine/store.py +341 -0
- lumencell-0.1.0/src/lumencell/engine/topology.py +114 -0
- lumencell-0.1.0/src/lumencell/engine/tree_support.py +285 -0
- lumencell-0.1.0/src/lumencell/engine/trends.py +181 -0
- lumencell-0.1.0/src/lumencell/export.py +58 -0
- lumencell-0.1.0/src/lumencell/jobs/__init__.py +1 -0
- lumencell-0.1.0/src/lumencell/jobs/manager.py +409 -0
- lumencell-0.1.0/src/lumencell/jobs/worker.py +305 -0
- lumencell-0.1.0/src/lumencell/prep/__init__.py +1 -0
- lumencell-0.1.0/src/lumencell/prep/cache.py +339 -0
- lumencell-0.1.0/src/lumencell/prep/cell_cycle_data/human_mouse_orthologs.tsv +105 -0
- lumencell-0.1.0/src/lumencell/prep/cell_cycle_data/tirosh2016.tsv +104 -0
- lumencell-0.1.0/src/lumencell/prep/cell_cycle_genes.py +118 -0
- lumencell-0.1.0/src/lumencell/prep/housekeeping.py +246 -0
- lumencell-0.1.0/src/lumencell/prep/pipeline.py +44 -0
- lumencell-0.1.0/src/lumencell/prep/stages.py +471 -0
- lumencell-0.1.0/src/lumencell/py.typed +0 -0
- lumencell-0.1.0/src/lumencell/server.py +80 -0
- lumencell-0.1.0/src/lumencell/trust/__init__.py +0 -0
- lumencell-0.1.0/src/lumencell/trust/cell_cycle.py +91 -0
- lumencell-0.1.0/src/lumencell/trust/clonal.py +324 -0
- lumencell-0.1.0/src/lumencell/trust/constants.py +40 -0
- lumencell-0.1.0/src/lumencell/trust/stability.py +132 -0
- lumencell-0.1.0/src/lumencell/trust/verdict.py +97 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/array-utils-flat-BL8Cekj1.js +13 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/array-utils-flat-BL8Cekj1.js.map +1 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/expression-C4x9yiMU.js +368 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/expression-C4x9yiMU.js.map +1 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/get-attribute-from-layouts-Dd2gixpo.js +2 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/get-attribute-from-layouts-Dd2gixpo.js.map +1 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/index-BUNqjr2M.css +2 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/index-sUUbyycK.js +5670 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/index-sUUbyycK.js.map +1 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/webgl-Bqe1kBnB.js +345 -0
- lumencell-0.1.0/src/lumencell/web_dist/assets/webgl-Bqe1kBnB.js.map +1 -0
- lumencell-0.1.0/src/lumencell/web_dist/index.html +16 -0
- lumencell-0.1.0/tests/__init__.py +0 -0
- lumencell-0.1.0/tests/api/__init__.py +0 -0
- lumencell-0.1.0/tests/api/test_cache_healing.py +196 -0
- lumencell-0.1.0/tests/api/test_clonal_settings.py +437 -0
- lumencell-0.1.0/tests/api/test_clonal_trust.py +467 -0
- lumencell-0.1.0/tests/api/test_contract.py +98 -0
- lumencell-0.1.0/tests/api/test_disconnected_graph.py +44 -0
- lumencell-0.1.0/tests/api/test_robustness_trust.py +498 -0
- lumencell-0.1.0/tests/api/test_routes.py +579 -0
- lumencell-0.1.0/tests/api/test_server.py +180 -0
- lumencell-0.1.0/tests/clonal/__init__.py +0 -0
- lumencell-0.1.0/tests/clonal/test_calibration.py +90 -0
- lumencell-0.1.0/tests/clonal/test_calibration_counts.py +340 -0
- lumencell-0.1.0/tests/clonal/test_calibration_n2_amended.py +77 -0
- lumencell-0.1.0/tests/clonal/test_labels.py +85 -0
- lumencell-0.1.0/tests/clonal/test_n2_split.py +184 -0
- lumencell-0.1.0/tests/clonal/test_properties.py +281 -0
- lumencell-0.1.0/tests/clonal/test_scores.py +566 -0
- lumencell-0.1.0/tests/conftest.py +34 -0
- lumencell-0.1.0/tests/contracts/__init__.py +0 -0
- lumencell-0.1.0/tests/contracts/test_lcb1.py +178 -0
- lumencell-0.1.0/tests/golden/__init__.py +0 -0
- lumencell-0.1.0/tests/golden/test_synthetic.py +68 -0
- lumencell-0.1.0/tests/real/__init__.py +0 -0
- lumencell-0.1.0/tests/real/test_real_datasets.py +63 -0
- lumencell-0.1.0/tests/test_wheel.py +15 -0
- lumencell-0.1.0/tests/unit/__init__.py +0 -0
- lumencell-0.1.0/tests/unit/daniel_fixture.py +201 -0
- lumencell-0.1.0/tests/unit/test_barcode_join.py +134 -0
- lumencell-0.1.0/tests/unit/test_builders_common.py +250 -0
- lumencell-0.1.0/tests/unit/test_cache_admin.py +343 -0
- lumencell-0.1.0/tests/unit/test_case_study.py +789 -0
- lumencell-0.1.0/tests/unit/test_case_study_declaration.py +136 -0
- lumencell-0.1.0/tests/unit/test_case_study_writeup.py +196 -0
- lumencell-0.1.0/tests/unit/test_cell_cycle_check.py +108 -0
- lumencell-0.1.0/tests/unit/test_cell_cycle_genes.py +136 -0
- lumencell-0.1.0/tests/unit/test_cli.py +157 -0
- lumencell-0.1.0/tests/unit/test_clonal_agreement.py +431 -0
- lumencell-0.1.0/tests/unit/test_clonal_settings.py +179 -0
- lumencell-0.1.0/tests/unit/test_commands.py +448 -0
- lumencell-0.1.0/tests/unit/test_compare.py +83 -0
- lumencell-0.1.0/tests/unit/test_daniel2022.py +746 -0
- lumencell-0.1.0/tests/unit/test_daniel_inspection.py +488 -0
- lumencell-0.1.0/tests/unit/test_datasets.py +644 -0
- lumencell-0.1.0/tests/unit/test_disconnected_graph.py +121 -0
- lumencell-0.1.0/tests/unit/test_gates.py +285 -0
- lumencell-0.1.0/tests/unit/test_isolation.py +311 -0
- lumencell-0.1.0/tests/unit/test_jobs.py +813 -0
- lumencell-0.1.0/tests/unit/test_loader.py +166 -0
- lumencell-0.1.0/tests/unit/test_makefile.py +16 -0
- lumencell-0.1.0/tests/unit/test_metrics.py +158 -0
- lumencell-0.1.0/tests/unit/test_paga_dpt.py +97 -0
- lumencell-0.1.0/tests/unit/test_palantir.py +94 -0
- lumencell-0.1.0/tests/unit/test_prep.py +477 -0
- lumencell-0.1.0/tests/unit/test_prep_cache.py +353 -0
- lumencell-0.1.0/tests/unit/test_projection.py +39 -0
- lumencell-0.1.0/tests/unit/test_real_clonal.py +581 -0
- lumencell-0.1.0/tests/unit/test_roots.py +310 -0
- lumencell-0.1.0/tests/unit/test_runner_clonal.py +409 -0
- lumencell-0.1.0/tests/unit/test_runner_stability.py +301 -0
- lumencell-0.1.0/tests/unit/test_scfates.py +110 -0
- lumencell-0.1.0/tests/unit/test_schema.py +163 -0
- lumencell-0.1.0/tests/unit/test_sheih2020.py +526 -0
- lumencell-0.1.0/tests/unit/test_stability.py +419 -0
- lumencell-0.1.0/tests/unit/test_stability_trust.py +154 -0
- lumencell-0.1.0/tests/unit/test_store.py +393 -0
- lumencell-0.1.0/tests/unit/test_synth.py +127 -0
- lumencell-0.1.0/tests/unit/test_synth_clones.py +389 -0
- lumencell-0.1.0/tests/unit/test_synth_controls.py +187 -0
- lumencell-0.1.0/tests/unit/test_tree_support.py +348 -0
- lumencell-0.1.0/tests/unit/test_trends.py +230 -0
- lumencell-0.1.0/tests/unit/test_trust_constants.py +99 -0
- lumencell-0.1.0/tests/unit/test_trust_verdict.py +111 -0
- lumencell-0.1.0/tests/unit/test_verdict_calibration.py +424 -0
- lumencell-0.1.0/uv.lock +2710 -0
- lumencell-0.1.0/web/e2e/slice.spec.ts +78 -0
- lumencell-0.1.0/web/eslint.config.js +18 -0
- lumencell-0.1.0/web/index.html +12 -0
- lumencell-0.1.0/web/package-lock.json +5889 -0
- lumencell-0.1.0/web/package.json +59 -0
- lumencell-0.1.0/web/playwright.config.ts +35 -0
- lumencell-0.1.0/web/src/App.test.tsx +111 -0
- lumencell-0.1.0/web/src/App.tsx +81 -0
- lumencell-0.1.0/web/src/api/client.ts +105 -0
- lumencell-0.1.0/web/src/api/events.ts +38 -0
- lumencell-0.1.0/web/src/api/generated/index.ts +3 -0
- lumencell-0.1.0/web/src/api/generated/types.gen.ts +2517 -0
- lumencell-0.1.0/web/src/api/lcb1.test.ts +88 -0
- lumencell-0.1.0/web/src/api/lcb1.ts +143 -0
- lumencell-0.1.0/web/src/api/queries.ts +244 -0
- lumencell-0.1.0/web/src/components/GenePanel.tsx +263 -0
- lumencell-0.1.0/web/src/components/GeneSearch.tsx +55 -0
- lumencell-0.1.0/web/src/components/Header.tsx +34 -0
- lumencell-0.1.0/web/src/components/Legend.tsx +41 -0
- lumencell-0.1.0/web/src/components/Scatter.tsx +293 -0
- lumencell-0.1.0/web/src/components/Sidebar.tsx +164 -0
- lumencell-0.1.0/web/src/components/trajectory/Compare.tsx +62 -0
- lumencell-0.1.0/web/src/components/trajectory/LineageTree.tsx +96 -0
- lumencell-0.1.0/web/src/components/trajectory/PrepProgress.tsx +68 -0
- lumencell-0.1.0/web/src/components/trajectory/PseudotimeFilter.tsx +45 -0
- lumencell-0.1.0/web/src/components/trajectory/RootPicker.tsx +124 -0
- lumencell-0.1.0/web/src/components/trajectory/Runs.tsx +112 -0
- lumencell-0.1.0/web/src/components/trajectory/TrajectoryPanel.tsx +43 -0
- lumencell-0.1.0/web/src/components/trajectory/TrustPanel.tsx +108 -0
- lumencell-0.1.0/web/src/components/ui.tsx +72 -0
- lumencell-0.1.0/web/src/components/useCellColors.ts +162 -0
- lumencell-0.1.0/web/src/index.css +94 -0
- lumencell-0.1.0/web/src/lib/colors.ts +122 -0
- lumencell-0.1.0/web/src/lib/geometry.ts +72 -0
- lumencell-0.1.0/web/src/lib/lib.test.ts +91 -0
- lumencell-0.1.0/web/src/main.tsx +20 -0
- lumencell-0.1.0/web/src/state/ui.ts +67 -0
- lumencell-0.1.0/web/src/test/fixtures.ts +123 -0
- lumencell-0.1.0/web/src/test/setup.ts +7 -0
- lumencell-0.1.0/web/tsconfig.app.json +26 -0
- lumencell-0.1.0/web/tsconfig.json +8 -0
- lumencell-0.1.0/web/tsconfig.node.json +26 -0
- lumencell-0.1.0/web/tsconfig.test.json +9 -0
- 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
|
lumencell-0.1.0/LICENSE
ADDED
|
@@ -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.
|
lumencell-0.1.0/Makefile
ADDED
|
@@ -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
|
lumencell-0.1.0/PKG-INFO
ADDED
|
@@ -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
|
+
```
|