heatmap

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

heatmap(data: AnnData, keys: Sequence[str] | Mapping[str, Sequence[str]] | None = None, group_by: str | None = None, *, markers: bool | str = False, n_genes: int = 5, groups: Sequence[str] | None = None, mapping: FeatureSpec | None = None, geom: Literal['raster', 'tile'] = 'raster', scale_axis: Literal[0, 1] | None = None, dendrogram: bool = False, aggregate: bool = False, group_bars: bool = True, group_bars_size: float = 6, group_bars_labels: bool = True, group_lines: bool = True, group_lines_color: str = 'white', group_lines_size: float = 0.6, dendrogram_color: str = 'black', dendrogram_size: float = 0.5, dendrogram_key: str | None = None, group_lines_kwargs: dict | None = None, dendrogram_kwargs: dict | None = None, key_labels: bool = True, key_labels_text_size: float = 1.0, key_labels_bracket_size: float = 0.6, key_labels_text_color: str = 'black', key_labels_bracket_color: str = 'black', key_labels_width: float = 0.6, value_column: str = 'value', variable_column: str = 'variable', color_low: str = '#0000ff', color_mid: str = '#ffffff', color_high: str = '#ff0000', mid_point: Literal['mean', 'median', 'mid'] | float = 'mid', axis: Literal[0, 1] | None = 0, observations_name: str = 'Barcode', variables_name: str = 'Variable', include_dimensions: bool | int = False, interactive: bool = False, max_rows: int | None = 1000, **geom_kwargs) → PlotSpec

Heatmap.

Parameters:

• data (AnnData) – The AnnData object of the single cell data.

• keys (Sequence[str] | Mapping[str, Sequence[str]] | None, default None) – Variable keys to include, placed on the x-axis. A mapping assigns keys to group labels (no key in more than one group). Must be None when markers is set.

• group_by (str | None, default None) – The key to group the data by. Inferred from a precomputed ranking when markers is set.

• markers (bool | str, default False) – Derive keys from a precomputed ranking. Pass True to use the default ranking key, or a string to read a custom key (e.g. “rank_genes_groups_wilcoxon”).

• n_genes (int, default 5) – Number of top genes to take per group when markers is set.

• groups (Sequence[str] | None, default None) – Subset of groups to include when markers is set; None keeps all groups in their stored order.

• mapping (FeatureSpec | None, default None) – Aesthetic mappings for the plot, the result of aes().

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

• dendrogram (bool, default False) – Whether to add a dendrogram for the group_by axis. Uses scanpy.tl.dendrogram if not already computed.

• aggregate (bool, default False) – If False, plot one row per observation (i.e., cell). If True, aggregate values per group by mean so each row is a group. For the aggregated view, prefer matrixplot().

• group_bars (bool, default True) – Whether to draw colored vertical bars on the left marking group membership. Only used when aggregate=False.

• group_bars_size (float, default 6) – Size (thickness) of the group color bars.

• group_bars_labels (bool, default True) – Whether to show group names as labels along the y-axis. Removes the related legend. Only applies when group_bars=True and aggregate=False.

• group_lines (bool, default True) – Whether to draw horizontal lines within the heatmap separating groups.

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

• 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. By default, dendrogram_{group_by} is used.

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

• dendrogram_kwargs (dict | None, default None) – Additional parameters to pass to the dendrogram geom_segment.

• key_labels (bool, default True) – Whether to draw bracket labels above the plot when keys is a mapping.

• key_labels_text_size (float, default 1.0) – Scale multiplier on the auto-computed bracket label text size.

• key_labels_bracket_size (float, default 0.6) – Size (thickness) of the bracket lines.

• key_labels_text_color (str, default 'black') – Color of the bracket label text.

• key_labels_bracket_color (str, default 'black') – Color of the bracket lines.

• key_labels_width (float, default 0.6) – Bracket width (in column units) for a singleton group. Multi-key groups extend key_labels_width / 2 past the first and last key on each side.

• scale_axis ({0, 1} | None, default None) – Whether to standardize a dimension between 0 and 1. Uses min-max scaling; constant partitions are set to 0. If 0, standardize each variable (column). If 1, standardize each row (group when aggregate is True, observation otherwise).

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

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

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

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

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

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

• axis ({0,1} | None, default 0) – Axis of the data, 0 for observations and 1 for variables.

• observations_name (str, default 'Barcode') – The name of the observations column.

• variables_name (str, default 'Variable') – Name for the variables index column.

• include_dimensions (bool | int, default False) – Whether to include dimensions in the DataFrame. Providing an integer will limit the number of dimensions to given number.

• interactive (bool, default False) – Whether to make the plot interactive.

• max_rows (int | None, default 1000) – When aggregate=False, cap the number of plotted rows by averaging contiguous observations within each group into virtual bins. Bypasses the long-form data payload sent to the renderer when row counts exceed display resolution. Set to None to disable.

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

Returns:

PlotSpec – Heatmap.

Raises:

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

• KeyNotFoundError – If markers is enabled and the requested ranking result or group is missing.

• DuplicateKeysError – If a mapping passed to keys assigns the same key to multiple groups.

• ValueError – If keys and group_by are missing while markers is disabled.

Examples

Heatmap plots one row per observation (cell), grouped by group_by.

import scanpy as sc
from lets_plot import *

import cellestial as cl

data = cl.datasets.pbmc3k(cache_directory="data")

markers = ["C1QA", "PSAP", "CD79A", "CD79B", "CST3", "LYZ"]

cl.heatmap(
    data,
    group_by="cell_type_lvl1",
    keys=markers,
    dendrogram=True,
) + scale_fill_viridis()

To enable tooltips, use geom=’tile’.

cl.heatmap(
    data,
    group_by="cell_type_lvl1",
    keys=markers,
    dendrogram=True,
    geom="tile",
    tooltips=["value"],
) + scale_fill_viridis()

Values can be standardized per-row or per-column with scale_axis.

cl.heatmap(
    data,
    group_by="cell_type_lvl1",
    keys=markers,
    dendrogram=True,
    scale_axis=1,
) + scale_fill_viridis()

Heatmap components (group separator lines, group bars, dendrogram) can be added or customized.

cl.heatmap(
    data,
    group_by="cell_type_lvl1",
    keys=markers,
    geom="raster",
    group_lines_size=0.5,
    group_lines_color="white",
    dendrogram=True,
    dendrogram_size="0.7",
    group_bars_labels=True,
    group_bars=True,
) + scale_fill_viridis()

For the aggregated view (one row per group), use matrixplot() or pass aggregate=True.

cl.heatmap(
    data,
    group_by="cell_type_lvl1",
    keys=markers,
    aggregate=True,
    dendrogram=True,
)

To plot the top genes from a precomputed ranking, set markers and n_genes (keys and group_by are inferred):

import scanpy as sc

sc.tl.rank_genes_groups(data, groupby="cell_type_lvl1")
cl.heatmap(data, markers=True, n_genes=5, aggregate=True)

WARNING: It seems you use rank_genes_groups on the raw count data. Please logarithmize your data before calling rank_genes_groups.