Viewer classes (Jupyter objects you control from Python)#

Two classes share one viewer API:

Widget (also cellucid.Widget): the notebook widget show_anndata() returns, shown in a cell’s output and reached through the notebook’s own connection;
AnnDataViewer: the same API for a viewer in a browser tab of its own, served from this machine (a script, an SSH tunnel).

They are designed for two-way interaction:

Viewer → Python: hooks/events like @viewer.on_selection
Python → Viewer: actions – every action of the viewer is a method, like viewer.highlight_cells(...) – each a step of the viewer’s history

If you prefer a minimal interface, start with Jupyter (notebook embedding + hooks).

Fast path#

A) Any AnnData, in a notebook#

import cellucid

viewer = cellucid.Widget(
    adata,
    dataset_name="My study",
    dataset_id="my-study-v1",
)
viewer  # the cell's output shows it (show_anndata() shows it for you)

B) A Cellucid-ready AnnData (written by `prepare()`), in a browser tab#

from cellucid import AnnDataViewer

viewer = AnnDataViewer("my_study.h5ad")  # names itself (uns['cellucid'])
print(viewer.viewer_url)  # open it in a browser; in a notebook a link is shown

Practical path (what you can do with a viewer)#

1) Register hooks (viewer → Python)#

@viewer.on_selection
def on_selection(event):
    cells = event.get("cells", [])
    print("Selected", len(cells))

@viewer.on_ready
def on_ready(event):
    print("Viewer ready:", event)

2) Drive the UI from Python (Python → viewer)#

Every action of the viewer – everything a person can do, and everything an agent reads – is a method, generated from the action catalogue (the full list):

viewer.color_by(field={"source": "obs", "key": "cell_type"})
viewer.highlight_cells(cells=[0, 1, 2], color="#00ff00")
viewer.camera_reset(view="live")
fields = viewer.fields_list()            # a read

Each returns an ActionRequest without waiting for the viewer; request.result() (in a notebook, in a later cell) is the viewer’s answer – a read’s result, or a change’s outcome – and raises ActionError with the viewer’s reason when it did not apply the action. A refusal nobody collects is printed to sys.stderr unless you take it over:

@viewer.on_command_error
def on_command_error(event):
    print("Refused:", event["requestId"], event["reason"])

viewer.act(type, **params) sends any action named in data (viewer.act("color.by", field=...)); cellucid.jupyter.action_catalog() lists them all (Python → frontend actions).

3) Robust scripts: wait for readiness#

A browser-tab viewer answers while your code runs, so it can wait:

viewer.wait_for_ready(timeout=30)

(A notebook widget hears the viewer only between cells; there, use @viewer.on_ready or read viewer.state.ready in a later cell — see Jupyter (notebook embedding + hooks).)

4) Pull results, or capture a session#

summary = viewer.pull(adata)                 # highlights, labels, scores -> adata.obs
request = viewer.request_session()
session = request.result(timeout=60)         # in a notebook: in the next cell
plan = session.apply(adata)                  # what applying the step shown would change

See Round trip (results back from the viewer, columns and gene sets into it) for the round trip, and Sessions (.cellucid-session files) for applying a session back to AnnData.

5) The history: turns, changes, sessions loaded#

with viewer.turn("Mark the T cells"):            # one turn of the history, undone together
    viewer.color_by(field={"source": "obs", "key": "cell_type"})
    viewer.highlight_cells(cells=adata.obs["cell_type"] == "T cell", label="T cells")

@viewer.on_history_change
def on_history_change(event):
    print(event["kind"], event["head"])

viewer.history.last_change                       # the latest change, or None
viewer.history_undo()                            # the history's actions are methods too
loading = viewer.load_session("analysis.cellucid-session")

A turn’s actions carry its id (python- and 12 hexadecimal digits) and label; turns do not nest. viewer.history is a LiveHistory: the latest history_changed event and a hook on each; the history is changed through the generated history_* methods. viewer.load_session(...) adds a session file’s trackers beside the person’s own and returns a LoadSessionRequest (loading.result() in a later cell: {"tracker": {"id", "name"}, "head"}).

6) Read and change the data mapping#

viewer.mapping_set(
    embeddings={
        "enabled": [{"key": "X_tsne", "columns": [0, 1]}],
        "defaults": {"1d": None, "2d": {"key": "X_tsne", "columns": [0, 1]}, "3d": None},
    },
)

Nothing waits. mapping_set() (the mapping.set action) changes the groups it names and leaves the others as they are (knn=None is “no neighbour graph”; leaving knn out keeps the one shown). The viewer reports its mapping once the dataset loads and again whenever it changes: the applied mapping is viewer.data_mapping from a later cell; a mapping the viewer refuses fails the request with the reason.

print(viewer.data_mapping["embeddings"])   # a later cell

Lifecycle and cleanup (important)#

Under the hood, a viewer starts a local server on a background thread of the kernel: on port 8765, or the next free port when 8765 is taken (a printed note says so).

Best practices:

If you create many viewers in a long-running notebook, call viewer.stop() when done.
If you repeatedly re-run a cell, you may end up with multiple servers unless the old viewer is stopped.

API reference#

`Widget`#

class cellucid.jupyter.Widget(data, height=600, *, latent_key=None, gene_id_column=None, normalize_embeddings=None, centroid_min_points=None, dataset_name=None, dataset_id=None, obs_keys=None, embedding_keys=None, knn_key=None, expression_source=None, vector_field_default=None, modality=None, web_source_url='https://www.cellucid.com', cache_bytes=None)[source]#

Bases: AnnDataViewer, AnyWidget

The Cellucid viewer as a notebook widget.

The same viewer API as AnnDataViewer – hooks (@viewer.on_selection, on_hover, on_click, on_ready, …), viewer.state, actions (one method per action of the catalogue: color_by, highlight_cells, history_get, …; act), sessions – shown in a notebook cell’s output and reached through the notebook’s own connection: no port, proxy or server address, so it works in JupyterLab, Jupyter Notebook 7, VS Code, Google Colab, marimo and Databricks alike. show_anndata() creates one and shows it; a Widget made directly is shown by making it a cell’s output.

The page is the Cellucid app at web_source_url (https://www.cellucid.com by default), loaded by the browser; the dataset never leaves this kernel except to that page, through the widget.

The viewer’s messages reach Python between cells, as every notebook widget’s do. So, in the cell that asks:

wait_for_ready() and wait_for_event() cannot wait for the viewer and raise at once with what to do instead; request_session() asks now, and its result() (or apply_session_to_anndata(adata, request)) collects the session in a later cell;
hooks run, and viewer.state updates, whenever the kernel is idle;
actions (color_by, highlight_cells, push and the rest) wait for nothing: they go as soon as the viewer can take them, and the request each returns is collected with result() in a later cell.

Example:

viewer = cellucid.Widget(adata)
viewer            # the cell's output shows the viewer

@viewer.on_selection
def handle(event):
    print(len(event["cells"]))

Parameters:

data (str | Path | anndata.AnnData | mudata.MuData)
height (int)
latent_key (str | None)
gene_id_column (str | None)
normalize_embeddings (bool | None)
centroid_min_points (int | None)
dataset_name (str | None)
dataset_id (str | None)
obs_keys (Sequence[str] | None)
embedding_keys (Mapping[str, EmbeddingKeySpec] | None)
knn_key (str | None)
expression_source (str | None)
vector_field_default (str | None)
modality (str | None)
web_source_url (str)
cache_bytes (int | None)

height#: Height of the viewer in pixels.

web_source_url#: Where the browser loads the Cellucid app from.

__init__(data, height=600, *, latent_key=None, gene_id_column=None, normalize_embeddings=None, centroid_min_points=None, dataset_name=None, dataset_id=None, obs_keys=None, embedding_keys=None, knn_key=None, expression_source=None, vector_field_default=None, modality=None, web_source_url='https://www.cellucid.com', cache_bytes=None)[source]#

Prepare the dataset for the viewer; the viewer starts when the widget is shown.

Parameters:

data (str | Path | anndata.AnnData | mudata.MuData) – AnnData or MuData object, or path to a file or folder Cellucid reads (show_anndata() lists them).
height (int) – Height of the viewer in pixels.
web_source_url (str) – Where the browser loads the Cellucid app: https://www.cellucid.com, or the address of a copy you host (no query, fragment or trailing slash).
latent_key (str | None)
gene_id_column (str | None)
normalize_embeddings (bool | None)
centroid_min_points (int | None)
dataset_name (str | None)
dataset_id (str | None)
obs_keys (Sequence[str] | None)
embedding_keys (Mapping[str, EmbeddingKeySpec] | None)
knn_key (str | None)
expression_source (str | None)
vector_field_default (str | None)
modality (str | None)
cache_bytes (int | None)

Return type:

None

Every other argument is show_anndata()’s.

wait_for_ready(timeout=30.0)[source]#

Return the viewer’s ready payload, waiting for it if it has not arrived.

In the cell that showed the widget (or any cell before the viewer loaded) this cannot wait – the viewer loads once the cell ends – and raises at once; @viewer.on_ready runs when it is ready.

Return type:: dict[str, Any]
Parameters:: timeout (float | None)

display()[source]#

Show the viewer in the cell’s output (an IPython kernel).

Return type:: None

property viewer_url: str#

its page lives in the cell’s output.

Type:: A widget has no address of its own

property server_url: str#

the page reads the data through the widget.

Type:: A widget runs no server

clear_web_cache()[source]#

A widget keeps no web build: the browser loads the app from web_source_url.

Return type:: Path

ensure_web_ui_cached(*, force=True, show_progress=True)[source]#

A widget keeps no web build: the browser loads the app from web_source_url.

Return type:

Any

Parameters:

force (bool)
show_progress (bool)

debug_connection(timeout=5.0)[source]#

Return a structured report of this widget’s connection.

Says where the app is loaded from, which outputs are connected and whether the channel is open, what the viewer last reported, and the commands it refused. It waits for nothing, so it works in any cell.

Return type:: dict[str, Any]
Parameters:: timeout (float | None)

stop()[source]#

Stop the viewer: its page keeps the last view, and what was served is let go.

The output stays on screen, frozen; Python stops answering it, and the served store – the object’s snapshot, its matrices laid out in files of the temporary folder – is removed. A widget is stopped by itself when the cell that showed it runs again (its output is replaced) and when it is closed (close()).

Return type:: None

close()[source]#

Close the widget: the viewer stops first (stop()), then its comm closes.

Return type:: None

Widget has every method of AnnDataViewer below except the ones about its server and web build (viewer_url, server_url, clear_web_cache, ensure_web_ui_cached).

`AnnDataViewer`#

class cellucid.AnnDataViewer(data, port=None, auto_open=True, *, latent_key=None, gene_id_column=None, normalize_embeddings=None, centroid_min_points=None, dataset_name=None, dataset_id=None, obs_keys=None, embedding_keys=None, knn_key=None, expression_source=None, vector_field_default=None, modality=None, client_server_url=None, web_source_url='https://www.cellucid.com', web_cache_dir=None, allowed_hosts=None, cache_bytes=None)[source]#

Bases: ViewerActions

Interactive viewer for AnnData objects, in a browser tab of its own.

This machine serves the Cellucid page and the data, and the page talks back over a WebSocket; open viewer_url in a browser (in a notebook, display() shows a link to it). The viewer reads the AnnData store itself, in place, with range requests: only what a view needs is read, and nothing is converted first. Supports bidirectional communication via hooks.

To show the viewer inside a notebook cell, use show_anndata() or cellucid.jupyter.Widget: the same API, reached through the notebook’s own connection.

Supports every file and folder Cellucid reads (.h5ad and AnnData Zarr, .h5mu and MuData Zarr, .loom, 10x .h5 and outs/, MatrixMarket folders, .rds/.rda/.RData, gzipped or not), served as it is on disk – an AnnData, MuData, Loom or 10x file not in priority order, and an in-memory AnnData or MuData, as a store in priority order made as the page reads it (an object’s expression matrices laid out gene-major in the background), removed when the viewer stops.

Example

>>> viewer = AnnDataViewer(
...     adata,
...     dataset_name="Example",
...     dataset_id="example",
... )
>>> viewer.display()
>>>
>>> @viewer.on_selection
... def analyze_selection(event):
...     subset = adata[event['cells']]
...     sc.pl.violin(subset, ['gene1', 'gene2'])
>>>
>>> # From an .h5ad file, read in place
>>> viewer = AnnDataViewer(
...     "/path/to/data.h5ad",
...     dataset_name="Example",
...     dataset_id="example",
... )

Event Hooks:

Register callbacks to respond to user interactions in the viewer:

@viewer.on_selection
def handle(event):
    print(event['cells'])  # list of selected cell indices

@viewer.on_hover
def handle(event):
    print(event['cell'])  # hovered cell index

@viewer.on_click
def handle(event):
    print(event['cell'])  # clicked cell index

@viewer.on_ready
def handle(event):
    print("Viewer loaded!")

@viewer.on_command_error
def handle(event):
    print(event['command'], event['reason'])  # a command failed

@viewer.on_data_mapping
def handle(event):
    print(event['origin'], event['mapping'])  # what the viewer plots

@viewer.on_history_change
def handle(event):
    print(event['kind'], event['head'])  # the history changed

@viewer.on_message
def handle(event):
    print(event)  # raw message dict

Parameters:

data (str | Path | anndata.AnnData | mudata.MuData)
port (int | None)
auto_open (bool)
latent_key (str | None)
gene_id_column (str | None)
normalize_embeddings (bool | None)
centroid_min_points (int | None)
dataset_name (str | None)
dataset_id (str | None)
obs_keys (Sequence[str] | None)
embedding_keys (Mapping[str, EmbeddingKeySpec] | None)
knn_key (str | None)
expression_source (str | None)
vector_field_default (str | None)
modality (str | None)
client_server_url (str | None)
web_source_url (str)
web_cache_dir (str | Path | None)
allowed_hosts (Sequence[str] | None)
cache_bytes (int | None)

__init__(data, port=None, auto_open=True, *, latent_key=None, gene_id_column=None, normalize_embeddings=None, centroid_min_points=None, dataset_name=None, dataset_id=None, obs_keys=None, embedding_keys=None, knn_key=None, expression_source=None, vector_field_default=None, modality=None, client_server_url=None, web_source_url='https://www.cellucid.com', web_cache_dir=None, allowed_hosts=None, cache_bytes=None)[source]#

Initialize the AnnData viewer.

Parameters:

data (str | Path | anndata.AnnData | mudata.MuData) – AnnData or MuData object, or path to a file or folder Cellucid reads (see above). A leading ~ in a path is expanded to the user’s home directory.
port (int | None) – Port for the data server. None takes 8765 – the one local port Cellucid registers with Google, so Google Drive files open (community annotation’s GitHub sign-in works only on www.cellucid.com) – or, when another viewer holds it, the next free port, said in a printed note (cellucid-r’s cellucid_view() does the same). A port given is used or refused.
auto_open (bool) – Show where the viewer is when created: a link in a notebook (display()), its address on the console.
latent_key (str | None) – obsm array (a latent space such as scVI or PCA) the viewer’s outlier filter measures in, instead of the data’s own uns['cellucid']['defaults']['latentKey']. The viewer reads the outlier quantiles the data stores for it, or computes them on first use.
gene_id_column (str | None) – Exact column in var (raw.var with expression_source="raw") whose values name the genes. If None, genes are named by the index.
normalize_embeddings (bool | None) – Whether the viewer scales embeddings into its coordinate range.
centroid_min_points (int | None) – The fewest cells a category needs to get outlier quantiles (10 when None).
dataset_name (str | None) – Exact non-empty human-readable name without surrounding whitespace or control characters. Defaults to uns['cellucid']['name'], else the file’s name, or AnnData (<n> cells) for an object.
dataset_id (str | None) – Portable 1-180 byte ASCII identifier beginning with a letter or digit and otherwise using letters, digits, ., _, or -; no trailing . or Windows device name. Defaults to uns['cellucid']['id'], else made from the file’s name without its extension, or from the object’s label (AnnData (N cells)) (said in one line: sessions are kept under it).
obs_keys (Sequence[str] | None) – Exact obs columns the viewer shows, in this order. If None, every column is shown.
embedding_keys (Mapping[str, EmbeddingKeySpec] | None) – The embedding of a dimension slot, such as {"2d": "X_tsne"} or {"2d": ("X_pca", [2, 0])} with 0-based columns. Slots not named follow the default rule, and a deterministic best guess applies when no slot resolves.
knn_key (str | None) – The obsp matrix the viewer draws as the neighbour graph, such as "connectivities"; read only when a view draws it. None follows the viewer’s default rule.
expression_source (str | None) – "X", "raw", or "layer:<name>"; None follows the viewer’s default rule (raw when it holds more genes than X or X is scaled, as Scanpy reads genes; else X).
vector_field_default (str | None) – The vector field the overlay opens on: <field> of an obsm array <field>_<basis> drawn over X_<basis> (velocity for velocity_umap).
modality (str | None) – The modality a multimodal dataset (a MuData) opens on; None opens the default one. Set only for multimodal data.
client_server_url (str | None) – Exact browser-reachable data server base URL.
web_source_url (str) – Origin publishing the web asset inventory.
web_cache_dir (str | Path | None) – Directory holding the active verified web build.
allowed_hosts (Sequence[str] | None) – Extra Host names the data server answers to. Required when client_server_url points at a reverse proxy such as jupyter-server-proxy: name that proxy’s host here.
cache_bytes (int | None) – What the data server keeps of what it makes for a store served in priority order, in bytes (least recently used first out); None keeps a 64th of the machine’s memory, 0 nothing (as cellucid.serve_anndata()’s).

Return type:

None

property on_selection: Callable[[Callable[[dict[str, Any]], None]], Callable[[dict[str, Any]], None]]#

Decorator to register a selection handler.

Called when user selects cells (lasso, shift-click, etc.)

Event data:

cells: list[int] - indices of selected cells, unique and ascending
source: str - selection method (‘lasso’, ‘knn’, ‘proximity’, ‘annotation’, …)

Example:

@viewer.on_selection
def handle(event):
    selected = adata[event['cells']]
    sc.pl.violin(selected, 'gene1')

property on_hover: Callable[[Callable[[dict[str, Any]], None]], Callable[[dict[str, Any]], None]]#

Decorator to register a hover handler.

Called when user hovers over a cell.

Event data:

cell: int | None - cell index (None if not hovering over cell)
position: dict - {x, y, z} world coordinates

Example:

@viewer.on_hover
def handle(event):
    if event['cell'] is not None:
        print(f"Cell {event['cell']}: {adata.obs.iloc[event['cell']]}")

property on_click: Callable[[Callable[[dict[str, Any]], None]], Callable[[dict[str, Any]], None]]#

Decorator to register a click handler.

Called when user clicks on a cell.

Event data:

cell: int - clicked cell index
button: int - mouse button (0=left, 1=middle, 2=right)
shift: bool - shift key held
ctrl: bool - ctrl/cmd key held

Example:

@viewer.on_click
def handle(event):
    print(f"Clicked cell {event['cell']}")

property on_ready: Callable[[Callable[[dict[str, Any]], None]], Callable[[dict[str, Any]], None]]#

Decorator to register a ready handler.

Called when viewer finishes loading and is ready for interaction.

Event data:

n_cells: int - number of cells in dataset
dimensions: int - embedding dimensionality (1, 2, or 3)

Example:

@viewer.on_ready
def handle(event):
    print(f"Loaded {event['n_cells']} cells")

property on_command_error: Callable[[Callable[[dict[str, Any]], None]], Callable[[dict[str, Any]], None]]#

Decorator to register a handler for a failed Python → viewer command.

Called when a command this viewer sent – an action (viewer.color_by(...), viewer.act(...)), a session request – was refused by the viewer instead of carried out. An action returns its request at once, so its method has returned by the time the failure arrives: this hook (or the request’s result(), which raises the same reason) is how a notebook learns that the viewer is unchanged.

Registering a handler also silences the notice Cellucid otherwise prints to sys.stderr, so reporting happens once, where you chose.

Event data:

command: str - the command type that failed: "action", "requestSessionBundle", …
requestId: str or None - the request it fails (an action’s request.request_id); None for a command that names none
reason: str - what the viewer reported, in one line

Like every hook, this runs on the viewer channel’s thread, not in your cell: an exception raised here is logged (logger cellucid.viewer_channel) and never reaches the notebook, the callbacks after it do not run, and the event is not recorded in viewer.state or handed to wait_for_event. Record the failure and raise from your own code. An action that did apply is answered too: its request’s result() returns its outcome.

Example:

rejected = []

@viewer.on_command_error
def handle(event):
    rejected.append(event)

viewer.color_by(field={"source": "obs", "key": "cell_type"})
...
if rejected:
    raise RuntimeError(rejected[-1]["reason"])

property on_data_mapping: Callable[[Callable[[dict[str, Any]], None]], Callable[[dict[str, Any]], None]]#

Decorator to register a handler for the viewer’s data mapping.

Called when the viewer reports which stored arrays it plots and reads: once after the dataset loads, and again whenever the mapping changes – from the viewer’s controls, a session, or this notebook’s mapping_set(). The viewer sends it because this package lists data_mapping among the events of GET /_cellucid/protocol.

Event data:

origin: str - why the mapping is what it is: "default", "best_guess", "session", "user", or "notebook" (this notebook’s mapping_set())
mapping: dict - the complete data mapping, in canonical form

Example:

@viewer.on_data_mapping
def handle(event):
    print(event["mapping"]["embeddings"])

property on_history_change: Callable[[Callable[[dict[str, Any]], None]], Callable[[dict[str, Any]], None]]#

Decorator to register a handler for every change of the viewer’s history.

Called when a step is recorded (by the person, an agent, or this notebook), the step shown moves (undo, redo, a jump, another branch), the history’s structure is edited (a rename, a note, a bookmark, a delete, a restore), a tracker is started, used, renamed or removed, or a session is loaded. viewer.history keeps the latest.

Event data:

kind: str - "step", "moved", "edited", "tracker" or "loaded"
tracker: str - the id of the tracker in use
head: str - the step shown
step: str or None - the step recorded ("step"), else None
branch: str or None - the id of the active branch

Example:

@viewer.on_history_change
def handle(event):
    if event["kind"] == "step":
        print("recorded", event["step"])

property history: LiveHistory#: The viewer’s history, live (LiveHistory): the latest change it told, a hook on each change, and its history read as a session. The history is changed through the generated history_* methods (history_undo(), history_jump(step=...), history_note_add(...), …).

turn(label)[source]#

Make every action sent inside the with block one turn of the viewer’s history.

The State panel shows the turn’s steps as one group, labelled label and by this notebook, and undoes them together (Undo turn), as it does an agent’s turn. Yields the turn’s id. Turns do not nest.

Example:

with viewer.turn("Normalise and cluster"):
    viewer.color_by(field={"source": "obs", "key": "leiden"})
    viewer.highlight_cells(cells=adata.obs["leiden"] == "3", label="Leiden 3")

Return type:: Iterator[str]
Parameters:: label (str)

load_session(session)[source]#

Load a session file into the viewer: its trackers are added beside the person’s own (nothing of theirs is replaced), and the file’s tracker shown is shown.

The session must be of the dataset this viewer shows. Returns the LoadSessionRequest; its result is {"tracker": {"id", "name"}, "head"} (in a notebook, collect it in a later cell).

Example:

viewer.load_session("analysis.cellucid-session")

Return type:: LoadSessionRequest
Parameters:: session (str | Path | CellucidSession)

property on_message: Callable[[Callable[[dict[str, Any]], None]], Callable[[dict[str, Any]], None]]#

Decorator to register a raw message handler.

Called for every validated current-schema message from the viewer. Use it to observe the complete event stream while debugging.

Event data:

event: str - the event type
… other fields depend on event type

Example:

@viewer.on_message
def handle(event):
    print(f"Got message: {event}")

register_hook(event, callback)[source]#

Register a callback for an event (non-decorator style).

Parameters:

event (str) – Event name (‘selection’, ‘hover’, ‘click’, ‘ready’, ‘command_error’, ‘data_mapping’, ‘message’)
callback (Callable[[dict[str, Any]], None]) – Function to call when event fires

Return type:

Callable[[dict[str, Any]], None]

Returns:

The callback function

Example:

def my_handler(event):
    print(event['cells'])

viewer.register_hook('selection', my_handler)

unregister_hook(event, callback)[source]#

Remove a callback from an event.

Parameters:

event (str) – Event name
callback (Callable[[dict[str, Any]], None]) – The callback to remove

Return type:

bool

Returns:

True if found and removed, False otherwise

clear_hooks(event=None)[source]#

Clear all callbacks for an event, or all events.

Parameters:: event (str | None) – Event name to clear, or None to clear all

wait_for_event(event, timeout=30.0, *, predicate=None)[source]#

Block until the next event of the given type arrives.

Parameters:

event (str) – Event type (e.g. “ready”, “selection”, “session_bundle”).
timeout (float | None) – Seconds to wait. None means wait forever.
predicate (Callable[[dict[str, Any]], bool] | None) – Optional filter on the event payload.

Returns:

The payload of the first matching event that arrives after the call (an event recorded before it is not returned).

Return type:

dict

Raises:

TimeoutError – No matching event arrived within timeout.

wait_for_ready(timeout=30.0)[source]#

Return the viewer’s ready payload, waiting for it if it has not arrived.

Raises TimeoutError when it does not arrive within timeout seconds (None waits forever).

Return type:: dict[str, Any]
Parameters:: timeout (float | None)

request_session()[source]#

Ask the viewer for its session – its whole history – without waiting.

The request is sent at once (or as soon as the viewer connects) and the viewer answers in the background with a .cellucid-session file of format 4: every tracker of the dataset’s history, each step, and the values each step shows (conversations of the chat bar are left out). Collect it with the returned request’s result() (a CellucidSession). In a notebook widget the answer arrives once the cell that asked has finished, so collect it in a later cell:

request = viewer.request_session()
# next cell
session = request.result()
plan = session.apply(adata)  # what would change, one row each
plan.apply()

Returns:: The request; request.done says whether the answer arrived.
Return type:: SessionRequest

property data_mapping: dict[str, Any] | None#

The data mapping the viewer last reported, or None before it reported one.

This is a copy of the mapping of the latest data_mapping event: which embedding fills each dimension slot, the bound vector fields, and – for an AnnData source – the neighbour graph, the gene names, the expression matrix and the latent space. Editing the copy changes nothing; use mapping_set() (the mapping.set action).

property data_mapping_origin: str | None#: Why the viewer’s data mapping is what it is, or None before it reported one.

act(action, /, **params)[source]#

Apply (or read) one action of the viewer, by its dotted type.

Every action has a method of its own as well (viewer.color_by(...) is viewer.act("color.by", ...)); act is the same for an action named in data, and every action is listed by cellucid.jupyter.action_catalog(). Parameters are checked by the catalogue and converted the same way for every action: cells (x-cells) as rows, a boolean mask or obs names; one number per cell (x-values) as an array; everything else as JSON (NumPy values and pandas indexes as lists). A parameter written in in the catalogue is in_ as a method’s keyword.

The action is sent at once (or as soon as the viewer connects) and the viewer applies it as a person’s control would: one step of its history, labelled as this notebook’s, undone like any other. Nothing waits: the returned request’s result() waits for the outcome – a read’s result – and raises ActionError with the viewer’s reason when it did not apply the action. In a notebook widget the answer arrives once the cell has finished, so collect it in a later cell:

request = viewer.fields_list()
# next cell
fields = request.result()

Example:

viewer.act("color.by", field={"source": "obs", "key": "cell_type"})
viewer.highlight_cells(cells=adata.obs["leiden"] == "3", label="Leiden 3")

Return type:

ActionRequest

Parameters:

action (str)
params (Any)

property results: list[ViewerResult]#

highlight groups, user-defined fields (labels, clusters), scores, gene sets, the visible and the open cells.

Raises RuntimeError before the viewer has sent them all once (it does when its dataset has opened): run the cell again then; and while the viewer shows a dataset this viewer did not serve (one opened in it instead), whose cells are not this dataset’s.

Type:: Every result the viewer holds, as of the last event it sent

pull(adata, *, highlights=True, fields=True, scores=True, visibility=False, gene_sets=True, include_pushed=False, highlight_prefix='cellucid_highlight__', field_prefix='', on_conflict='error', prune=True)[source]#

Write everything made in this viewer onto adata, in place, in one call.

Every highlight group, user-defined field (labels, annotations, clusters), score and gene set the viewer holds – see cellucid.pull() for the columns, their names and dtypes, and every option. adata is the AnnData or MuData the viewer shows, cells in the same order. Nothing is waited for: the viewer sent its results as they were made, so in a notebook a lasso drawn and this run in the next cell finds the lasso.

Example:

summary = viewer.pull(adata)
summary.columns          # what was written, by obs column
adata.uns["cellucid"]["gene_sets"]

Return type:

PullSummary

Parameters:

adata (Any)
highlights (bool)
fields (bool)
scores (bool)
visibility (bool)
gene_sets (bool)
include_pushed (bool)
highlight_prefix (str)
field_prefix (str)
on_conflict (str)
prune (bool)

property obs_names: Index | None#

The obs names of the cells this viewer shows, in the order it names them (their original order), or None when this process cannot read them (a format only the browser reads).

Taken from what is served (AnnDataServer.obs_names): an object’s names as they were when it was shown – its cells put back in their original order when it was read from a file in priority order – whatever is done to it after; a file’s at the version it is served as. A viewer that stopped keeps the last ones.

property selection: Selection | None#: The viewer’s last selection (lasso, k-NN, proximity, annotation), or None before the first: its cells as rows of obs and, when this process has them, their obs names.

subset(adata, which=None)[source]#

The cells of a highlight group, or of the last selection, as a new AnnData.

Parameters:

adata (Any) – The AnnData (or MuData) the viewer shows, cells in its order (an object holding them in another order is refused, as pull() refuses it).
which (str | None) – A highlight group, by id ("highlight_3") or by its label; "visible" for the cells the filters leave visible; None for the last selection.

Return type:

Any

Returns:

adata[cells].copy() (to_memory() for a backed AnnData).

gene_sets(*, symbols=False)[source]#

Every gene set the viewer holds: the notebook’s, the shown marker genes result’s (one per group) and the shown gene signature’s, by name (a name used again is "name (2)", as everywhere in Cellucid).

Each set’s genes are identifiers – the var index, as adata.var_names holds them – or, with symbols=True, the names the viewer shows for them: those of the var column its data mapping names the genes by (such as feature_name), else the identifiers themselves. cellucid.write_gmt() writes them as a GMT file.

Return type:: dict[str, list[str]]
Parameters:: symbols (bool)

push(values, key=None)[source]#

Show a column in the viewer as a field: labels as a categorical, numbers as a continuous field. Pushing the same key again replaces it.

The field.push action, made from a Python column (its own method, viewer.field_push(...), takes the codes and values as the viewer stores them).

Parameters:

values (Any) – A pandas.Series – adata.obs["leiden"], a score – aligned to the viewer’s cells by its index (obs names), or an array or list of one value per cell in obs order. Categorical, string, object and bool values become a categorical (missing values have no category; a bool’s labels are "false" and "true"); numbers a continuous field (missing: no value).
key (str | None) – The field’s name in the viewer; the Series’ name when None. A field of that name the notebook did not push is never replaced: the viewer refuses it, and says why.

Returns:

its result is {"name", "kind", "id"} once the viewer added the field (results lists it from then on; in a notebook, from the next cell). The column is sent at once, or, for a format only the browser reads, once the viewer has said how many cells it has (a cell run before that, “Run All”, is fine). A column the viewer refuses, or that does not fit the dataset once it is known, fails the request with the reason (printed unless a command_error hook handles it).

Return type:

The ActionRequest

apply_session_to_anndata(adata, request, *, tracker=None, branch=None, step=None, dry_run=True, overwrite=False, keep_session=False, timeout=60.0, cleanup_file=True)[source]#

Plan or apply the session a request_session() request brought to an AnnData.

The one way to get the viewer’s state into an object, in a notebook widget and a browser-tab viewer alike (cellucid-r’s cellucid_apply_session(object, request)): ask, then apply – in a notebook, in a later cell, since the viewer answers between cells:

request = viewer.request_session()
# next cell
plan = viewer.apply_session_to_anndata(adata, request)   # what would change
report = plan.apply()

tracker, branch and step choose the state applied: by default the step the viewer shows (the active tracker’s head); any step of any tracker is the state as it was after that step. Every other keyword but timeout (the wait for the session; a notebook widget’s cell cannot wait, and says so at once when the answer has not arrived) and cleanup_file (delete the session file the viewer sent once it is read and planned: the plan, and a record kept with keep_session, need it no longer; request.result().save(...) first keeps a copy) is apply_cellucid_session_to_anndata()’s.

Return type:

Any

Parameters:

adata (Any)
request (SessionRequest)
tracker (str | None)
branch (str | None)
step (str | None)
dry_run (bool)
overwrite (bool)
keep_session (bool)
timeout (float | None)
cleanup_file (bool)

debug_connection(timeout=5.0)[source]#

Return a structured connectivity/debug report for this viewer.

Includes: :rtype: dict[str, Any]

server health/info probes
exact id/path-keyed identity probes for every declared dataset
whether the viewer’s channel (its WebSocket) is connected
Python→viewer ping/pong roundtrip over the channel
frontend debug snapshot (URL/origin/userAgent as seen by the iframe)
recent_events["command_errors"]: the commands the viewer refused instead of applying

Parameters:: timeout (float | None)
Return type:: dict[str, Any]

clear_web_cache()[source]#

Clear this viewer’s selected web UI cache.

Return type:: Path

ensure_web_ui_cached(*, force=True, show_progress=True)[source]#

Establish one complete verified web build in this viewer’s cache.

Parameters:

force (bool)
show_progress (bool)

property server_url: str#: Get the data server URL.

property viewer_url: str#: Get the full viewer URL with anndata flag.

display()[source]#

Say where the viewer is: a link to its browser tab in a notebook, its address on the console otherwise.

This viewer runs in a browser tab of its own (the page and its channel are served by this machine). To show a viewer inside a notebook cell, use show_anndata() or cellucid.jupyter.Widget.

send_message(message)[source]#

Send one command to the viewer.

This is the low-level API for sending commands to the frontend. The command travels on the viewer’s channel (a WebSocket the viewer opens to this server). Before the viewer has connected – the cell output is still loading, or the page is reconnecting – the command waits and is sent, in order, the moment it connects.

An action whose parameters hold NumPy arrays (cells as uint32 original positions, a column’s values) travels as one binary frame, the arrays little-endian; every other command as JSON text. Use act() (or an action’s own method) for actions: it checks the parameters by the catalogue and returns the request its answer completes.

Parameters:: message (dict) – Dict with the command’s exact keys (the shared protocol’s commands).
Return type:: bool
Returns:: True when the command was sent now, False when it is waiting for the viewer to connect.

Example:

viewer.send_message({"type": "freeze"})

stop()[source]#

Stop the data server and cleanup all resources.

This method: 1. Stops the underlying data server (which removes its served store’s scratch folder) 2. Removes the viewer from the active viewers set 3. Clears all hooks 4. Logs the cleanup

Safe to call multiple times after a successful stop.

Action methods (generated)#

Every action of the catalogue, as a method of both classes. They are generated from the catalogue the package ships (scripts/generate_actions.py, never written by hand), so this list is exactly the viewer’s actions.

class cellucid.jupyter.ViewerActions[source]#

Bases: object

Every action of the catalogue as a method (mixed into the viewer).

analysis_cancel(*, analysis, in_='panel')[source]#

Stop an analysis.

Stop a running analysis; what it was showing stays, nothing else changes.

Action analysis.cancel. It reads only and changes nothing; request.result() is what it reads.

Parameters:

analysis ({"markers", "differential", "dotplot", "signature", "composition", "correlation"}) – An analysis with a Run button.
in ("panel" or int) – Default 'panel'.
in_ (Literal['panel'] | int)

Returns:

The request, sent at once (or as soon as the viewer connects). In a notebook widget its answer arrives once the cell has finished: collect it in a later cell.

Return type:

Viewer classes (Jupyter objects you control from Python)#

Fast path#

A) Any AnnData, in a notebook#

B) A Cellucid-ready AnnData (written by prepare()), in a browser tab#

Practical path (what you can do with a viewer)#

1) Register hooks (viewer → Python)#

2) Drive the UI from Python (Python → viewer)#

3) Robust scripts: wait for readiness#

4) Pull results, or capture a session#

5) The history: turns, changes, sessions loaded#

6) Read and change the data mapping#

Lifecycle and cleanup (important)#

API reference#

Widget#

AnnDataViewer#

Action methods (generated)#

ActionRequest, ActionError and OMIT#

SessionRequest#

LiveHistory and LoadSessionRequest#

Edge cases (do not skip)#

Not running in a notebook#

Re-running cells#

Waiting in a notebook cell#

Callbacks and exceptions#

Troubleshooting (symptom → diagnosis → fix)#

Symptom: “viewer.display() prints a URL instead of showing a viewer”#

Symptom: “Hooks never fire”#

Symptom: “I have too many running servers”#

See also#

B) A Cellucid-ready AnnData (written by `prepare()`), in a browser tab#

`Widget`#

`AnnDataViewer`#

`ActionRequest`, `ActionError` and `OMIT`#

`SessionRequest`#

`LiveHistory` and `LoadSessionRequest`#

Symptom: “`viewer.display()` prints a URL instead of showing a viewer”#