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(...)),hands data to the viewer (
show_anndata(...)in a notebook;cellucid serve,serve_anndata(...)for a browser tab),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.
Notebook: Python kernel ◀── the notebook's connection ──▶ widget output (app from www.cellucid.com)
reads answered · commands ⇄ events on one viewer channel
Browser tab: Python ──starts──▶ local HTTP server ◀── fetch() (Range) ── web viewer (browser tab)
commands ⇄ events: one WebSocket, /_cellucid/ws
Reading order (recommended)#
What is a “viewer” object? (what you get back from
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, versioned files, 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 network requirements (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 files vs reproducible dataset files (and what resets when).
How to choose stable dataset IDs, version dataset files, and avoid “session applied to wrong data”.
Capture a .cellucid-session file 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.
Preparation-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 figures#
UI figures in this chapter use reproduced, visually reviewed application captures. Alt text describes the visible state, and captions state the contract the reader should verify.