Concepts and Mental Models (Python-side)#
This chapter is the “how to think about Cellucid” part of the cellucid Python package documentation.
It is written for mixed audiences:
Wet lab / non-technical: clear mental models and “what happens when I click?” explanations (no assumption of Python expertise).
Computational users: precise terminology, data-flow diagrams, and reproducibility guidance.
Power users / developers: lifecycle, state, network + security model, and debugging playbook.
If you prefer learning by doing, you can skim this chapter and jump to:
The 30‑second mental model#
Cellucid is a web app (the viewer UI). cellucid-python is a helper toolkit that:
prepares data for the viewer (
prepare(...)),serves data to the viewer (
serve(...),show(...),show_anndata(...)),and optionally lets Python and the browser talk to each other (hooks/events, sessions).
In notebooks, a “viewer object” is just a Python handle for a running viewer instance.
Python (kernel) ──starts──▶ local HTTP server ──serves──▶ web viewer (iframe/browser)
▲ │ │
│ │ fetch() │ UI interactions
│ ▼ │
└────────── events via POST ◀── /_cellucid/events ◀────────┘
Reading order (recommended)#
What is a “viewer” object? (what you get back from
show(...)/show_anndata(...))Data flows (what runs where: Python vs browser vs server)
State, persistence, and scope (what persists, what resets, and why)
Dataset identity and reproducibility (stable IDs, exports, and “paper-ready” workflows)
Sessions → AnnData (No-Download Bridge) (pulling session state into Python and mutating AnnData safely)
Optional deep dive: Sessions → AnnData (Design notes)
Privacy, security, and offline vs online (what leaves your machine, and how to run offline)
Performance mental model and scaling (what gets slow, why, and what to do)
Debugging mental model (where to look first) (a systematic checklist for “it doesn’t work”)
Pages in this chapter#
What a viewer is, what it controls, lifecycle/cleanup, and how events map to Python.
Where data lives (disk/server/browser), how the viewer loads it, and how hooks route events.
Live viewer state vs durable session bundles vs reproducible export folders (and what resets when).
How to choose stable dataset IDs, version exports, and avoid “session applied to wrong data”.
Capture a .cellucid-session bundle into Python (no download) and apply highlights/fields to AnnData.
Protocol and guardrails behind no-download session capture and safe AnnData application.
What stays local, what can be exposed on a network, and how to make offline usage predictable.
Export-time vs view-time costs, lazy loading, caching, and practical scaling advice.
The fastest path to diagnosing viewer/server/hook issues, with concrete checks and fixes.
Screenshots and figure placeholders#
When this chapter references a UI step in the Cellucid web app, it uses screenshot placeholders with explicit capture instructions. If you want to add images, follow the playbook in:
cellucid/markdown/DOCUMENTATION_SCREENSHOTS_AND_FIGURES_GUIDE.md