scallops.visualize.heatmap.plate_heatmap

scallops.visualize.heatmap.plate_heatmap(df, column, tile_shape=None, tile_layout=9, cmap='viridis', figsize=None, colorbar_location='top', vmin_quantile=0, vmax_quantile=1, missing_value=nan, full_well=None, aggregation_func=None, overall_ann=None, column_names=None, row_names=None)

Plot summary statistics for each well and tile in a heatmap.

This function generates a heatmap to visualize summary statistics for each well and tile based on a specified column in the provided DataFrame.

Parameters:

  • df (DataFrame) – Data frame to plot. The DataFrame must be grouped by well and tile.

  • column (str) – Column in the data frame to plot.

  • tile_shape (tuple[int, int]) – Tile layout rows and columns. If None, it is inferred assuming a square layout.

  • tile_layout (int) – Layout constant from ~scallops.visualize.grid_layout.

  • cmap (str | Colormap) – The Colormap instance or registered colormap name used to map scalar data to colors.

  • figsize (tuple[float, float]) – Figure size. If None, it is automatically determined.

  • colorbar_location (Literal['top', 'bottom', 'right', 'left'] | None) – Colorbar location. Either ‘top’ or ‘right’.

  • vmin_quantile (float) – Quantile (between 0 and 1) to use for computing the color scale minimum.

  • vmax_quantile (float) – Quantile (between 0 and 1) to use for computing the color scale maximum.

  • missing_value (float) – Value to fill the heatmap if the well and tile combination is not found in the data frame.

  • full_well (Sequence[int] | None) – Optional sequence of the number of tiles per row in an elliptical well (e.g., Nikon elements tiling). If not provided, it is assumed to be squared.

  • aggregation_func (Callable | str | None) – Optional function to aggregate column by if df is not aggregated

  • overall_ann (dict[str, Callable] | None) – Dictionary of Callables to provide a function for the xlabel per well (e.g., {‘Median’: np.median}). Must be nan resilient.

  • column_names (Sequence[str] | None) – Optional list of names for columns. Must be ordered by plate layout

  • row_names (Sequence[str] | None) – Optional list of names for rows. Must be ordered by plate layout

Returns:

Returns a Matplotlib Figure object containing the heatmap.

Example:

import pandas as pd
import numpy as np
from scallops.visualize import plate_heatmap

# Create a sample DataFrame
np.random.seed(42)
wells = ["A1", "A2", "B1", "B2"]
tiles = list(range(16))
w, t = zip(*product(wells, tiles))
data = pd.DataFrame(
    {
        "well": w,
        "tile": t,
        "value": np.random.normal(size=len(w)),
    }
).set_index(["well", "tile"])

# Generate a heatmap
plate_heatmap(data, column="value", tile_shape=(4, 4), cmap="viridis")