publiplots.heatmap¶

publiplots.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, ax=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None, xticklabels='auto', yticklabels='auto', mask=None, **kwargs)[source]¶

Create a heatmap with publiplots styling.

This function creates heatmaps for both wide-format (matrix) and long-format (tidy) data. When size is provided, creates a dot/bubble heatmap where marker size encodes an additional variable.

Parameters:

data (pd.DataFrame) – Input data. Can be: - Wide format: DataFrame where index=rows, columns=cols, values=cells - Long format: DataFrame with x, y, value columns (requires x, y, value params)
x (str, optional) – Column name for x-axis (columns) in long-format data.
y (str, optional) – Column name for y-axis (rows) in long-format data.
value (str, optional) – Column name for cell values in long-format data.
size (str, optional) – Column name for marker sizes (long-format only). If provided, creates a dot/bubble heatmap instead of a color heatmap.
cmap (str or colormap, default="viridis") – Colormap for mapping values to colors.
vmin (float, optional) – Minimum value for color normalization. If None, uses data minimum.
vmax (float, optional) – Maximum value for color normalization. If None, uses data maximum.
center (float, optional) – Value to center the colormap at (e.g., 0 for diverging data).
annot (bool or DataFrame, default=False) – If True, write data values in cells. If DataFrame, use its values.
annot_kws (dict, optional) – Keyword arguments for annotation text.
fmt (str, default=".2g") – Format string for annotations.
linewidths (float, default=0) – Width of lines between cells.
linecolor (str, default="white") – Color of lines between cells.
square (bool, default=False) – If True, set aspect ratio to equal for square cells.
sizes (tuple of float, optional) – (min_size, max_size) in points^2 for dot heatmap markers. Default: (20, 500).
size_norm (tuple or Normalize, optional) – Normalization for size values. If tuple, (vmin, vmax).
alpha (float, optional) – Transparency for markers in dot mode. When None, resolved from publiplots.rcParams["alpha"].
linewidth (float, optional) – Edge linewidth for markers in dot mode. When None, resolved from publiplots.rcParams["lines.linewidth"].
edgecolor (str, optional) – Edge color for markers in dot mode. If None, uses marker color. Can also be set globally via publiplots.rcParams["edgecolor"].
ax (Axes, optional) – Matplotlib axes object. If None, creates new figure.
title (str, default="") – Plot title.
xlabel (str, default="") – X-axis label.
ylabel (str, default="") – Y-axis label.
legend (bool or dict, default=True) – Whether to show colorbar/size legend. Accepts bool or dict[kind, bool] for per-kind control (e.g., legend={"size": False} on a dot heatmap keeps the colorbar but hides the size legend).
legend_kws (dict, optional) – Keyword arguments for legend: - value_label : str - Label for colorbar (default: value column name) - size_label : str - Label for size legend (default: size column name)
xticklabels (bool, str, or list, default="auto") – X-axis tick labels.
yticklabels (bool, str, or list, default="auto") – Y-axis tick labels.
mask (DataFrame or array, optional) – Boolean mask for hiding cells (True = hidden).
**kwargs – Additional keyword arguments passed to sns.heatmap (standard mode) or internal scatter function (dot mode).

Returns:

The axes where the plot was drawn.

Return type:

Axes

Examples

Wide-format heatmap:

>>> matrix = pd.DataFrame(np.random.randn(10, 10))
>>> ax = pp.heatmap(matrix, cmap="coolwarm", center=0)

Long-format heatmap:

>>> ax = pp.heatmap(df, x="sample", y="gene", value="expression")

Dot heatmap with size encoding:

>>> ax = pp.heatmap(df, x="sample", y="gene",
...                  value="expression", size="pvalue")

Annotated heatmap:

>>> ax = pp.heatmap(matrix, annot=True, fmt=".1f")