JavaScript API Overview
Use Celldega in a web page to explore prepared datasets without a Python kernel. The same Landscape and Clustergram views used in notebooks can read hosted DegaFiles or AnnData Zarr directly.
Quick start
Serve the page and the built celldega.js module over HTTP. This example
opens a spatial Landscape; replace base_url with your dataset's DegaFiles URL.
<!doctype html>
<html lang="en">
<body>
<div id="landscape"></div>
<script type="module">
import celldega from "./celldega.js";
const landscape = await celldega.landscape(
document.getElementById("landscape"),
{
base_url: "https://your-data-host/DegaFiles",
width: 900,
height: 600,
},
);
</script>
</body>
</html>
For a single-cell UMAP/XY Landscape, use zarr_url and zarr_layer instead.
For a saved clustered Matrix, use clustergram(element, {url}).
Main APIs
| Function | Purpose |
|---|---|
landscape(element, options) |
Spatial tissue and low dimensional embedding landscapes |
clustergram(element, options) |
Heatmap or dot plot from a network, DegaFiles, or a saved Matrix Zarr |
from_png(element, file, options) |
Reopen an exported PNG as an interactive visualization using its saved source and state |
read_png(file) / snapshot_png(snapshot) |
Read embedded Snapshot metadata / export a Snapshot as a PNG |
link_models(source, key, target, key) |
Link selections between visualizations |
anndata_zarr_source(url, options) |
Cell-level Zarr metadata and per-gene expression reader |
network_from_zarr(url) |
Restore a saved Matrix's browser visualization network |
Each Landscape and Clustergram these return can also be read and driven from code:
get_state() reports what it shows, apply_state() changes it, and capture_raster()
captures its image. See the Viz API, which web apps and AI agents can use
to inspect a view, show evidence, and keep a reproducible picture of it.
See the API reference for complete options and a linked Landscape/Clustergram example. Lower-level renderers remain available for custom integrations.
Data and hosting
- Spatial Landscapes use image pyramids, cell metadata, transcript/boundary tiles, and expression in DegaFiles.
- Single-cell Landscapes use AnnData Zarr with a CSC expression matrix.
- Clustergrams can read the complete clustered Matrix AnnData Zarr format.
- Cross-origin hosting must allow browser requests. Row-group DegaFiles also require HTTP byte ranges.
See File Formats for the layouts, and the Gallery for live examples.
Development
To add controls or embed Celldega in an application, see State management: where a visualization's state lives, how the observable store works, and how a change becomes a deck.gl redraw.