Skip to content

Clust Module API Reference

Matrix preserves supplied values during construction. For general standalone datasets, filtering and normalization are explicit operations, so the data transformations remain visible in the notebook:

import celldega as dega

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

For a SetCollection signature, the main expression matrix and a same-shaped size channel can be selected without creating a second signature modality:

mat = dega.clust.Matrix(
    collection=setc,
    color_by="expression",
    size_by_layer="fraction_expressing",
)
mat.norm("row", by="zscore")
mat.cluster(view="rank_genes_groups", levels=[1, 3, 5, 10, 25, 50])

cluster() is the canonical clustering method and returns self for chaining. It accepts one optional view; the full matrix remains available when reduced views are precomputed. Use cut_tree() to turn either dendrogram into flat labels, providing exactly one of n_clusters or threshold.

The older clust(), views=, dot_plot, dot_mat, set_dot_matrix(), and to_cluster() interfaces are deprecated compatibility aliases. New code should use cluster(), view=, size_by_layer / size_matrix / set_size_matrix(), and cut_tree().

This module provides the main Matrix class for hierarchical data clustering and visualization.

AxisEntity

Bases: TypedDict

Describes what entity a clustergram axis represents.

Attributes:

Name Type Description
entity str

The type of entity (cell, gene, nbhd, cluster, etc.)
attr str

The attribute of that entity (name, leiden, custom_column, etc.) - For cells: 'leiden' means cell clusters, 'name' means individual cells - For nbhd: 'name' means specific neighborhoods - For genes: typically 'name'

Examples:

Clustergram with cell clusters on rows (cells grouped by leiden)

{"entity": "cell", "attr": "leiden"}

Clustergram with specific cells on columns

{"entity": "cell", "attr": "name"}

Clustergram with neighborhoods on columns

{"entity": "nbhd", "attr": "name"}

Clustergram with genes on rows

{"entity": "gene", "attr": "name"}

Hextile neighborhoods by cell clusters

row: {"entity": "cell", "attr": "leiden"} col: {"entity": "hextile", "attr": "nbhd_cluster"}

EntityType

Bases: Enum

Entity types that can be represented in clustergram rows/columns.

Matrix

High-performance matrix class for explicit transformations and hierarchical clustering.

Construction preserves supplied values. Filtering and normalization are explicit operations, followed by hierarchical clustering and visualization export. Uses intelligent caching for performance with large datasets.

Examples:

Preserve an already-prepared matrix

mat = Matrix(adata) mat.cluster()

Explicit preprocessing for a general dataset

mat = Matrix(adata, global_colors={"high": "red", "low": "blue"}) mat.filter("row", by="var", num=5000) mat.norm("row", by="qn")

dat property

Lazy dat structure with intelligent caching.

dot_mat property writable

Deprecated alias for :attr:size_matrix.

__init__(data=None, meta_col=None, meta_row=None, col_attr=None, row_attr=None, row_entity='gene', col_entity='cell_cluster', global_colors=None, name=None, *, collection=None, color_by=None, size_by=None, size_by_layer=None, dot_plot=None)

Create a Matrix while preserving the supplied values.

Parameters:

Name Type Description Default
data DataFrame | AnnData | None

DataFrame or AnnData object

 None
meta_col DataFrame | None

Column metadata (for DataFrame input)

 None
meta_row DataFrame | None

Row metadata (for DataFrame input)

 None
col_attr list[str] | None

Column attribute names (categorical or numeric)

 None
row_attr list[str] | None

Row attribute names (categorical or numeric)

 None
row_entity str | dict | AxisEntity | None

Entity specification for rows. Accepted formats: - str: Shorthand with implicit attr mapping: - "gene" → {"entity": "gene", "attr": "name"} - "nbhd" → {"entity": "nbhd", "attr": "name"} - "cell" → {"entity": "cell", "attr": "name"} - "hextile" → {"entity": "hextile", "attr": "name"} - "cell_cluster" or "cluster" → {"entity": "cell", "attr": "leiden"} - tuple: Compact format, e.g., ("nbhd", "name") - dict: Full format, e.g., {"entity": "nbhd", "attr": "name"}

 'gene'
col_entity str | dict | AxisEntity | None

Entity specification for columns (same formats as row_entity)

 'cell_cluster'
global_colors dict[str, str] | DataFrame | None

Global category color mapping (dict or DataFrame with 'color' column)

 None
name str | None

Name for the matrix (default: None)

 None
collection Any

A Celldega collection (SetCollection/DatasetCollection/etc.) to build data from, in place of passing data directly — equivalent to data=collection.mod[color_by]. Requires color_by.

 None
color_by str | None

Modality key on collection driving color/opacity (the main matrix).

 None
size_by str | None

Optional modality key on collection driving the secondary size channel (dot-plot size, e.g. fraction of cells expressing — but any per-cell magnitude works, e.g. significance) — equivalent to calling .set_size_matrix(collection.mod[size_by]) after construction. Omit for a matrix with no size channel.

 None
size_by_layer str | None

Optional layer on collection.mod[color_by] driving the secondary size channel. This is the compact path for a signature created with fraction_expressing_layer. Mutually exclusive with size_by and dot_plot.

 None
dot_plot str | None

Deprecated alias for size_by (pass either, not both).

 None

Examples:

Preserve already-prepared values (default)

mat = Matrix(adata)

Explicit preprocessing for a general standalone dataset

colors = {"Cancer": "#ff0000", "Normal": "#0000ff"} mat = Matrix(adata, global_colors=colors) mat.filter("row", by="var", num=5000) mat.norm("row", by="qn")

Dot plot directly from a SetCollection, no manual DataFrame wrangling

setc.calc_signature( adata, modality_name="expression", fraction_expressing_layer="fraction_expressing", ) mat = Matrix( collection=setc, color_by="expression", size_by_layer="fraction_expressing", )

Raw matrix without data

mat = Matrix() # Empty matrix for manual loading

With entity specifications for widget interaction:

Genes (rows) by cell clusters (columns) - typical gene expression heatmap

mat = Matrix(df, row_entity="gene", col_entity="cell_cluster")

Or equivalently with new format:

mat = Matrix(df, row_entity={"entity": "gene", "attr": "name"}, col_entity={"entity": "cell", "attr": "leiden"})

Neighborhoods by cell types

mat = Matrix(df, row_entity={"entity": "cell", "attr": "leiden"}, col_entity={"entity": "nbhd", "attr": "name"})

add_category(axis, name, data)

Add category to metadata.

Parameters:

Name Type Description Default
axis AxisInput

'row'/'col', 0/1, or Axis enum (0/ROW=rows, 1/COL=columns)

 required
name str

Category name

 required
data Series

Category values (must match axis length)

 required

add_cats(axis, cat_data)

Add multiple categories to metadata.

Parameters:

Name Type Description Default
axis AxisInput

'row'/'col', 0/1, or Axis enum

 required
cat_data dict[str, Any]

Dict with category name as key, values as list/Series/dict

 required

Examples:

Add multiple categories at once

mat.add_cats('col', { 'cell_type': ['T-cell', 'B-cell', 'NK-cell'], 'treatment': ['control', 'treated', 'control'] })

From existing metadata

mat.add_cats('col', meta_df.to_dict('series'))

clust(dist_type='cosine', linkage_type='average', force=False, views=None, levels=None)

Deprecated alias for :meth:cluster.

cluster(dist_type='cosine', linkage_type='average', force=False, view=None, levels=None, *, views=None)

Perform hierarchical clustering.

Parameters:

Name Type Description Default
dist_type DistanceType

Distance metric ('cosine', 'euclidean', 'correlation')

 'cosine'
linkage_type LinkageType

Linkage method ('average', 'complete', 'ward')

 'average'
force bool

Override size limits for large matrices

 False
view str | None

Precompute reduced-dimensionality views, each independently re-biclustered, and drive them from the Clustergram's RANK slider. One of:

  • "rank_genes_groups": each cluster's top markers, unioned. Needs differential expression carried by the input AnnData, normally from SetCollection.calc_signature(..., rank_genes_groups=True).
  • "var" / "sum" / "mean": rows ranked by a per-row metric on the matrix itself — no differential expression needed, which is the right fit for bulk or otherwise ungrouped matrices.
 None
levels list[int] | None

Slider stops to precompute. The unit depends on the view:

  • "rank_genes_groups": top markers per cluster, so level 10 means each cluster's 10 best markers unioned (deduplicated, so the row count is at most n_clusters * 10). Defaults to :data:~celldega.clust.constants.DEFAULT_MARKER_VIEW_LEVELS. Counting per cluster rather than in total means you don't have to divide a row budget by however many clusters you happen to have.
  • metric views: total rows kept, since those rankings are global with no groups to divide by. Defaults to :data:~celldega.clust.constants.DEFAULT_VIEW_LEVELS.

Levels that resolve to the whole matrix, to fewer than :data:~celldega.clust.constants.MIN_VIEW_ROWS rows, or to rows a finer level already covered are dropped. The full matrix is always available as the slider's "all" stop.

 None

Examples:

>>> mat.cluster()                                        # no view
>>> mat.cluster(view="rank_genes_groups")                # top K per cluster
>>> mat.cluster(view="rank_genes_groups", levels=[3, 5]) # 3 and 5 per cluster
>>> mat.cluster(view="var", levels=[10, 50, 200])        # 10/50/200 rows

cut_tree(axis='row', n_clusters=None, threshold=None, criterion=None)

Cut the dendrogram into flat cluster labels.

Cuts the hierarchical clustering linkage (computed by :meth:cluster) along one axis and returns a label per row/column. Use n_clusters to request a fixed number of clusters (fcluster with criterion="maxclust") or threshold to cut at a linkage distance (criterion="distance"). Exactly one of the two must be given. criterion can override the inferred SciPy criterion, but it does not replace the cut value.

This is the programmatic counterpart to the Clustergram's interactive dendrogram slider: it turns a clustered Matrix into discrete groups (e.g. consensus domains, meta-clusters) that can be attached back to a collection's obs / var.

Parameters:

Name Type Description Default
axis AxisInput

"row"/"col" (or 0/1) — which dendrogram to cut.

 'row'
n_clusters int | None

Target number of flat clusters (maxclust criterion).

 None
threshold float | None

Linkage-distance cutoff (distance criterion).

 None
criterion str | None

Explicit scipy fcluster criterion; overrides the n_clusters/threshold inference when given (paired with whichever of the two is supplied as t).

 None

Returns:

Type Description
Series

A pd.Series of integer cluster labels indexed by the axis names
Series

(data.index for rows, data.columns for columns), in data order.

Raises:

Type Description
ValueError

If the matrix is unclustered, the linkage is empty, or not exactly one of n_clusters or threshold is provided.

downsample_to(category='leiden', axis='col', propagate_metadata=False)

Downsample data by aggregating categories using scanpy.get.aggregate.

Parameters:

Name Type Description Default
category str

Metadata column to aggregate by

 'leiden'
axis AxisInput

Which axis to aggregate ('col'/1/COL for cells, 'row'/0/ROW for genes)

 'col'
propagate_metadata bool | list[str]

Whether to propagate other metadata columns to the aggregated result using the modal (most frequent) value per group. - False: Skip metadata propagation (fast, default) - True: Propagate all metadata columns (slow for large datasets) - list[str]: Propagate only specified columns

 False

Requires: scanpy for aggregation functionality

Note

Uses scanpy.get.aggregate under the hood for fast mean aggregation. See: https://scanpy.readthedocs.io/en/stable/generated/scanpy.get.aggregate.html

Examples:

>>> mat = Matrix(adata)
>>> mat.downsample_to("leiden")

export_viz_json()

Export visualization as JSON dict.

.. deprecated:: 0.10 Use :meth:export_viz_parquet instead.

export_viz_json_string()

Export visualization as JSON string.

.. deprecated:: 0.10 Use :meth:export_viz_parquet instead.

export_viz_parquet()

Export visualization using Parquet encoded tables.

export_viz_to_widget(which_viz='viz')

Export visualization for widget.

.. deprecated:: 0.10 Use :class:celldega.viz.Clustergram with matrix instead.

filter(axis, by, num)

Filter features by specified metric.

Parameters:

Name Type Description Default
axis AxisInput

'row'/'col', 0/1, or Axis enum (0/ROW=rows, 1/COL=columns)

 required
by FilterType

Metric ('var' for variance, 'mean' for mean)

 required
num int

Number of top features to keep

 required

load_adata(adata, col_attr=None, row_attr=None)

Load AnnData object.

Parameters:

Name Type Description Default
adata AnnData

AnnData object (will be transposed to genes x cells)

 required

load_df(df, meta_col=None, meta_row=None, col_attr=None, row_attr=None)

Load DataFrame with metadata.

Parameters:

Name Type Description Default
df DataFrame

Data matrix

 required
meta_col DataFrame | None

Column metadata (must match df.columns)

 None
meta_row DataFrame | None

Row metadata (must match df.index)

 None
col_attr list[str] | None

Column attribute names for viz (categorical or numeric)

 None
row_attr list[str] | None

Row attribute names for viz (categorical or numeric)

 None

make_viz()

Generate visualization data structure.

norm(axis, by)

Normalize data along specified axis.

Parameters:

Name Type Description Default
axis AxisInput

'row'/'col', 0/1, or Axis enum (0/ROW=rows, 1/COL=columns)

 required
by NormType

Normalization method ('total', 'zscore', 'qn')

 required

random_subsample(axis, num, seed=42)

Randomly subsample features.

Parameters:

Name Type Description Default
axis AxisInput

'row'/'col', 0/1, or Axis enum (0/ROW=rows, 1/COL=columns)

 required
num int

Number of features to sample

 required
seed int

Random seed for reproducibility

 42

set_cat_color(axis, cat_index, cat_name, color)

Set color for specific category value in a specific category column.

Parameters:

Name Type Description Default
axis AxisInput

'row'/'col', 0/1, or Axis enum

 required
cat_index int

Category column index (1-based, like original Network)

 required
cat_name str

Category value name to color

 required
color str

Hex color string or named color

 required
Example

Set color for 'Cancer' in the first column category

mat.set_cat_color('col', 1, 'Cancer', '#ff0000')

set_cat_colors(axis, cat_index, color_mapping)

Set colors for multiple category values in a specific category column.

Parameters:

Name Type Description Default
axis AxisInput

'row'/'col', 0/1, or Axis enum

 required
cat_index int

Category column index (1-based)

 required
color_mapping dict[str, str]

Dict mapping category values to colors

 required
Example

Set colors for multiple values in tissue type category

mat.set_cat_colors('col', 1, { 'Liver': '#00ff00', 'Brain': '#ffff00', 'Heart': '#ff00ff' })

set_dot_matrix(dot)

Deprecated alias for :meth:set_size_matrix.

set_global_cat_colors(color_mapping=None)

Set global category color mapping that applies across all categories.

Parameters:

Name Type Description Default
color_mapping dict[str, str] | DataFrame | None

Dict mapping category values to colors, DataFrame with 'color' column, or None to auto-generate

 None
Note

If metadata has a 'color' column, those colors will be used automatically.

set_matrix_colors(pos='red', neg='blue')

Set matrix color scheme for positive and negative values.

Parameters:

Name Type Description Default
pos str

Color for positive values (hex or named color)

 'red'
neg str

Color for negative values (hex or named color)

 'blue'
Example

mat.set_matrix_colors(pos="#ff0000", neg="#0000ff")

set_size_matrix(size)

Attach a secondary matrix that drives size encoding.

The values are interpreted as a per-cell size channel (typically the fraction of cells in a cluster expressing a gene, in [0, 1]) that is rendered as square/dot size in a dot-plot :class:~celldega.viz.Clustergram, independently of the main matrix which continues to drive color/opacity and the clustering order.

The size matrix is aligned to the main matrix by row and column name at export time, so it does not need to share the clustered ordering — only the same labels. Missing entries become 0 (no dot).

Parameters:

Name Type Description Default
size DataFrame | ndarray | AnnData | Matrix

A DataFrame indexed by row names with columns of column names, a 2D array matching the main matrix shape/order, an AnnData (X with obs_names rows / var_names cols), or another Matrix.

 required

Returns:

Type Description
Matrix

self (to allow chaining, e.g. Matrix(df).set_size_matrix(frac)).

subset(axis, by)

Subset data by feature list.

Parameters:

Name Type Description Default
axis AxisInput

'row'/'col', 0/1, or Axis enum (0/ROW=rows, 1/COL=columns)

 required
by list[str]

List of feature names to keep

 required

to_adata()

Convert to AnnData object.

to_cluster(axis='row', n_clusters=None, threshold=None, criterion=None)

Deprecated alias for :meth:cut_tree.

to_df()

Return DataFrame copy of data.

write_dega_files(path, name=None)

Write Clustergram visualization data to a DegaFiles directory.

This creates a cgm/ subdirectory containing the parquet files needed to load the Clustergram in JavaScript without a Python backend.

Parameters

path : str or Path Path to the DegaFiles directory (the same directory used for Landscape and Yearbook data). name : str, optional Name for this Clustergram. If provided, files are saved to cgm/{name}/. If None, uses the matrix's name attribute, or "default" if no name is set.

Examples

mat = Matrix(adata) mat.cluster() mat.write_dega_files("./my_dega_files", name="skin_cancer_clusters")

JavaScript can then load from:

base_url + '/cgm/skin_cancer_clusters/'

Notes

The following files are created: - mat.parquet: The matrix data - row_nodes.parquet: Row node information - col_nodes.parquet: Column node information - row_linkage.parquet: Row dendrogram linkage - col_linkage.parquet: Column dendrogram linkage - meta.json: Metadata including colors and config

normalize_axis_entity(value)

Normalize an axis entity specification to the AxisEntity format.

Handles backwards compatibility with string-only entity values and supports compact tuple format.

Parameters:

Name Type Description Default
value str | tuple | dict | AxisEntity | None

Entity specification - can be: - str: Shorthand format with implicit attr (see mapping below) - tuple: Compact format (entity, attr) e.g., ("nbhd", "name") - dict/AxisEntity: Full format with entity and attr keys - None: Returns default {"entity": "gene", "attr": "name"}

 required
String Shorthand Mapping

When a string is provided, the following implicit attr values are used: - "gene" → {"entity": "gene", "attr": "name"} - "nbhd" → {"entity": "nbhd", "attr": "name"} - "cell" → {"entity": "cell", "attr": "name"} - "hextile" → {"entity": "hextile", "attr": "name"} - "cell_cluster" or "cluster" → {"entity": "cell", "attr": "leiden"} - any other string → {"entity": , "attr": "name"}

Returns:

Type Description
AxisEntity

AxisEntity with entity and attr keys

Examples:

String shorthand (attr is implicit)

>>> normalize_axis_entity("gene")
{"entity": "gene", "attr": "name"}

>>> normalize_axis_entity("nbhd")
{"entity": "nbhd", "attr": "name"}

>>> normalize_axis_entity("cell_cluster")
{"entity": "cell", "attr": "leiden"}

Tuple format (explicit entity and attr)

>>> normalize_axis_entity(("nbhd", "name"))
{"entity": "nbhd", "attr": "name"}

>>> normalize_axis_entity(("cell", "leiden"))
{"entity": "cell", "attr": "leiden"}

Dict format (most explicit)

>>> normalize_axis_entity({"entity": "cell", "attr": "leiden"})
{"entity": "cell", "attr": "leiden"}