Skip to content

CellCloud–Clustergram

Link a CellCloud and Clustergram to compare 3D cell organization with gene-expression patterns. This is useful for thick tissue or aligned serial sections, where rotating the cell cloud reveals relationships across slices.

CellCloud shows cell positions in physical space. Clustergram compares expression across cell groups; its selections update the 3D view.

What you can explore

  • Select a cell group and inspect its distribution across the 3D dataset.
  • Click a gene to see where expressing cells occur while rotating or zooming.
  • Compare the expression relationships in the Clustergram with the physical arrangement of the corresponding cells.

Before you start

Use point-cloud DegaFiles containing 3D cell positions and a matching cell-level AnnData, adata. Its obs_names must match the DegaFiles cell IDs; adata.obs["leiden"] supplies the cell-group labels used by both views.

The example assumes prepared, nonnegative expression in adata.X and uses celldega[scanpy] to summarize cells by group. Replace "leiden" in both groupby and cluster_attr to use a different cell annotation.

See the CellCloud guide for point-cloud preparation and File Formats for the layout.

Usage

Build the expression summary from the cells shown in the cloud:

import celldega as dega

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

cell_cloud = dega.viz.CellCloud(
    base_url="https://your-data-host/point_cloud_files",
    adata=adata,
    cluster_attr="leiden",
    use_adata_3d_centroids=False,
)
cgm = dega.viz.Clustergram(matrix=mat, name="cloud_clusters")

linked = dega.viz.spatial_clustergram(cell_cloud, cgm)
linked

Replace base_url with your point-cloud DegaFiles URL. use_adata_3d_centroids=False uses the saved 3D positions from DegaFiles while AnnData supplies the cell annotations. The Clustergram has genes as rows and cell groups as columns. Dot color shows row-z-scored mean expression and dot size shows the fraction of cells expressing each gene.

Use Clustergram advanced usage to prepare marker-ranked views or restore a previously saved Matrix instead.

Try the linked selections

  1. Rotate and zoom the CellCloud. Inspect the overall shape of the tissue or aligned sections.
  2. Select a cell group in the Clustergram. Its corresponding cells are highlighted in 3D.
  3. Click a gene in the Clustergram. CellCloud colors cells by expression, while you continue to rotate and zoom.
  4. Change the Clustergram's feature view. Explore a different set of genes when the Matrix includes precomputed views.

To add gene-set interpretation, pass enrich=True to the same helper:

linked_with_enrich = dega.viz.spatial_clustergram(
    cell_cloud, cgm, enrich=True
)
linked_with_enrich

See Landscape–Clustergram–Enrich for the enrichment interactions shared by these linked layouts.

Examples and reference

Source: linking helpers.