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 Data preparation (prepare) (Cellucid-ready AnnData) + Server (browser tab + local HTTP server) (serving AnnData).
Power user / developer: start with Sessions (.cellucid-session files) (session bundles) + Vector fields (velocity / drift overlays) (velocity/drift overlays).

Which function should I call?#

You have…	You want…	Use…
`AnnData` or `MuData` (in memory), or any file or folder Cellucid reads (`.h5ad`, AnnData or MuData Zarr, `.h5mu`, `.loom`, a 10x `.h5` or `outs/` folder, a MatrixMarket folder, `.rds`/`.rda`/`.RData`)	The fastest “just show me” notebook view	`show_anndata()`
Arrays, an `AnnData` or a `MuData` to share or host	A Cellucid-ready AnnData (or MuData) file	`prepare()`
Any file or folder Cellucid reads (`.h5ad`, AnnData or MuData Zarr, `.h5mu`, `.loom`, a 10x `.h5` or `outs/` folder, a MatrixMarket folder, `.rds`/`.rda`/`.RData`)	Browser tab (local HTTP server)	`serve_anndata()` or `cellucid serve …` (with `--dataset-name` and `--dataset-id` unless the AnnData or MuData declares `uns['cellucid']['name']` and `['id']`, as every file `prepare` writes does)
A viewer, or the web app’s exports (CSV, GMT, session)	Everything made in Cellucid (highlights, labels, scores, gene sets) as `obs` columns, in one call	`viewer.pull(adata)` or `pull()`
An `obs` column or a gene set	Shown in the viewer	`viewer.push(...)`, `viewer.gene_set_save(...)`
A session saved in the web app (the history of every step)	Its trackers, branches and steps; the state at any step (labels, highlights, fields, gene sets) planned, then applied onto `AnnData`	`read_session()` + `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 any file or folder Cellucid reads, or an AnnData or MuData object (including SSH-tunnel workflows).

Data Preparation

prepare(...): write a Cellucid-ready AnnData (.h5ad, .zarr, .zarr.zip) or MuData (.h5mu, MuData Zarr).

Viewers

The AnnDataViewer class (Jupyter widget + hooks).

Round trip

Pull highlights, labels, scores and gene sets into obs in one call; push columns and gene sets; GMT.

Sessions

.cellucid-session files: read the history (trackers, branches, steps), plan and apply a step back to AnnData.

Vector Fields

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

CLI

cellucid serve: detects and serves any file or folder Cellucid reads.

“Cellucid-ready AnnData” means a standard AnnData written by prepare() (or R’s cellucid_prepare()): gene-major, chunked for range reads, naming itself in uns['cellucid'].
Every viewing API hands a file or folder, or an in-memory AnnData or MuData, to the viewer, which reads it itself: in place with HTTP range requests where the format allows it (AnnData, MuData, Loom, 10x), once from the start for an R object or a MatrixMarket folder. An in-memory AnnData, and an AnnData, MuData, Loom or 10x file (or outs/ folder) not in priority order, are served as a store with their cells in priority order, made as the viewer reads it and holding what the viewer presents from the file itself; an in-memory MuData as a MuData store, the same way. Expression matrices held in memory, and a cell-major X of a file, are laid out gene-major in the background, so the viewer opens at once.
Many APIs are lazy-imported from cellucid.__init__ to keep CLI startup fast; importing cellucid is intentionally lightweight.