Skip to content

Clustergram

Clustergram uses hierarchical bi-clustering to organize both axes of a high-dimensional matrix: genes/features by their expression patterns, and cells, clusters, neighborhoods, or samples by their similarity. The heatmap or dot plot makes these relationships visible alongside dendrograms.

For single-cell expression, a common workflow starts by identifying cell groups with tools such as Scanpy's Leiden clustering. Celldega can summarize expression within those groups, then hierarchically cluster the genes and groups to explore marker programs and relationships between cell populations.

Loading an interactive preview…

Interactive preview: top marker genes of 180 Tabula Sapiens cell types. Color shows mean expression scaled per gene; dot size shows the fraction of cells expressing the gene. Use DIM to change the number of markers per cell type. Data: Tabula Sapiens Consortium, via CZ CELLxGENE Discover · CC BY 4.0.

Reading a Clustergram

A Clustergram arranges a matrix so that similar rows sit next to each other, and so do similar columns. In the marker dot plot below, rows are genes and columns are Leiden clusters of peripheral blood mononuclear cells (PBMCs). Each mark's color shows a gene's mean expression in a cluster, scaled across clusters: red is above the gene's average and blue is below. Its size shows the fraction of the cluster's cells that express the gene. The dendrograms on the right and bottom show how genes and clusters were grouped, so blocks of red reveal marker programs: B-cell genes such as CD79A in cluster 1, platelet genes such as PPBP and PF4 in cluster 8, and NK-cell genes such as GZMB and NKG7 in cluster 4.

Clustergram of PBMC marker genes with numbered callouts

Marker genes of nine PBMC clusters, five per cluster, as a dot plot.

Control What it does
1 COL / ROW Order each axis (CLUST, SUM, VAR, or INI), and cut its dendrogram with the slider.
2 DIM Choose how many genes to show, from views precomputed in Python; here, five markers per cluster.
3 CROP · UNDO · PROP · UNIT Crop to a region and undo the crop; switch dot-plot marks between proportional and full size.
4 Category bars Count the categories in view, such as clusters. Hover a bar to highlight its rows or columns.
5 Search Find a gene and zoom to it. The box below describes a clicked gene.
6 Celldega logo Opens this page.
7 Column labels Cluster names, above a colored strip for each column category.
8 Row labels Gene names. Hover for a description; click to send the gene to linked views.
9 Matrix One mark per gene and cluster. Hover for its values.
10 Dendrograms The row (right) and column (bottom) clustering trees. Hover or click a branch to select its group.

Many of these interactions build on Clustergrammer (Fernandez et al., Scientific Data, 2017), whose interaction guide describes the original designs. For stacked cell-type proportions across groups, use Composition.

Motivation for Clustergram and Matrix

We usually describe Clustergrams with cells and genes, but the analysis is generic: any matrix of observations and dimensions can be explored this way.

Clusters of observations and of dimensions

Graph-based clustering, such as Scanpy's Leiden clustering, assigns each cell to a cluster but does not show how the clusters relate to each other or which genes they share. A Clustergram hierarchically clusters both axes. Clustering the Leiden clusters' expression signatures gives a meta-clustering that groups related clusters, such as T-cell subtypes. Clustering the genes finds programs of co-expressed genes, such as the NK-cell cytotoxicity genes above, and shows which cell groups share them.

A viewer for a DataFrame or an AnnData

dega.clust.Matrix prepares a pandas DataFrame or an AnnData for hierarchical bi-clustering: it holds the values, the row and column annotations, the clustering, and any precomputed views. A Clustergram displays a Matrix, so you can think of it as an interactive viewer for your DataFrame or AnnData, with clustering on both axes.

Observations as columns

A Clustergram shows observations as columns and dimensions as rows, the transpose of AnnData's observations × variables:

AnnData Clustergram
Observations (obs_names): cells, clusters, samples Columns
Variables (var_names): genes, proteins Rows
obs columns, such as leiden or sample Colored strips above the columns
var columns Colored strips beside the rows
X The matrix, transposed

Observations usually carry more annotations than dimensions: cluster, sample, condition, cell type, and so on. With observations as columns, each annotation becomes a horizontal band of color above the matrix, and a stack of horizontal bands is easier to read than a row of vertical ones. Celldega transposes for you when it reads an AnnData and when it saves a Matrix.

Views of marker-gene rankings

Scanpy's rank_genes_groups ranks marker genes for each cluster, and a marker plot usually shows one choice of how many genes to include. Celldega precomputes views at several levels, such as 1, 3, 5, and 10 markers per cluster, each clustered on its own. The DIM slider then lets you move between them interactively. See views at different feature resolutions.

Dot size: the fraction of cells expressing a gene

Matrix(adata, groupby="leiden") summarizes cells by group: color is the group's mean expression, and dot size is the fraction of its cells with expression greater than zero, as in Scanpy's dot plots. A gene can have a high mean because a few cells express it strongly, or because most cells express it moderately; dot size tells these apart. See the marker-gene dot plot example.

Saving the results in AnnData

AnnData has no standard place for hierarchical clustering of observations and variables. When you save a clustered Matrix with Matrix.write_zarr, Celldega stores the dendrograms, node orders, views, and colors in an ordinary AnnData Zarr store under Celldega-specific keys (uns["celldega"], obsm["celldega_nodes"], and varm["celldega_nodes"]). Python and the browser can both reopen the same store without reclustering. Separately, for a single-cell Landscape, Celldega reads cell-level expression from a CSC copy of the expression matrix, which lets the browser fetch one gene at a time. See File Formats for both layouts.

Beyond cells and genes

The same methods cluster any observations and dimensions. The Atera breast cancer neighborhoods tutorial clusters tissue neighborhoods by their cell-type composition, and the Scanpy–Squidpy Xenium pancreas tutorial clusters cell types by their neighborhood enrichment.

Zooming and panning

Scroll to zoom and drag to pan. When a Clustergram has many more rows than columns, zooming first spreads the rows apart until the marks are about square, then zooms both axes. Scrolling over the labels or dendrograms zooms from that edge of the matrix. You cannot zoom out beyond the whole matrix.

Zooming into the rows, panning, and zooming back out

Scrolling spreads the rows apart first, then zooms both axes; dragging pans; scrolling back out returns to the whole matrix.

Hovering for details

Hovering shows information without changing anything:

  • A mark: its gene, column, value, and, in a dot plot, its size.
  • A gene label: the protein name and a description from UniProt, for human gene symbols.
  • A dendrogram branch: the members of that group (dimming the rest).
  • A category tile: its category, with matching tiles highlighted.

Tooltip over a dot-plot mark

The platelet gene PPBP in cluster 8: its scaled mean expression (value) and the fraction of cells expressing it (size).

UniProt description of PPBP in a row-label tooltip

Hovering a gene label shows its UniProt name and description.

Reordering rows and columns

The COL and ROW dropdowns order each axis by CLUST (the dendrogram), SUM (total value), VAR (variance), or INI (the original order). The reordering is animated so that you can follow the rows and columns. Dendrograms appear only in CLUST order.

Double-click a gene's label to sort the columns by that gene, from highest to lowest; the label turns blue and COL reads CUSTOM. Double-click a column label to sort the genes by that column, or double-click a category title, such as leiden beside the strip, to group that axis by category.

Reordering the columns by GZMB and the rows by SUM

Double-clicking GZMB sorts the clusters by its expression (NK cluster 4 first); ROW → SUM sorts the genes by total; CLUST restores the dendrogram order.

Dendrograms

Each dendrogram slider sets where its tree is cut into groups. While you drag it, a preview draws the whole tree over the matrix, with a blue cut line and the number of groups. Release the slider, or press Esc, to hide the preview. The slider is unavailable while that axis is cropped.

Dragging the row dendrogram slider

Moving the ROW slider cuts the gene tree into more or fewer groups.

Hover a branch, the gray trapezoids along the right and bottom, to see its members and dim everything else. Click it to select the group: a gene group colors linked cells by the genes' combined expression and can be sent to Enrich. Click it again to clear the selection. Double-click a branch to crop to that group, and double-click again to restore the axis.

Hovering, selecting, and cropping to a dendrogram branch

Hover the platelet branch to see its genes, click to select it, double-click to crop to it, and double-click again to restore the rows.

Categories

Colored strips beside the labels show each row's or column's categories, such as its Leiden cluster. The category bars in the control panel count the categories in view. When an axis has more than one category, choose which to show from the dropdown. Hover a bar or a strip tile to highlight the matching rows or columns.

To annotate interactively, create the Clustergram with manual_col_cat="cell_type" (or manual_row_cat). Clicking a column's category tile then opens an editor where you can name its category and choose a color, for example to label each cluster with a cell type. The annotations are available in Python as cgm.manual_cat.

Cropping

Click CROP, then drag a rectangle over the matrix to keep only the rows and columns inside it. CROP stays unavailable until you click UNDO, which restores the whole matrix. To crop one axis to a dendrogram group, double-click its branch.

Cropping with CROP and a dragged rectangle, then UNDO

CROP, then drag a rectangle: the Clustergram keeps the monocyte, platelet, and NK-cell genes across all clusters. UNDO restores the matrix.

Changing the number of dimensions

When a Matrix has precomputed views (see views at different feature resolutions), the DIM (dimensions) slider steps through them, ending with all rows. The readout shows the level, such as 5/clust for five marker genes per cluster; hover it to see how the genes were ranked. Each view is clustered on its own, so the order of the columns can change.

Moving the DIM slider from one to fifty marker genes per cluster

Stepping DIM from 1 to 50 marker genes per cluster (9 to 310 genes), then back to 5. Each view is clustered on its own.

Proportional or full-size marks

In a dot plot, PROP sizes each mark by its size value, such as the fraction of cells expressing the gene. UNIT draws every mark at full size, keeping the colors, which makes weak or rare expression easier to compare.

Switching between proportional and full-size marks

UNIT draws full-size marks, revealing weak and negative values; PROP restores sizes by the fraction of cells expressing each gene.

Searching

Type a gene name in the search box and press Enter, or choose it from the suggestions. The Clustergram zooms to the gene and bolds its label. Searching does not select the gene; click its label to send it to linked views.

Searching for GZMB and then CD79A

Searching for GZMB, then CD79A: the Clustergram zooms to each gene and bolds its label.

Linking to other visualizations

Linked to a Landscape, CellCloud, or NeighborhoodCloud, and to Enrich, a Clustergram drives the other views:

In the Clustergram Landscape or CellCloud Enrich
Click a gene label Colors cells by that gene; click again to return to clusters —
Click a column label Selects that cluster's cells Receives the column's top marker genes
Click a column dendrogram branch Selects those clusters' cells —
Shift-click column labels Selects those clusters' cells (shift-click again to remove one) Receives their top marker genes
Click a row dendrogram branch, or crop rows Colors cells by the genes' combined expression Receives those genes
Shift-click gene labels Colors cells by the genes' combined expression Receives those genes
Click a mark Colors cells by that gene within that cluster —

Selecting an Enrich term turns its genes' labels blue in the Clustergram, and clicking a gene in Enrich zooms the Clustergram to it. Shift-clicked labels are blue too, until a plain click starts over. With dega.viz.spatial_clustergram, the clusters highlighted in the Landscape (from its cluster bars, a Clustergram click or a Clerk link) turn their column labels blue (cgm.highlighted_cols); other Landscape selections do not change the Clustergram. See Landscape–Clustergram–Enrich for a complete linked example.

Widget: Python-backed interactions

As a notebook widget, a Clustergram also shares its state with Python:

  • Selections: cgm.selected_genes, cgm.selected_rows, and cgm.selected_cols hold the latest selection; cgm.enrichment_genes holds the gene set sent to Enrich; and cgm.click_info describes the last click.
  • Annotations: categories assigned in the manual category editor are in cgm.manual_cat.
  • Updates from Python: for example, cgm.viz_mode = "heatmap" switches a dot plot to a heatmap. cgm.apply_state({...}) sets controls by name: marker_level (the DIM slider, or "all"), mode ("heatmap" / "dotplot"), size ("prop" / "unit"), focus_gene (zoom to a gene, like the search box), and categories (see below).
  • Annotations from Python: cgm.set_categories({"4": "Goblet cells", "5": "Plasma cells"}) labels columns in the manual category, exactly as the editor would; the strips, bars and cgm.manual_cat update. Pass axis="row" for rows, attribute=... to choose or create the category, colors={...} for colors, and replace=True to clear the axis's other labels first.
  • State queries: cgm.request_state() asks the browser what is shown (rows and columns on screen, order, marker level, dendrogram groups, attributes, selection, values); cgm.request_state(markers={"clusters": ["4"], "n": 25}) also returns a cluster's ranked rank_genes_groups markers. Read cgm.latest_state in a later cell.
  • Images: cgm.request_raster() captures the heatmap (with its labels and category strips) as a PNG, like the Landscape's; read cgm.raster_png (and the cgm.raster_thumb preview) in a later cell. Captures stay in memory and are never saved into the notebook. In JavaScript, matrix.capture_raster() returns the same.
  • Snapshots: cgm.snapshot(description="...", name="...") saves the screenshot together with a memo and reproducibility metadata in a PNG that can be reopened. See Snapshots.
cgm = dega.viz.Clustergram(matrix=mat, manual_col_cat="cell_type")
cgm
# After clicking a dendrogram branch and labeling some clusters:
cgm.selected_genes
cgm.manual_cat

Links made with dega.viz.spatial_clustergram and dega.viz.clustergram_enrich run in the browser, so they keep working in a notebook report without a kernel. Links to a Yearbook use Python and need a running kernel.

Usage

This example assumes that adata.X already contains prepared expression values. Filtering and normalization are explicit:

import celldega as dega

mat = dega.clust.Matrix(adata)
mat.filter("row", by="var", num=min(5000, adata.n_vars))
mat.norm("row", by="zscore")
mat.cluster()

cgm = dega.viz.Clustergram(matrix=mat)
cgm

Row z-scoring emphasizes each gene's relative expression across the columns. For large single-cell datasets, summarize cells into groups as below before hierarchically clustering the columns.

Advanced usage

A marker-gene dot plot after Leiden clustering

Assume that adata.obs["leiden"] holds the first-round cell labels and adata.X contains nonnegative, log-normalized expression, before cell-level z-scoring. This example requires celldega[scanpy].

import scanpy as sc
import celldega as dega

# Rank markers using the same expression values that will be summarized.
sc.tl.rank_genes_groups(adata, groupby="leiden", use_raw=False)

# Columns become Leiden groups; rows remain genes.
markers = dega.clust.Matrix(adata, groupby="leiden")
markers.filter_by_size(0.05)
markers.norm("row", by="zscore")
markers.cluster(
    view="rank_genes_groups",
    levels=[1, 3, 5, 10, 25],
)

dotplot = dega.viz.Clustergram(matrix=markers, rank_dim=5)
dotplot

Before row z-scoring, the color matrix is each group's mean expression. Dot size is the fraction of its cells with expression greater than zero. filter_by_size(0.05) keeps genes detected in at least 5% of cells in at least one group; row z-scoring changes the color values while preserving those fractions. A Matrix carrying size values opens as a dot plot automatically.

Matrix reuses matching rank_genes_groups results. Alternatively, pass rank_genes_groups=True when constructing the Matrix to calculate missing rankings. See Scanpy's marker-ranking documentation and aggregation documentation for the underlying operations.

Generate views at different feature resolutions

cluster(view=..., levels=...) keeps the full matrix and precomputes smaller feature sets. Each set is independently clustered on both axes, so the column order can change as different gene programs come into focus.

view How rows are chosen Meaning of a level
"rank_genes_groups" Union of each group's top-ranked marker genes Markers per group
"var" Highest row variance Total rows
"sum" Highest row sum Total rows
"mean" Highest row mean Total rows

In the dot-plot example, level 5 means up to five markers per Leiden group. Shared markers are counted once, so the total displayed rows may be less than 5 × number of groups. The DIM slider switches among the computed levels and all, which restores the full matrix.

Metric views also work without marker rankings, including bulk and other high-dimensional data. For example, compare the most variable genes across Leiden-group means:

variable = dega.clust.Matrix(
    adata,
    groupby="leiden",
    rank_genes_groups=False,
)
variable.cluster(view="var", levels=[100, 500, 1000])

heatmap = dega.viz.Clustergram(
    matrix=variable,
    viz_mode="heatmap",
    rank_dim=500,
)
heatmap

Metric rankings use the Matrix's current values. Use un-z-scored normalized values for variance views: row z-scoring makes row variances equal. Choose levels smaller than the feature count. Levels that select the whole matrix, too few rows, or duplicate another feature set are omitted.

One Matrix stores one view family at a time. Build separate Matrices to compare marker-ranked and variance-ranked views. rank_dim chooses the initial level; it does not compute a new view. The browser switches among precomputed levels.

Save the clustered views

markers.write_zarr("marker_dotplot.zarr")
restored = dega.clust.Matrix.read_zarr("marker_dotplot.zarr")
reopened = dega.viz.Clustergram(matrix=restored, rank_dim=5)

The store preserves values, optional dot sizes, metadata, dendrograms, precomputed views, colors, and marker rankings. See Matrix storage for what is saved before and after clustering, and File Formats for the AnnData Zarr schema and JavaScript readers.

Examples and source code

Link a Clustergram to a Landscape, CellCloud, or NeighborhoodCloud with dega.viz.spatial_clustergram. Gene clicks color cells by expression, and group selections highlight their corresponding cells.

The Chromium PBMC tutorial demonstrates marker dot plots and saved Matrix stores. The Visium HD tutorial demonstrates linked Landscape, Clustergram, and Enrich views.

For constructor options, see the Viz API. Source: Matrix clustering and views, Clustergram widget, and browser view controls.

Screenshot sources

Screenshots and animations show the PBMC 3k marker dot plot that the Chromium PBMC tutorial saves with Matrix.write_zarr (pbmc3k_leiden_markers.zarr), from 10x Genomics PBMC 3k data. They were captured with Celldega 0.28.0 using scripts/docs_screenshots/capture.py.