Viewing methods overview#

This page is the “map” of how you can open Cellucid against your data using cellucid-python.

If you just want to pick the right command, go to Choose your workflow (decision tree).

The mental model (1 minute)#

Cellucid always needs two things:

  1. the viewer UI (HTML/JS) that runs in your browser, and

  2. the dataset’s bytes: an AnnData file or store the viewer reads itself, with range requests.

cellucid-python brings them together in one of two ways:

  • In a notebook (show_anndata): a widget in the cell’s output frames the app, which the browser loads from https://www.cellucid.com, and the app reads the data from the kernel through the notebook’s own connection. No port, no server, no URL to open.

  • In a browser tab (cellucid serve, serve_anndata, AnnDataViewer): Python establishes the exact viewer generation and starts a local HTTP server that serves both UI and data from the same origin. Open the exact Viewer URL printed by that server:

    http://127.0.0.1:8765/?anndata=true

    The anndata=true marker declares the user-served source before the first paint, and the UI can load the data without cross-origin issues.

At a glance#

Audience

  • Wet lab / non-technical: use the CLI quickstart and stop at “What success looks like”.

  • Computational: pay attention to data formats (.h5ad vs Zarr store vs in-memory, prepared or not).

  • Power users: pay attention to SSH tunnels, remote kernels, and caching.

Prerequisites

  • pip install cellucid

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

The three core entry points#

You want to…

Best entry point

You pass…

Typical place you run it

Open the viewer from the terminal

cellucid serve …

a path

terminal

Start a server from a Python script

serve_anndata(…)

a path, an AnnData or a MuData

Python (notebook optional)

Show the viewer in a notebook cell

show_anndata(…)

a path, an AnnData or a MuData

JupyterLab (tested); Notebook 7, VS Code, Colab, marimo, Databricks (expected, not tested)

A viewer object in a browser tab (script, SSH tunnel)

AnnDataViewer(…)

a path, an AnnData or a MuData

Python

Server mode vs notebook mode#

  • Server mode (cellucid serve, serve_anndata) is a normal “keep this terminal running” server.

  • Notebook mode (show_anndata) starts no server: it shows a widget in the cell’s output and gives you a viewer object for hooks, commands and pulling results back.

  • Browser-tab viewer (AnnDataViewer) is a server plus the same viewer object, for a script or an SSH tunnel.

Data inputs#

Data input

How you get it

Recommended APIs

Why you’d choose it

Cellucid-ready AnnData

cellucid.prepare(...)

show_anndata("pbmc_cellucid.h5ad") / serve_anndata(...) / cellucid serve pbmc_cellucid.h5ad

fastest; names itself; easiest to share and host

.h5ad path

AnnData HDF5 file

show_anndata("…h5ad", dataset_name="My dataset", dataset_id="my-dataset") / serve_anndata("…h5ad", dataset_name="My dataset", dataset_id="my-dataset") / cellucid serve data.h5ad --dataset-name "My dataset" --dataset-id my-dataset

convenient + scalable: the viewer reads the file in place, with range requests

Zarr store path (folder or .zip)

AnnData Zarr store

show_anndata("…zarr", dataset_name="My dataset", dataset_id="my-dataset") / serve_anndata("…zarr", dataset_name="My dataset", dataset_id="my-dataset") / cellucid serve data.zarr --dataset-name "My dataset" --dataset-id my-dataset

convenient + scalable: read in place, key by key

In-memory AnnData

you already loaded it

show_anndata(adata, dataset_name="My dataset", dataset_id="my-dataset") / serve_anndata(adata, dataset_name="My dataset", dataset_id="my-dataset")

convenient; served in priority order, made from the object as the viewer reads it

MuData (.h5mu, MuData Zarr, or in memory)

mudata, or prepare(data=mdata, ...)

the same calls; modality="rna" (--modality rna) picks the modality it opens on

several modalities over the same cells; an object is served as a MuData store made from it

Loom, 10x .h5 / outs/, MatrixMarket folder, .rds/.rda

other tools

a path, with dataset_name/dataset_id (Python reads no identity from these)

no conversion: the browser reads them itself (Every loading route)

Where these fit among every loading route#

Data reaches the viewer either through the browser itself (a sample, a link, a file) or through a Cellucid server, which these APIs start.

Common “gotchas” (read once)#

  • Large dataset? An in-memory object and any AnnData file are served in priority order, so a subsample sends only its cells; a file written by prepare() is served as it is, gene-major, so every gene is one small read (Performance and storage).

  • Remote machine? Don’t bind to 0.0.0.0 unless you mean to. Use an SSH tunnel first: Remote servers, SSH tunneling, and cloud.

  • Remote notebook (JupyterHub, VS Code Remote, Colab)? show_anndata() needs no port or proxy: Notebook / widget mode (advanced).

  • Viewer source blocked? A notebook widget needs the browser to reach https://www.cellucid.com (or web_source_url); a browser-tab server stops at startup instead of using a previous generation. See Server mode (advanced) and Troubleshooting (viewing).

Next steps#