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 marker-gene dot plot, pass a cell-level AnnData with groupby. Matrix aggregates the cells with scanpy.get.aggregate (mean expression drives color, the fraction of cells expressing drives dot size) and reuses scanpy's rank_genes_groups results for the RANK slider's marker views:

import scanpy as sc

sc.tl.rank_genes_groups(adata, groupby="leiden")
mat = dega.clust.Matrix(adata, groupby="leiden")
mat.norm("row", by="zscore")
mat.cluster(view="rank_genes_groups", levels=[1, 3, 5, 10, 25, 50])
cgm = dega.viz.Clustergram(matrix=mat)

Pass rank_genes_groups=True (or a dict of sc.tl.rank_genes_groups keyword arguments) to compute the ranks on the fly, and layer= to aggregate a layer instead of X. The same groupby path works for samples or any other cell grouping.

With whole-transcriptome data, consider dropping genes that almost no cells detect before the row z-score. The z-score measures how specific a gene is to a cluster, not how many cells express it, so a gene detected in a single cell of a single cluster gets the same top value as a real marker and can crowd the full-gene view. filter_by_size() keeps rows whose size (here, the fraction of cells expressing) reaches a threshold in at least one column:

mat = dega.clust.Matrix(adata, groupby="leiden")
mat.filter_by_size(0.05)  # detected in at least 5% of some cluster's cells
mat.norm("row", by="zscore")

Precomputed modalities in a MuData can drive color and size directly:

mat = dega.clust.Matrix(mdata=mdata, color_by="expression", size_by="fraction")

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().

Saving a clustered Matrix (experimental)

write_zarr() saves a clustered Matrix, including its dendrograms, views, colors, attributes, and size matrix, as an AnnData Zarr store. read_zarr() restores it without re-clustering, so it can go straight to a Clustergram:

mat.cluster(view="rank_genes_groups")
mat.write_zarr("pbmc_markers.zarr")

cgm = dega.viz.Clustergram(matrix=dega.clust.Matrix.read_zarr("pbmc_markers.zarr"))

The store has the Clustergram's columns as observations and its rows as variables, so anndata.read_zarr opens it too. Values are saved as float32 by default; pass dtype=None to keep the Matrix's own precision. In a browser, the JavaScript matrix_from_zarr renders the same store without Python.

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 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, *, groupby=None, layer=None, rank_genes_groups=None, mdata=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
groupby	str | None	With a cell-level AnnData data, aggregate cells into groups by this obs column (e.g. "leiden", a sample or dataset column) with scanpy.get.aggregate: columns become groups, color is the mean expression, and dot size is the fraction of cells expressing each feature (a dot plot). Group colors come from uns[f"{groupby}_colors"]. Requires scanpy.	None
layer	str | None	With groupby, aggregate this layer instead of X.	None
rank_genes_groups	bool | dict[str, Any] | None	With groupby, where marker ranks (for cluster(view="rank_genes_groups")) come from. None (default) reuses adata.uns["rank_genes_groups"] when it was computed for the same groupby; True also runs scanpy.tl.rank_genes_groups when there are none; a dict runs it with these keyword arguments; False skips marker ranks.	None
mdata	Any	A MuData (or any object exposing .mod) to build data from, in place of passing data directly — equivalent to data=mdata.mod[color_by]. Requires color_by.	None
color_by	str | None	Modality key on mdata driving color/opacity (the main matrix).	None
size_by	str | None	Optional modality key on mdata 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(mdata.mod[size_by]) after construction. Omit for a matrix with no size channel.	None
size_by_layer	str | None	Optional layer driving the secondary size channel, on mdata.mod[color_by] or on an AnnData data. 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")

Marker dot plot straight from a cell-level AnnData

sc.tl.rank_genes_groups(adata, groupby="leiden") mat = Matrix(adata, groupby="leiden") mat.cluster(view="rank_genes_groups")

Dot plot from MuData modalities

mat = Matrix(mdata=mdata, color_by="expression", size_by="fraction")

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 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 scanpy.tl.rank_genes_groups (see Matrix(adata, groupby=...)). "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 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 DEFAULT_VIEW_LEVELS. Levels that resolve to the whole matrix, to fewer than 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 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 an AnnData'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 export_viz_parquet instead.

export_viz_json_string()

Export visualization as JSON string.

.. deprecated:: 0.10 Use 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 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

filter_by_size(min_size, axis='row')

Keep rows (or columns) that reach min_size in the size matrix.

With the fraction of cells expressing each gene as the size matrix (see set_size_matrix), mat.filter_by_size(0.05) keeps genes detected in at least 5% of the cells of at least one cluster.

Optional, but recommended for whole-transcriptome data before a row z-score: the z-score measures how specific a gene is to a column, not how many cells express it, so a gene detected in a single cell of a single cluster gets the same top value as a real marker.

Parameters:

Name	Type	Description	Default
min_size	float	Value that a row's (or column's) largest size must reach.	required
axis	AxisInput	'row'/'col', 0/1, or Axis enum: filter rows by their largest size across columns, or columns by their largest size across rows.	'row'

from_clustered_adata(adata) classmethod

Restore a clustered Matrix from to_clustered_adata's AnnData.

Nothing is re-clustered: dendrograms, orders, views, and colors are read back as saved, so the result can go straight to Clustergram(matrix=...).

Raises:

Type	Description
ValueError	If adata does not hold a supported clustered Matrix.

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

read_zarr(store) classmethod

Read a clustered Matrix written by write_zarr (experimental).

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 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 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 cut_tree.

to_clustered_adata(*, dtype=None)

Package the clustered Matrix as an AnnData, ready to write to Zarr.

The AnnData has the Clustergram's columns as observations and its rows as variables (the orientation Matrix(adata) reads): matrix values in X, the optional size matrix in layers["size"], dendrogram orders in obsm/varm["celldega_nodes"], and linkages, views, colors, attributes, and entities in uns["celldega"]. from_clustered_adata restores the Matrix without re-clustering.

Parameters:

Name	Type	Description	Default
dtype	Any	Data type of X and the size layer. Defaults to the Matrix's own.	None

Raises:

Type	Description
ValueError	If the Matrix has not been clustered.

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

write_zarr(store, *, dtype='float32', zarr_format=3)

Write the clustered Matrix to an AnnData Zarr store (experimental).

The store keeps everything a Clustergram needs: read_zarr loads it back without re-clustering for Clustergram(matrix=...), and the JavaScript matrix_from_zarr renders it in a browser. It is also a regular AnnData store that anndata.read_zarr opens.

Parameters:

Name	Type	Description	Default
store	Any	Path or zarr store to write to.	required
dtype	Any	Data type of the matrix values and size layer. Defaults to float32, the precision the Clustergram displays; None keeps the Matrix's own.	'float32'
zarr_format	int	Zarr format version, 3 (default) or 2.	3

Examples:

>>> mat.cluster(view="rank_genes_groups")
>>> mat.write_zarr("pbmc_markers.zarr")
>>> cgm = Clustergram(matrix=Matrix.read_zarr("pbmc_markers.zarr"))

compute_marker_ranks(adata, groupby, rank_genes_groups_kwargs=None, stacklevel=3)

Run scanpy.tl.rank_genes_groups and return tidy, rank-annotated results.

Used by Matrix(adata, groupby=..., rank_genes_groups=True) so marker ranking happens against cell-level data before the signature is aggregated.

Cost is dominated by scanpy: the default "wilcoxon" test runs at roughly 30 ms per gene on 200k cells ("t-test" is about 3x faster), scaling linearly in genes. Restricting adata to the genes you actually intend to display is the most effective lever.

Parameters:

Name	Type	Description	Default
adata	Any	Cell-level AnnData carrying groupby in obs.	required
groupby	str	obs column defining the groups to compare.	required
rank_genes_groups_kwargs	dict[str, Any] | None	Extra keyword arguments for scanpy.tl.rank_genes_groups; method defaults to "wilcoxon".	None
stacklevel	int	Warning stacklevel, so the too-few-groups warning points at the caller's caller rather than in here.	3

Returns:

Type	Description
DataFrame | None	A tidy frame with group/names/scores/logfoldchanges/
DataFrame | None	pvals/pvals_adj/rank, or None when there are fewer than
DataFrame | None	two groups to compare.

marker_ranks_from_uns(payload)

Recover a tidy marker-rank frame from an uns payload.

Accepts what marker_ranks_to_uns wrote, and also scanpy's own in-place uns["rank_genes_groups"] structure (per-group columns in a structured array), so an AnnData that already had sc.tl.rank_genes_groups run on it works without any celldega-specific preparation.

Returns None for anything it doesn't recognize, so callers can probe uns keys without guarding each shape themselves.

marker_ranks_to_uns(markers)

Serialize a tidy marker-rank frame for AnnData.uns.

Stored column-wise as plain lists so it survives an h5ad round trip, unlike a DataFrame.

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"}