annotated_heatmap#

API pages include interactive (HTML) plots that would possibly not render correctly on a mobile device.

annotated_heatmap(data: AnnData | MuData, keys: Sequence[str], group_by: str | None = None, *, variable_group_by: str | None = None, modality: str | None = None, column_annotations: str | Sequence[str] | None = None, row_annotations: str | Sequence[str] | None = None, annotation_colors: Mapping[str, AnnotationColors] | None = None, mapping: FeatureSpec | None = None, geom: Literal['raster', 'tile'] = 'raster', layers: FeatureSpec | Sequence[FeatureSpec] | None = None, layers_all: FeatureSpec | Sequence[FeatureSpec] | None = None, scale_axis: Literal[0, 1] | None = None, transpose: bool = False, dendrogram: bool = False, group_lines: bool = True, group_lines_color: str = 'white', group_lines_size: float = 0.6, group_lines_kwargs: dict | None = None, dendrogram_color: str = 'black', dendrogram_size: float = 0.5, dendrogram_key: str | None = None, dendrogram_kwargs: dict | None = None, column_annotation_height: float = 0.025, row_annotation_width: float = 0.025, column_annotation_position: Literal['top', 'bottom'] = 'top', row_annotation_position: Literal['left', 'right'] = 'left', row_track_titles: bool = False, column_track_titles: bool = False, key_labels: Sequence[str] | None = None, group_labels: Mapping[str, str] | None = None, group_labels_width: float = 0.25, group_labels_kwargs: dict | None = None, color_low: str = '#0000ff', color_mid: str = '#ffffff', color_high: str = '#ff0000', midpoint: Literal['mean', 'median', 'mid'] | float = 'mid', max_rows: int | None = 1000, value_column: str = 'value', variable_column: str = 'variable', variable_id_column: str = 'Variable', interactive: bool = False, legend: bool = True, annotation_legends: bool = True, **geom_kwargs) → PlotSpec#

Annotated heatmap.

Parameters:

  • data (AnnData | MuData) – The single-cell data object.

  • keys (Sequence[str]) – Variable keys to include, placed on the x-axis.

  • variable_group_by (str | None, default None) – Variable metadata key whose contiguous blocks (over keys in order) are separated by group lines, like group_by for observations. Drawn with the group_lines_* styling; needs group_lines.

  • modality (str | None, default None) – Which modality’s stored analysis results to use when markers or dendrogram is enabled. Required for a multimodal object holding more than one modality, and not accepted otherwise.

  • group_by (str | None, default None) – The observation key to group the rows by. When None, rows keep their original order and no group separators are drawn.

  • column_annotations (str | Sequence[str] | None, default None) – Variable metadata key(s) to draw as tracks above the heatmap.

  • row_annotations (str | Sequence[str] | None, default None) – Observation metadata key(s) to draw as tracks to the left of the heatmap.

  • annotation_colors (Mapping[str, Mapping[str, str] | Sequence[str]] | None, default None) – Per-track color overrides, keyed by annotation name. The value is either a category -> color mapping, or a list of colors (two colors define a gradient for numeric tracks). Tracks without an entry use the defaults.

  • mapping (FeatureSpec | None, default None) – Additional aesthetic mappings for the heatmap, the result of aes().

  • geom ({'raster', 'tile'}, default 'raster') – The geom to use for the heatmap cells. Use ‘raster’ for performance. Use ‘tile’ to enable tooltips.

  • layers (FeatureSpec | Sequence[FeatureSpec] | None, default None) – Extra lets-plot layers to add to the heatmap, such as a scale or theme; a single spec or a sequence of them. A scale_fill_* (e.g. scale_fill_viridis()) overrides the default value gradient.

  • layers_all (FeatureSpec | Sequence[FeatureSpec] | None, default None) – Extra lets-plot layers added after layers. The heatmap and its tracks are one plot, so this now acts as layers; kept for compatibility.

  • scale_axis ({0, 1} | None, default None) – Standardize values with min-max scaling. If 0, standardize each variable (column); if 1, standardize each observation (row).

  • transpose (bool, default False) – Swap the axes so observations run along the x-axis and the variable keys along the y-axis. Annotation tracks and the dendrogram move with their data: variable tracks to the left, observation tracks and the dendrogram above the heatmap.

  • dendrogram (bool, default False) – Whether to cluster the groups and draw a dendrogram beside the observation tracks, outermost in their side band. The clustering is computed if not already available. Requires group_by.

  • group_lines (bool, default True) – Whether to draw separator lines between group_by groups (and between variable_group_by blocks).

  • group_lines_color (str, default 'white') – Color of the group separator lines.

  • group_lines_size (float, default 0.6) – Size (thickness) of the group separator lines.

  • group_lines_kwargs (dict | None, default None) – Additional parameters for the group separator geom_segment.

  • dendrogram_color (str, default 'black') – Color of the dendrogram segments.

  • dendrogram_size (float, default 0.5) – Size (thickness) of the dendrogram segments.

  • dendrogram_key (str | None, default None) – Specific key holding the precomputed dendrogram.

  • dendrogram_kwargs (dict | None, default None) – Additional parameters for the dendrogram geom_path.

  • column_annotation_height (float, default 0.025) – Height of each column annotation track, relative to the heatmap.

  • row_annotation_width (float, default 0.025) – Width of each row annotation track, relative to the heatmap.

  • column_annotation_position ({'top', 'bottom'}, default 'top') – Which side of the heatmap the column (variable) tracks sit on. Under transpose this reflects to the left/right side (top to left, bottom to right).

  • row_annotation_position ({'left', 'right'}, default 'left') – Which side of the heatmap the row (observation) tracks and the dendrogram sit on. Under transpose this reflects to the top/bottom side (left to top, right to bottom).

  • row_track_titles (bool, default False) – Whether to name the row_annotations tracks beside their band (left of the heatmap, or above it under transpose). Hidden by default, since the legends already name the tracks. A top or bottom band’s names sit on its right, a left or right band’s names above it.

  • column_track_titles (bool, default False) – Whether to name the column_annotations tracks beside their band (above the heatmap, or left of it under transpose), placed as for row_track_titles. With both set, a left or right band’s names move below it, so the two bands’ names never share a corner.

  • key_labels (Sequence[str] | None, default None) – Label only these keys, spread evenly along the key axis, with a leader line from each key’s row (or column) to its label, as for gene callouts. The labels sit on the side opposite the column annotation tracks, and the lines in a margin of the heatmap panel on that side. The labels are the key axis labels, so a theme styles them (e.g. theme(axis_text_y=element_text(face=”italic”)) when transposed). None labels every key; an empty sequence labels none (hiding the key axis labels by theme would also hide the track titles on that axis).

  • group_labels (Mapping[str, str] | None, default None) – Text per variable_group_by block (e.g. its GO terms; a newline breaks lines), drawn beside the block outside the column annotation tracks, with a bracket spanning the block. Blocks without an entry get none. Requires variable_group_by.

  • group_labels_width (float, default 0.25) – Width (or height) of the group_labels text area, relative to the heatmap. Text longer than this runs past the plot’s edge.

  • group_labels_kwargs (dict | None, default None) – Additional parameters for the group_labels text layer, such as size.

  • color_low (str, default '#0000ff') – Color for low values in the heatmap gradient.

  • color_mid (str, default '#ffffff') – Color for mid values in the heatmap gradient.

  • color_high (str, default '#ff0000') – Color for high values in the heatmap gradient.

  • midpoint ({'mean', 'median', 'mid'} | float, default 'mid') – Midpoint for the heatmap color gradient.

  • max_rows (int | None, default 1000) – Cap the number of plotted rows by averaging contiguous observations (within each group) into virtual bins. Numeric annotations are averaged and categorical annotations take their most frequent value per bin. Set to None to plot every observation.

  • value_column (str, default 'value') – Name for the value column after unpivoting.

  • variable_column (str, default 'variable') – Name for the variable column after unpivoting.

  • variable_id_column (str, default 'Variable') – Name for the variables identifier column.

  • interactive (bool, default False) – Whether to make the heatmap panel interactive (zoom and pan).

  • legend (bool, default True) – Whether to show the legends for the heatmap and the annotation tracks.

  • annotation_legends (bool, default True) – Whether to show the annotation tracks’ legends. Set to False to keep only the heatmap’s color bar (with legend).

  • **geom_kwargs – Additional parameters for the heatmap geom layer.

Returns:

PlotSpec – The annotated heatmap, one plot with its tracks in side bands.

Raises:

  • UnsupportedDataTypeError – If data is not a supported single-cell data object.

  • ValueError – If dendrogram is set without group_by, key_labels holds a name that is not in keys, or group_labels is set without variable_group_by or names a block it does not have.

Notes

Rows are observations and columns are the variable keys. Variable tracks sit above the heatmap and observation tracks to its left, in ggside side bands that share the heatmap’s axes (and its zoom, with interactive). Each track has its own fill scale (new_scale_fill) and legend, and is labelled on its band’s axis.

When dendrogram=True and the requested dendrogram is absent from data.uns, plot construction calls scanpy.tl.dendrogram and stores the result in data.uns. This mutates the input AnnData. Precompute the dendrogram under dendrogram_key to avoid mutation during plotting.

Examples

import cellestial as cl

data = cl.datasets.pbmc3k()
markers = ["C1QA", "PSAP", "CD79A", "CD79B", "CST3", "LYZ"]

cl.annotated_heatmap(
    data,
    keys=markers,
    group_by="cell_type_lvl1",
    column_annotations=["highly_variable"],
    row_annotations=["leiden", "pct_counts_mt"],
    scale_axis=0,
)
C1QA PSAP CD79A CD79B CST3 LYZ value 0 0.2 0.4 0.6 0.8 1 pct_counts_mt 10 20 30 highly_variable true leiden 0 10 7 13 6 16 1 11 23 8 2 4 15 3 12 9
On this page