API Reference (cellucid-python)#

This section is the canonical reference for the public cellucid Python API (and the cellucid CLI).

Choose your path

Wet lab / beginner: start with Jupyter (notebook embedding + hooks) (notebooks) or CLI (cellucid) (terminal).
Computational user: start with Export / Data Preparation (prepare) (reproducible exports) + Server (browser tab + local HTTP server) (sharing + lazy loading).
Power user / developer: start with Sessions (.cellucid-session bundles) (session bundles) + Vector fields (velocity / drift overlays) (velocity/drift overlays).

Which function should I call?#

You have…	You want…	Use…
`AnnData` (in memory / `.h5ad` / `.zarr`)	The fastest “just show me” notebook view	`show_anndata()`
Exported dataset directory	Notebook embedding	`show()`
Exported dataset directory	Browser tab (local HTTP server)	`serve()` or `cellucid serve …`
`.h5ad` / `.zarr`	Browser tab without exporting first	`serve_anndata()` or `cellucid serve …`
A session captured in the web app	Apply highlights/fields back onto `AnnData`	`CellucidSessionBundle` + `apply_cellucid_session_to_anndata()`
A transition matrix + embedding	Vector field overlay in Cellucid	`compute_transition_drift()` / `add_transition_drift_to_obsm()`

Jupyter

Notebook embedding, hooks/events, and controlling the viewer from Python.

Server

Run a local server for exported datasets or AnnData (including SSH-tunnel workflows).

Export / Data Preparation

prepare(...) and the exported on-disk format used by the web viewer.

Viewers

CellucidViewer and AnnDataViewer classes (Jupyter widgets + hooks).

Adapters

AnnDataAdapter (server-side adapter for .h5ad/.zarr/in-memory AnnData).

Sessions

.cellucid-session bundles: read, inspect, and apply back to AnnData.

Vector Fields

Compute/store vector overlays (e.g., CellRank drift) for visualization.

CLI

cellucid serve auto-detects .h5ad, .zarr, or exported directories.

“Exported dataset directory” means a folder created by prepare() (contains dataset_identity.json, obs_manifest.json, and points_*d.bin(.gz)).
“AnnData mode” means serving data directly from an AnnData object or .h5ad/.zarr without running prepare first (convenient, but typically slower).
Many APIs are lazy-imported from cellucid.__init__ to keep CLI startup fast; importing cellucid is intentionally lightweight.