Skip to content

Jupyter Notebook Examples

These example notebooks demonstrate how to use Celldega for spatial transcriptomics analysis and visualization. Each notebook is designed to be run in a Jupyter environment and showcases different features of the library.

Spatial Transcriptomics Tutorials

Comprehensive tutorials that walk through complete workflows:

  • Atera Kidney Landscape-Clustergram - Direct Scanpy and AnnData steps for default clusters, linked dotplot Clustergrams, and cell-type composition across podocyte-defined glomerular gradients
  • Atera Breast Cancer Landscape-Clustergram - Loads a precomputed Scanpy clustering (or optionally recomputes it) and creates linked Landscape, Clustergram, and Enrich widgets
  • Atera Breast Cancer Neighborhood Exploration - Continues the Atera tutorial with hextile niches linked to cell-type composition and alpha-shape overlap linked to a separate Landscape
  • Visium HD Human CRC Landscape-Clustergram-Enrich - Uses Scanpy and plain AnnData to summarize a clustered Visium HD colorectal cancer sample (signatures, fraction expressing, marker genes) and explores it in linked Landscape, Clustergram, and Enrich widgets, ready for interactive annotation
  • Scanpy-Squidpy Xenium Pancreas - Full analysis workflow using Scanpy and Squidpy with Xenium data
  • Preprocess DegaFiles and Viz Pancreas - Preprocessing raw Xenium Pancreas data into DegaFiles and visualizing the result in a Landscape widget
  • Chromium PBMC Landscape-Clustergram-Enrich - Downloads a 10x PBMC count matrix, clusters cells with Scanpy, and uses plain AnnData for expression signatures, fraction expressing, and marker-ranked Clustergram views linked to a UMAP Landscape and Enrich, plus a single-cell Clustergram linked to Enrich
  • Broad-Allen Dev Mouse Brain E15.5 Align - Aligns 43 Xenium sections of an E15.5 mouse brain (3.8M cells, 480 genes) into a 3D stack in two steps, Leiden cluster centroids then neighborhood (alpha-shape) overlap, and shows how to write CellCloud DegaFiles
  • Broad-Allen Dev Mouse Brain E15.5 Viz - Visualizes the aligned E15.5 brain as a 3D CellCloud linked to the cluster composition of every slice and to a gene-expression Clustergram

Brief Notebooks

Focused examples demonstrating specific features:

Running the Notebooks

Prerequisites

Install Celldega and its dependencies:

pip install celldega

For full analysis workflows, you may also need:

pip install scanpy squidpy

Embedding interactive widgets in the docs

The docs are rendered statically by mkdocs-jupyter, which displays saved widget state but does not execute notebooks. For an interactive Landscape / Clustergram (anywidget) to appear on the docs site, the notebook's saved widget state must be complete and its model IDs must match the cell outputs.

A plain "Run All + Save" in Jupyter Lab is unreliable for this: each Landscape streams a large message (the embedded JS bundle plus the data parquet), and the state is only captured if the widget has fully finished rendering in the browser before you save. Editing a cell and saving without a full re-execution leaves stale or missing state, and the widgets render blank.

The reliable way to (re)build a docs notebook so its widgets embed is to execute it headless with a raised iopub_timeout so those large messages aren't dropped:

jupyter nbconvert --to notebook --execute --inplace \
  --ExecutePreprocessor.timeout=900 \
  --ExecutePreprocessor.iopub_timeout=120 \
  docs/examples/brief_notebooks/<Notebook>.ipynb

Tips:

  • Put each widget as the only expression in its own cell (separate from its construction) — anywidget embeds most reliably that way.
  • Don't add %env ANYWIDGET_HMR=1 to a docs notebook. That dev-time hot-reload watches and reloads the widget's frontend module; running it while the frontend bundle is being rebuilt can desync the saved model IDs from the cell outputs.
  • To confirm a notebook is good, check that every application/vnd.jupyter.widget-view+json model_id in the cell outputs also exists in metadata.widgets["application/vnd.jupyter.widget-state+json"].state.

Online Resources

You can also run Celldega notebooks in the cloud: