vampire.anno.pl.motif_abundance_heatmap

vampire.anno.pl.motif_abundance_heatmap#

vampire.anno.pl.motif_abundance_heatmap(adata, *, layer=None, standard_scale='obs', deduplicate=False, cluster_rows=True, cluster_cols=True, row_cluster_method='average', col_cluster_method='average', row_cluster_metric='euclidean', col_cluster_metric='euclidean', colormap=None, showticklabels=True, vmax=None, vmin=None, row_annotation=None, row_annotation_colormap=None, col_annotation=None, col_annotation_colormap=None, figsize=(None, None), save=None, **kwargs)[source]#

Plot a sample × motif abundance heatmap with hierarchical clustering and dendrograms.

This is a convenience wrapper around matrix_heatmap() that extracts the motif abundance matrix from an AnnData object.

Parameters:

  • adata (AnnData) – Annotated data object generated from pp.read_anno().

  • layer (str | None) – Layer in adata.layers to use. If None, uses adata.X.

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

    Standard scaling mode:

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

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

    • "zscore_obs" — z-score standardize each row (sample)

    • "zscore_var" — z-score standardize each column (motif)

  • deduplicate (bool, default=False) – If True, collapse samples with identical motif arrays into a single row. The track label shows the first sample name followed by ... (n=X) where X is the number of collapsed samples. The draw order follows the position of the first occurrence in sample_order.

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

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

  • 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 name. Default is white to red.

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

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

  • row_annotation (str | list[str] | dict[str, dict[str, str]] | None) –

    Categorical annotation(s) for each row.

    • str — column name in adata.obs; values are read and wrapped into the unified dict format.

    • list[str] — multiple column names in adata.obs; each becomes a separate annotation dimension.

    • dict[str, dict[str, str]] — keys are dimension names and values are {sample_name -> category} mappings. Looked up by sample name so the order is safe.

    When deduplicate=True, inputs are aggregated per sample group so collapsed rows show stacked proportions.

  • 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. Non-nested values apply to all dimensions; nested dict keys must match dimension names.

  • col_annotation (str | list[str] | dict[str, dict[str, str]] | None) – Categorical annotation(s) for each column. Same semantics as row_annotation, but reads from adata.var instead of adata.obs.

  • 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. Non-nested values apply to all dimensions; nested dict keys must match dimension names.

  • figsize (tuple[int | None, int | None] | 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 forwarded to matrix_heatmap() and fig.update_layout().

Returns:

A Plotly figure containing the clustered heatmap with dendrograms.

Return type:

Figure

Examples

>>> import vampire as vp
>>> vp.anno.pl.set_default_plotstyle()
>>> adata = vp.datasets.wdr7_hprc()
>>> vp.anno.pl.motif_abundance_heatmap(
...     adata,
...     cluster_rows=True,
...     cluster_cols=True,
...     standard_scale="obs",
... )
Contents