Skip to content

Viz API: getters, setters and exporters

Landscape and Clustergram expose an initial API for reading and changing views from code. Support varies by widget and control. Three kinds of methods cover this:

  • Getters report what a visualization shows right now, as plain JSON: the space and camera, what is selected or highlighted, which clusters and genes are on screen, and the values behind them.
  • Setters change what it shows, as its controls would: select clusters, color by genes, zoom to cells, move the Clustergram's marker level, label columns.
  • Snapshots combine a screenshot (raster image), memo and metadata for reproducibility, in memory or as a PNG. See Snapshots.

get_state() returns bounded scientific observations. get_replay_state() returns complete inputs for supported controls, without those observation caps. Only the latter can be passed directly to apply_state(); saved views use it automatically. Saved settings replay the supported parts of a view on widgets with the same data. from_png can construct a fresh visualization from an exported PNG's source references and restore those settings. Use Portable Snapshots to capture image and state together and validate data identity before restoring supported settings; some controls remain outside replay coverage.

The API uses corresponding operations in a web page (JavaScript) and a notebook (Python). It was built for Clerk, Celldega's AI assistant, but it doesn't depend on it: any web app, script or AI agent can use it to read a view, reason about it, show the evidence it finds, and save it.

JavaScript (web page) Python (notebook widget)
Get viz.get_state(options) returns the state widget.request_state(...), then widget.latest_state
Replay inputs viz.get_replay_state() widget.latest_snapshot["state"] after capture
Set await viz.apply_state(changes) widget.apply_state(changes), then widget.get_apply_result(widget.apply_request_id)
Raster viz.capture_raster(options) returns a PNG widget.request_raster(), then widget.raster_png
Capture Snapshot await viz.snapshot(options) widget.request_snapshot(...), then widget.latest_snapshot
Save Snapshot celldega.snapshot_png(snapshot) returns a PNG Blob widget.snapshot(description, path, name="...") writes PNG + Markdown
Notebook postcard — dega.viz.Snapshot(landscape=landscape, snapshot="name")
Restore await viz.restore_snapshot(saved) widget.restore_snapshot(saved), then widget.get_apply_result(request_id)
Open PNG await celldega.from_png(el, file, options) dega.viz.from_png(path, **options), then display the widget
Read PNG metadata await celldega.read_png(file) dega.viz.load_snapshot(path)

In Python, every request is answered asynchronously: the browser's reply reaches Python only after the calling cell finishes. Read latest_state, raster_png or get_apply_result(...) in a later cell, or observe the traits. Live-view capture traits are not synced into notebook widget state. A displayed Snapshot postcard embeds its PNG, memo and metadata so the card can be shared.

Design rules the API follows:

  • Scientific meaning, not interface details. State names clusters, genes, spaces and marker levels, not buttons or DOM elements.
  • Input validation. Unknown settings and invalid input are rejected; in Python, in the calling cell. Runtime failures, such as unavailable data, can still leave a partial change. Python apply_state returns what it submitted, not completion; the browser's acknowledgement says whether it was applied.
  • Same paths as the controls. Setting clusters behaves like clicking cluster bars, setting genes like the gene search, and so on, so linked widgets update as usual.
  • Only what you pass changes. Setting categories changes the labels you name and leaves the others alone, unless you ask to replace them all.

Landscape

celldega.landscape(el, options) returns the Landscape object these methods are on (see the API reference). CellCloud and NeighborhoodCloud support the same state and Snapshot APIs; their view also supports orbit rotation.

get_state(options)

What the Landscape shows. options.max_bars caps the per-cluster and per-gene counts (25 by default).

{
  "kind": "landscape",
  "space": "spatial",
  "view_state": {"target": [5120.5, 3988.0, 0], "zoom": -2.3},
  "color_by": "cluster",
  "selected_clusters": ["4"],
  "selected_genes": [],
  "selected_cells": 0,
  "viewport": {
    "clusters": [{"name": "4", "value": 1203}, {"name": "5", "value": 980}],
    "genes": [{"name": "MUC2", "value": 512}]
  }
}
  • space: "spatial", "umap" or "xy".
  • color_by: "cluster", a gene, or "GENE1 + GENE2" for several genes.
  • viewport: values shown by the cluster and gene bar charts. In UMAP/XY, gene_summary records whether genes are a viewport estimate (mode: "estimate"), whole-dataset values with all cells visible ("whole"), or a whole-dataset fallback ("dataset"); it also records scope, known units and status. Without this metadata, do not assume the gene values are measured within the current field of view.

apply_state(changes)

Returns a promise of short descriptions of what changed, for example ["highlighted clusters 4", "zoomed to clusters 4"].

Key Value Like
space "spatial", "umap" or "xy" the SPATIAL / UMAP / XY buttons
clusters cluster names; [] clears the selection clicking (and shift-clicking) cluster bars
genes gene names (up to 20); [] returns to cluster colors the comma-separated gene search
zoom_to {"clusters": [...]} or {"cells": [...]} framing those cells (spatial view; in 3D for orbit clouds, at any camera rotation)
view {"target": [x, y, z], "zoom": z}; orbit views also accept rotationOrbit, rotationX moving/rotating the camera
selected_cells exact cell IDs; [] clears them selecting cells
xy {"genes": ["GENE1", "GENE2"], "scale": "linear"}; 0–2 genes, scale linear or log1p XY axes and scaling
reset_view true the initial view
layers booleans for image, cells, transcripts, neighborhoods IMG / CELL / TRX / NBHD visibility
channels {channelName: {visible, intensity}} image channel toggles and sliders; intensity is 0–100
sliders {cell, nbhd, trx: {size, opacity}} layer size/opacity sliders; only available sliders are accepted
image_source "primary" or "he" the image source selector; H&E must be available
await landscape.apply_state({ clusters: ['4'], zoom_to: { clusters: ['4'] } });
await landscape.apply_state({ genes: ['MUC2', 'TFF3'] });
await landscape.apply_state({
  layers: { image: true, cells: false },
  channels: { DAPI: { visible: true, intensity: 35 } },
});

get_state() returns these four layer fields in the same shape. Channel visibility is preserved independently of the master image toggle. Cell and neighborhood slider values range from 0–100. Transcript opacity ranges from 0–150; size uses the dataset's slider range (100 times its transcript size scale). Both transcript modes are saved, including the inactive mode. Older single-mode transcript sliders use trx: {value: ...} instead. Fields describe the available controls, so do not assume every dataset exposes the same channels or layers.

When xy_genes is empty at construction, XY starts with the two genes with the highest whole-dataset mean expression (X first, Y second). Ties keep dataset gene order; genes without finite mean statistics follow those with statistics, in dataset order. A one-gene dataset initializes X only. Explicit constructor axes take precedence, and later edits or Snapshot restores—including empty axes—are preserved. The default uses loaded metadata and fetches expression only when XY is entered.

capture_raster(options)

The view's image (a raster): {png, thumb, width, height, view_state}, where png and thumb are base64 PNGs (no data: prefix). options.max_size and options.thumb_size set their longest side in pixels (1024 and 192 by default). It captures the visualization itself, not the control panel. Areas it leaves empty are white; options.background sets another CSS color, or null keeps them transparent. snapshot(options) takes the same option.

Clustergram

celldega.clustergram(el, options) returns the Clustergram object these methods are on.

get_state(options)

What the Clustergram shows. Options:

Option Default Meaning
rows, cols "viewport" which rows/columns to describe: "viewport" (on screen), "ranked" (the top of the current order), or a list of names
max_rows, max_cols 50 cap on rows/columns described
extra_rows, extra_cols [] names to add even if off screen (e.g. genes being asked about)
include_values true include the values (and dot sizes) for the described rows and columns
markers none {"clusters": ["4"], "n": 25}: each cluster's top-n ranked markers (rank_genes_groups), whatever the marker level shows

The result has, per axis (rows, cols), the names described, which of them were added, missing names, counts, the current order, attributes (e.g. leiden, cell_type) and dendrogram groups. It also has:

  • marker_level: the marker level (the DIM slider) and the levels available;
  • cluster_markers: with the markers option, [{cluster, genes: [{name, rank, value, size}]}];
  • display: mode, size and focused_row;
  • selection: the current click, selected genes, dendrogram group and crop;
  • values: {values, sizes} for the rows by columns described;
  • view: {target: [x, y], zoom: [xZoom, yZoom]} for the matrix camera;
  • crop: {row: [...names] | null, col: [...names] | null}; null means uncropped. An axis cropped to more than 100 names is left out (its count is in selection.crop);
  • order: {row, col} for axes in a named order. An explicit order (custom, or by an attribute) is left out here and labeled in rows.order / cols.order.

Every field is bounded, so the result stays small enough for an agent's prompt. The complete settings, including every name of an explicit order or crop, come from get_replay_state() and saved views.

const state = clustergram.get_state({ rows: 'ranked', max_rows: 25 });
const markers = clustergram.get_state({
  markers: { clusters: ['4', '5'], n: 25 },
  include_values: false,
}).cluster_markers;

apply_state(changes)

Returns short descriptions of what changed, for example ["DIM -> 10 markers per cluster"].

Key Value Like
marker_level markers per cluster, or "all" the DIM slider
mode "heatmap" or "dotplot" the mode buttons
size "prop" or "unit" the PROP / UNIT buttons
focus_gene a row name; "" clears it the row search
categories as for set_categories the category editor
view {target: [x, y], zoom: [xZoom, yZoom]}; either field may be omitted pan and independent axis zoom; the camera constrains legal positions
crop {row: [...names] \| null, col: [...names] \| null} crop or undo crop for either axis
order {row, col}: "clust", "rank", "rankvar", "ini", "alpha", or all axis names in display order reorder controls; only orders available in the matrix are accepted

An explicit order must include every name on the axis exactly once, including names outside the crop. This preserves custom, gene-based and category-based orders without depending on the current dropdown choice. A saved explicit order restores the displayed sequence, not a live sorting rule. Order is applied before crop, and camera last, so combined restores survive the controls' usual camera resets.

clustergram.apply_state({
  order: { row: 'rank', col: 'clust' },
  crop: { col: ['4', '5'] },
  view: { zoom: [1, 2] },
});

set_categories(request)

Label rows or columns in a manual category, as the category editor would; returns how many were labeled.

clustergram.set_categories({
  axis: 'col',                 // or 'row'
  attribute: 'cell_type',      // created if needed
  values: { 4: 'Goblet cells', 5: 'Plasma cells' },   // '' removes a label
  colors: { 'Goblet cells': '#1f77b4' },              // optional
  replace: false,              // true clears the axis's other labels first
});

capture_raster(options)

The heatmap's image, with its labels and category strips: {png, thumb, width, height}, as for the Landscape.

Example: read, show, capture

A web page (or an agent driving one) can read what is on screen, show the evidence for a claim, and keep a picture of it:

import celldega from 'celldega';

const landscape = await celldega.landscape(spatial_el, { base_url });
const clustergram = await celldega.clustergram(matrix_el, { url: matrix_url });
celldega.link_models(clustergram.model, 'click_info', landscape.model, 'update_trigger');

// Get: cluster 4's top markers, and what is in the field of view.
const { cluster_markers } = clustergram.get_state({
  markers: { clusters: ['4'], n: 25 },
  include_values: false,
});
const in_view = landscape.get_state().viewport.clusters;

// Set: show cluster 4 and its top two markers.
const top = cluster_markers[0].genes.slice(0, 2).map((gene) => gene.name);
await landscape.apply_state({ zoom_to: { clusters: ['4'] }, genes: top });
clustergram.apply_state({ focus_gene: top[0] });

// Export: an image and an observation of the result (not a complete restore recipe).
const image = landscape.capture_raster({ max_size: 1024 });
const record = { state: landscape.get_state(), image: image.png };

Replaying supported settings

Use get_replay_state() for a complete supported semantic view, or snapshot() for that state together with the raster, bounded observations and provenance.

Visualization Supported replay state
Clustergram Marker level, heatmap/dotplot mode and dot-size encoding, focused row; camera target and per-axis zoom; explicit or named order and crop; dendrogram cut percentages; selected rows/columns/genes and highlighted genes; selected dendrogram group by member names; both axes' manual annotation names, assignments and colors.
Landscape Space and camera, cluster or gene coloring, selected cell IDs, XY genes/scale, layer visibility, image source, channels and sliders.
Orbit spatial views The shared Landscape controls where available, plus camera rotationOrbit and rotationX. XY is unavailable in orbit views and is rejected.
clustergram.apply_state({
  dendrogram: { row: 35, col: 65 },
  selection: { rows: ['MUC2'], cols: ['4'], highlighted_genes: ['muc2'] },
  annotations: {
    col: { attribute: 'review', values: { '4': 'supported' }, colors: { supported: '#3377cc' } },
  },
});
await landscape.apply_state({
  space: 'xy', xy: { genes: ['MUC2', 'TFF3'], scale: 'log1p' },
  selected_cells: ['cell-1', 'cell-2'],
});

annotations replaces each supplied axis's manual annotation state; null clears that axis. This updates the visualization and synced manual-category traits, not the source AnnData. categories remains the patch-oriented assignment API. Do not pass both in one operation. A saved dendrogram selection uses {axis, members} and must exist at the restored cut/crop; unavailable groups fail explicitly. apply_state also accepts {axis, name}, the group name get_state lists, which only identifies a group together with the cut it was listed at (pass that cut in dendrogram). Selection lists in replay state are uncapped, unlike the bounded observations returned by get_state.

Restore applies cuts before crop, selection after crop, and camera last. The XY setter awaits expression loading and its position animation, and exposes failures. An explicit layer restore also cancels delayed visibility resets from space changes.

Completion and errors

Every Python apply_state call sends one request, including trait-only controls. The browser validates availability, applies the requested controls and replies with applied or apply_error. The reply reaches Python only after the cell that sent the request finishes, so check it from the next cell:

cgm.apply_state({"dendrogram": {"row": 35}})
request_id = cgm.apply_request_id
cgm.get_apply_result(request_id)  # {"event": "applied", "done": [...]} or apply_error

get_apply_result returns None while pending and never substitutes another request's result; restore_snapshot returns a request id to check the same way. apply_capture_id and apply_error remain available for observers. Code that runs outside a cell, such as a background task (asyncio.ensure_future) or an application, can await cgm.apply_state_async(changes) or await cgm.wait_for_apply(request_id), which raise on failure or timeout. Awaiting them in the cell that sent the request would always time out.

JavaScript Landscape setters accept a second {timeout_ms: 30000} option. Errors and timeouts never acknowledge success; they can leave partial changes, and timeout does not cancel pending browser work. Recapture before treating the outcome as evidence. Ordinary camera/reorder style animations may still need to settle before comparing PNG pixels.

Coverage boundaries

Saved views do not bundle source data or construct a visualization. Load the matching data first. Transient hover/click history, drawn gates or edited neighborhood geometry, non-manual attribute palettes, specialized composition controls, and the constructor's 2D dataset rotation transform are outside this replay contract. Orbit camera rotation is supported. Linked visualizations have separate captures, not one atomic transaction. Scientific state equality is the primary round-trip check; exact pixels are only expected under matching canvas size, renderer, fonts, browser and GPU.

Records remain marked restoration: "partial" because of these boundaries. Older saved views only restore the fields they contain. See Portable Snapshots for identity checks, schema compatibility, and the explicit canvas-resize override.