publiplots.complex_heatmap¶

publiplots.complex_heatmap(data, x=None, y=None, value=None, size=None, cmap='viridis', vmin=None, vmax=None, center=None, annot=False, annot_kws=None, fmt='.2g', linewidths=0, linecolor='white', square=False, sizes=None, size_norm=None, alpha=None, linewidth=None, edgecolor=None, axes_size=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None, xticklabels='auto', yticklabels='auto', mask=None, row_cluster=False, col_cluster=False, cluster_method='ward', cluster_metric='euclidean', row_dendrogram=True, col_dendrogram=True, dendrogram_size=10, hspace=1.0, wspace=1.0, **kwargs)[source]¶

Create a complex heatmap builder for adding margin plots.

This function returns a ComplexHeatmapBuilder that composes a main publiplots.heatmap() with aligned margin plots (any publiplots or user function that accepts ax=) and optional row/column hierarchical clustering with dendrograms. Margin plots are attached via .add_top() / .add_bottom() / .add_left() / .add_right() and the figure is rendered by .build().

Parameters:

data (pd.DataFrame) – Input data (wide or long format).
x (str, optional) – Column names for long-format data.
y (str, optional) – Column names for long-format data.
value (str, optional) – Column names for long-format data.
size (str, optional) – Column names for long-format data.
cmap (str, default="viridis") – Colormap for the heatmap.
vmin (float, optional) – Color normalization bounds.
vmax (float, optional) – Color normalization bounds.
center (float, optional) – Center value for diverging colormaps.
annot (bool or DataFrame, default=False) – Cell annotations.
annot_kws (dict, optional) – Annotation styling.
fmt (str, default=".2g") – Annotation format string.
linewidths (float, default=0) – Cell border width.
linecolor (str, default="white") – Cell border color.
square (bool, default=False) – Force square cells.
sizes (tuple, optional) – (min, max) marker sizes for dot heatmap.
size_norm (tuple or Normalize, optional) – Size normalization.
alpha (float, optional) – Marker transparency.
linewidth (float, optional) – Marker edge width.
edgecolor (str, optional) – Marker edge color.
axes_size (tuple of float, optional) – Main heatmap axes dimensions in millimeters, as (width_mm, height_mm). The figure grows to accommodate margin plots added via .with_top() / .with_bottom() / etc. If not specified, defaults to (80, 60) mm.
title (str, default="") – Plot title.
xlabel (str, default="") – Axis labels.
ylabel (str, default="") – Axis labels.
legend (bool, default=True) – Show legend.
legend_kws (dict, optional) – Legend styling.
xticklabels (bool, str, or list) – Tick label configuration.
yticklabels (bool, str, or list) – Tick label configuration.
mask (DataFrame or array, optional) – Cell mask.
row_cluster (bool, default=False) – Cluster rows.
col_cluster (bool, default=False) – Cluster columns.
cluster_method (str, default="ward") – Clustering linkage method.
cluster_metric (str, default="euclidean") – Clustering distance metric.
row_dendrogram (bool, default=True) – Show row dendrogram if clustering.
col_dendrogram (bool, default=True) – Show column dendrogram if clustering.
dendrogram_size (float, default=10) – Dendrogram size in mm.
hspace (float, default=1.0) – Vertical space between plots (mm).
wspace (float, default=1.0) – Horizontal space between plots (mm).
**kwargs – Additional heatmap parameters.

Returns:

Builder object with .add_top(), .add_left(), etc. methods.

Return type:

ComplexHeatmapBuilder

Examples

Basic complex heatmap with margins:

>>> axes = (
...     pp.complex_heatmap(data, x="sample", y="gene", value="expr")
...     .add_top(pp.barplot, data=totals, x="sample", y="count", height=15)
...     .add_left(pp.barplot, data=means, x="mean", y="gene", width=15)
...     .build()
... )

With clustering and dendrograms:

>>> axes = (
...     pp.complex_heatmap(matrix, row_cluster=True, col_cluster=True)
...     .build()
... )

Access individual axes:

>>> axes['main']      # Main heatmap
>>> axes['top'][0]    # First top margin plot
>>> axes['left'][0]   # First left margin plot