vampire.anno.pl.heatmap_from_matrix

vampire.anno.pl.heatmap_from_matrix#

vampire.anno.pl.heatmap_from_matrix(matrix, *, is_distance=False, row_labels=None, col_labels=None, standard_scale=None, cluster_rows=True, cluster_cols=True, row_cluster_method='average', col_cluster_method='average', row_cluster_metric='euclidean', col_cluster_metric='euclidean', colormap=None, colorbar_title='Value', showticklabels=True, vmax=None, vmin=None, hover_template='Row: %{y}<br>Col: %{x}<br>Value: %{hovertext}<extra></extra>', row_annotation=None, row_annotation_colormap=None, col_annotation=None, col_annotation_colormap=None, figsize=(None, None), save=None, **kwargs)[source]#

Plot a clustered heatmap from an arbitrary numeric matrix.

This is the generic engine underlying all domain-specific heatmap functions. It accepts a raw 2-D numpy array, optionally clusters rows and/or columns, and returns an interactive Plotly figure with dendrograms.

Parameters:

  • matrix (ndarray) – 2-D array of shape (n_rows, n_cols).

  • is_distance (bool) – Whether the matrix is alreadt distance matrix.

  • row_labels (list[str] | None) – Labels for rows. If None, integer indices are used.

  • col_labels (list[str] | None) – Labels for columns. If None, integer indices are used.

  • standard_scale (Optional[Literal['obs', 'var', 'zscore_obs', 'zscore_var']]) –

    Standard scaling mode:

    • "obs" — min-max scale each row to [0, 1]

    • "var" — min-max scale each column to [0, 1]

    • "zscore_obs" — z-score standardize each row

    • "zscore_var" — z-score standardize each column

  • cluster_rows (bool) – Whether to hierarchically cluster rows.

  • cluster_cols (bool) – Whether to hierarchically cluster columns.

  • row_cluster_method (str) – Linkage method for row clustering.

  • col_cluster_method (str) – Linkage method for column clustering.

  • row_cluster_metric (str) – Distance metric for row clustering.

  • col_cluster_metric (str) – Distance metric for column clustering.

  • colormap (str | list[str] | None) – Plotly colormap.

  • colorbar_title (str) – Title shown next to the color bar.

  • showticklabels (bool) – Whether to display row and column tick labels.

  • vmax (float | None) – Upper bound for clipping the heatmap color scale. Values above vmax are clipped for visualization only; the original values are still shown on hover.

  • vmin (float | None) – Lower bound for clipping the heatmap color scale. Values below vmin are clipped for visualization only.

  • hover_template (str) – Plotly hover template for the heatmap trace. Use %{text} to reference the un-clipped original value.

  • row_annotation (dict[str, list[list[str]]] | None) – Categorical annotation(s) for each row. Keys are dimension names (e.g. "haplotype") and values are lists of length n_rows. Each inner list contains the labels for that row; multiple labels per row are rendered as a stacked proportion bar. Displayed as coloured sidebars between the row dendrogram and the heatmap.

  • row_annotation_colormap (dict[str, str] | list[str] | str | dict[str, dict[str, str] | list[str] | str] | None) – dict[str, dict[str, str] | list[str] | str] | None, optional Color specification for row annotations. If a non-nested value is given, it applies to all dimensions. If a nested dict is given, keys must match dimension names and values are used for that dimension only. Missing dimensions fall back to auto-generated Glasbey colors. If None, colours are auto-generated from the Glasbey palette. If a string is provided, it must be selected from rainbow, glasbey, or sequential to use the corresponding preset palette.

  • col_annotation (dict[str, list[list[str]]] | None) – Categorical annotation(s) for each column. Keys are dimension names and values are lists of length n_cols. Each inner list contains the labels for that column; multiple labels per column are rendered as a stacked proportion bar. Each dimension is rendered as a separate coloured bar stacked between the column dendrogram and the heatmap.

  • col_annotation_colormap (dict[str, str] | list[str] | str | dict[str, dict[str, str] | list[str] | str] | None) – dict[str, dict[str, str] | list[str] | str] | None, optional Color specification for column annotations. Same semantics as row_annotation_colormap: non-nested values apply to all dimensions; nested dict keys must match dimension names.

  • figsize (tuple[int | None, int | None]) – Figure size in pixels. (None, None) triggers auto-computation from the matrix dimensions so that heatmap cells are square and labels are not clipped.

  • save (str | bool | None) – If True or a str, save the figure. A string is appended to the default filename. Infer the filetype if ending on {'.pdf', '.png', '.svg'}.

  • **kwargs – Additional keyword arguments passed to fig.update_layout().

Returns:

A Plotly figure containing the clustered heatmap with dendrograms and optional annotation blocks.

Return type:

Figure

Contents