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.

Tutorials

Comprehensive tutorials that walk through complete workflows:

Scanpy-Squidpy Xenium Pancreas - Full analysis workflow using Scanpy and Squidpy with Xenium data
Chromium Pre-process - Pre-processing Chromium single-cell RNA-seq data
Single-cell Clustergram Chromium - Creating clustergram visualizations for single-cell data
Visium-HD Landscape Pre-process - Pre-processing Visium HD data for Landscape visualization

Brief Notebooks

Focused examples demonstrating specific features:

Landscape View Xenium - Basic Landscape visualization of Xenium data
Landscape-Heatmap Visium-HD - Combined Landscape and heatmap visualization
UMAP-Cluster Pancreas Xenium - UMAP clustering with Xenium pancreas data
Visium-HD Landscape Mouse Lung - Visium HD visualization example
Custom Segmentation - Using custom cell segmentation with Celldega
NeighborhoodCollection Population Space - Creating a neighborhood collection and calculating a neighborhood-by-population modality
Gradient Neighborhood Pancreas Islets - Building inward/outward gradient rings around pancreatic islets and profiling cell-type proportion and hormone expression with distance from the islet edge
DatasetCollection Population Space - Creating toy dataset-level data and calculating dataset-by-population modalities
Yearbook-Query - Using single-cell Yearbook view

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: