Skip to content

Python API Overview

Use Celldega to prepare visualization data, summarize analysis results, and explore them in linked widgets. It fits downstream of single-cell and spatial workflows such as Scanpy and Squidpy: most analysis functions accept standard AnnData, MuData, and GeoDataFrame objects.

You can start with these objects directly. Celldega's collection classes are useful when you want to keep several feature spaces, metadata, and relationships organized around the same datasets, neighborhoods, or cell sets.

How the modules support the visualizations

Celldega's interactive visualizations support human-in-the-loop analysis: you explore, select, and annotate in the browser. The Python modules perform the analysis behind those views. They prepare data, cluster it, define neighborhoods, organize higher-level biological entities, choose cells to review, and align serial sections in 3D. Each produces something a visualization displays:

 Your analysis (AnnData, MuData, GeoDataFrame)
   │
   ├─ pre ─────────► DegaFiles ──────► Landscape, Yearbook, CellCloud
   ├─ clust ───────► Matrix ─────────► Clustergram, Composition
   ├─ nbhd ────────► neighborhoods ──► Landscape, NeighborhoodCloud, Clustergram
   ├─ collections ─► summaries ──────► Clustergram, Composition
   ├─ select ──────► selections ─────► Yearbook
   └─ align ───────► 3D coordinates ─► CellCloud, NeighborhoodCloud
  • clust hierarchically bi-clusters genes and cell groups, and precomputes views at several numbers of genes, for Clustergrams.
  • nbhd creates tissue neighborhoods (alpha shapes, hextiles, gradients) and calculates their attributes, such as cell-type composition and expression. Neighborhoods display in Landscape and NeighborhoodCloud; their summaries cluster into Clustergrams.
  • Collections (collection, dataset, set) are data structures for higher-level biological entities, such as neighborhoods, samples, and sets of cells, that keep several feature spaces together.
  • select chooses and ranks cells for review in Yearbook.
  • align quickly aligns serial sections into 3D coordinates for CellCloud and NeighborhoodCloud.
  • pre turns instrument output into DegaFiles that the browser loads a piece at a time.

Results flow back too: selections, drawn neighborhoods, and annotations made in a widget are available to these modules for the next step of the analysis.

Choose a module

Module What you use it for Main inputs and results
pre Prepare instrument output for browser visualization Instrument files → DegaFiles; optional aligned H&E; point-cloud and neighborhood-cloud writers
viz Display and link interactive views Prepared spatial data, analysis objects, or saved matrices → notebook widgets
clust Find patterns through hierarchical bi-clustering Expression or other feature matrices → clustered Matrix, heatmaps, and dot plots
nbhd Define spatial neighborhoods and summarize their contents Cell coordinates and polygons → neighborhood geometry, expression, composition, and relationships
collection Store multiple feature spaces on one observation axis MuData-backed CelldegaCollection, the shared base for collection classes
dataset Compare samples or datasets Cell-level data → DatasetCollection with sample metadata, population composition, and signatures
set Represent and compare groups defined by cell membership Cell labels → SetCollection, signatures, composition, and overlap
select Choose, rank, and sample observations Metadata/expression queries → an ordered Selection for inspection or visualization
align Register tissue slices in physical space Landmarks and cell coordinates → reusable transforms and aligned coordinates
qc Inspect segmentation and transcript-assignment quality Instrument output and segmentation assignments → summary and gene-level QC metrics

Start with an example

  • Single-cell expression: Chromium PBMC combines Scanpy analysis with UMAP/XY Landscapes, marker dot plots, and Enrich using clust and viz.
  • Spatial analysis: Scanpy–Squidpy Xenium Pancreas connects cell clustering and spatial neighborhood enrichment to interactive views.
  • Neighborhoods: Atera breast cancer neighborhoods uses nbhd, clust, and viz for hextile niches and cell-type composition.
  • Preparing your own data: Atera preprocessing turns an instrument output bundle into DegaFiles with pre, then opens a Landscape.

See Installation for Python dependencies and optional extras, and Usage for the preparation and hosting workflow.

pre: prepare data for visualization

pre writes the files that let the browser load large spatial datasets a piece at a time: image pyramids, cell metadata, tiled transcripts and boundaries, per-gene expression, and a visualization manifest. pre.main handles Xenium (including Atera) and MERSCOPE output bundles. Other technologies and custom data use the appropriate readers and lower-level writers described in the reference.

Use pre.add_aligned_he to add an already aligned histology background, or pre.write_point_cloud_dataset and pre.write_nbhd_cloud_dataset for the 3D views. CellCloud also accepts AnnData Zarr written with pre.write_point_cloud_zarr; see the two export formats. Preparing DegaFiles is separate from clustering an AnnData for analysis.

Examples: Atera preprocessing, custom segmentation, and adding aligned H&E. Reference: pre API and DegaFiles layout.

viz: explore and connect results

viz creates the interactive notebook widgets. Landscape shows tissue data or low dimensional embedding landscapes (UMAP/XY); Yearbook compares cell portraits; CellCloud and NeighborhoodCloud show 3D spatial data. Clustergram compares expression and other measurements, Composition compares category proportions or counts, and Enrich interprets a gene set.

Link them with viz.spatial_clustergram or viz.clustergram_enrich so that a selection in one view updates the others.

Examples: Atera kidney combines Landscape, Clustergram, Yearbook, and Composition; Visium HD colorectal cancer connects Landscape, Clustergram, and Enrich. Reference: widget guides and viz API.

clust: hierarchically cluster high-dimensional data

clust.Matrix prepares a feature matrix for hierarchical bi-clustering: filter features, normalize values, cluster both axes, and precompute different views. For single-cell expression, Matrix(adata, groupby="leiden") summarizes clusters identified in an earlier analysis, using mean expression for color and the fraction of expressing cells for dot size.

Display the result with viz.Clustergram. Save a complete clustered object with Matrix.write_zarr and restore it with Matrix.read_zarr, including its metadata, dendrograms, colors, marker rankings, and precomputed views.

Examples: Chromium PBMC and Atera breast cancer. Reference: clust API and advanced Clustergram usage.

nbhd: define and analyze neighborhoods

nbhd builds alpha shapes around cell groups, regular hextile grids, and inward/outward gradients around a region. Its functions summarize neighborhood expression and cell-type composition and calculate overlap or bordering relationships. Geometry is represented by a GeoDataFrame; summaries are AnnData or MuData objects that can be clustered and visualized.

Use NeighborhoodCollection when you want to store geometry, feature modalities, and neighborhood relationships together. Compute summaries with the nbhd functions and attach their results to the collection.

Examples: Atera breast cancer neighborhoods and pancreas islet gradients. Reference: nbhd API.

CelldegaCollection is the common MuData-backed storage model used by the collection classes. One observation axis can have several feature modalities, shared annotations, pairwise relationships, and provenance. For example, the same neighborhoods can have both gene-expression and cell-population summaries. The collection stores these results; analysis and visualization functions use them.

Example: Pancreas islet gradients stores gradient geometry, population and expression summaries, and a bordering relationship in a NeighborhoodCollection. Reference: collection model and API.

dataset: summarize samples and cohorts

DatasetCollection makes samples or datasets the observations. Build it from cell-level metadata, retain sample annotations such as patient and condition, and calculate population composition or expression signatures for comparison across samples. Store the feature spaces as modalities and persist the collection as MuData.

Examples and reference: DatasetCollection construction, population summaries, signatures, and persistence. For interactive comparisons of group composition, see the Composition guide.

set: compare groups defined by membership

SetCollection represents groups of cells without requiring spatial geometry. Its membership matrix records exactly which cells belong to each set. Use it to summarize cluster labels or algorithm-defined groups, compare their expression and composition, and quantify overlap between different groupings. concat_sets combines collections for cross-grouping comparisons.

Examples and reference: SetCollection membership, signatures, overlap, and persistence. Display its feature modalities with Matrix and Clustergram.

select: query and sample observations

select.Selector combines metadata and gene-expression filters with reproducible sampling or ranking. It returns a Selection: ordered observation IDs plus information about the query and sampling method. Use it to choose representative cells, inspect high-expression cells, or drive a Yearbook without manually assembling ID lists.

Examples and reference: Selector queries and samplers and choosing cells for Yearbook.

align: register tissue coordinates

align provides a landmark-based serial-slice workflow: calculate landmarks, fit rigid or thin-plate-spline transforms, inspect the fit, and apply the transforms to cell positions or other points in the same coordinate system. Save a fitted transform for reuse, then write the aligned coordinates as point-cloud DegaFiles for CellCloud. These are transformations of physical coordinates; expression-space integration remains part of the upstream analysis.

Reference: alignment API. Notebook: Broad–Allen mouse-brain preprocessing and alignment, followed by CellCloud visualization. Visualization example: aligned developing mouse brain in 3D. For importing an already aligned image, use the separate aligned H&E workflow.

qc: assess segmentation and transcript assignment

qc computes metrics such as the fraction of assigned transcripts, cell counts, cell areas, and gene-level assignment statistics. Use these to inspect instrument segmentations or compare a custom segmentation before interpreting the resulting expression measurements. qc_segmentation writes summary and gene-level CSV files.

Reference: segmentation QC API. For the related preparation workflow, see the custom segmentation example; that notebook demonstrates importing a segmentation, rather than running QC.