Viewing APIs (cellucid serve / serve_anndata / show_anndata + loading options)#

Cellucid is a web app (WebGL viewer UI). cellucid-python gives you Python + CLI entry points to open that viewer against your data.

There are two big “modes”:

  • Server mode (terminal/browser): cellucid serve …, serve_anndata(…)

  • Notebook mode (a widget in the cell’s output, no server): show_anndata(…)

All of them take any file or folder Cellucid reads — AnnData (.h5ad, a Zarr store folder or .zip), MuData (.h5mu, MuData Zarr), Loom, a 10x .h5 file or Cell Ranger outs/ folder, a MatrixMarket folder, an R object (.rds/.rda/.RData, gzipped or not) — and serve_anndata/show_anndata also an in-memory AnnData or MuData (Every loading route). The viewer reads a file in place, with range requests where the format allows it; an in-memory AnnData, and an AnnData file not in priority order, are served in priority order, made as the viewer reads them, so a subsample sends only its cells (a MuData object as a MuData store). A file written by prepare() (a Cellucid-ready AnnData) reads fastest and names itself, so it needs no dataset_name/dataset_id.

At a glance#

Audience

  • Wet lab / non-technical: copy/paste the quickstarts and use the decision tree.

  • Computational: focus on data format tradeoffs: .h5ad files, Zarr stores, and in-memory objects, prepared or not.

  • Power user / developer: focus on networking (SSH tunnels), caching, and debug endpoints.

Time

  • First successful view: ~5 minutes

  • Full read (with edge cases): ~30–45 minutes

Prerequisites

  • pip install cellucid

  • One of: a .h5ad, a Zarr store (folder or .zip), any other file or folder Cellucid reads (Every loading route), or an in-memory AnnData/MuData

Where to start#

Quick start (copy/paste)#

Notebook (fastest analysis loop)#

from cellucid import show_anndata

viewer = show_anndata(
    "data.h5ad",
    height=600,
    dataset_name="My study",
    dataset_id="my-study-v1",
)

A Cellucid-ready AnnData (fastest + names itself)#

from cellucid import show_anndata

viewer = show_anndata("pbmc_cellucid.h5ad", height=600)  # written by cellucid.prepare()

Read once: how the exact viewer generation is served#

Important

By design, the Python server serves both:

  1. your data: the AnnData store’s bytes under /_cellucid/anndata/, which the viewer reads itself with range requests, and

  2. the viewer UI (HTML/JS/CSS) by downloading it from https://www.cellucid.com and caching it locally.

This verified same-origin generation approach:

  • avoids HTTPS→HTTP mixed-content problems in notebooks and in strict browsers,

  • keeps the UI and data on the same origin (simplifies networking),

  • and requires the configured viewer source at every server startup.

If the source generation cannot be fetched and verified, startup reports the exact failure and does not bind the viewer server. Configure the generation directory with web_cache_dir=....

Relationship to the web app + other repos#

  • Cellucid (web app) is the UI you interact with.

  • cellucid-python (this documentation) is how you run servers, write Cellucid-ready AnnData files, and embed the viewer in notebooks.

  • cellucid-annotation is a separate repo for community annotation workflows (publish/vote/audit).

  • cellucid-r writes the same Cellucid-ready AnnData from R (cellucid_prepare()) and has its own viewer and server (cellucid_view(), cellucid_serve()) on the same viewer channel; this chapter documents the Python ones. See R Package Guide for R workflows.

Serving from somewhere that is not your laptop#