scallops.visualize.imshow.plot_percentile_montage

scallops.visualize.imshow.plot_percentile_montage(df, genes_to_plot, images, labels=None, feature='nuclei_mean_7', group_by=('Plate', 'Row', 'gene_symbol'), percentiles=(10, 30, 50, 70, 90), pad=50, guide_lines=False, context=False, gene_name_col='gene_symbol', cmap=None, vmaxq=0.9, vminq=0.1, labels_key_pattern=None)

Plot a montage of gene-specific images at specified feature percentiles from a dataframe and image stack.

This function creates a montage of images for specified genes, displaying representative cells at given percentiles of a specified feature. It allows for context-based padding and optional guide-lines, extracting relevant image segments and aligning them based on their maximum size.

Parameters:

  • df (DataFrame) – DataFrame containing metadata with positional information for each gene.

  • genes_to_plot (Sequence[str]) – Sequence of gene symbols to plot.

  • images (str | DataArray | Experiment) – Image data, can be a string path, xarray DataArray, or Experiment object.

  • labels (str | DataArray | Experiment | None) – Label data from segmentation if context is disabled. Provide either labels or set context to True, not both. Defaults to None.

  • feature (str) – Feature column name to use for percentile calculations. Defaults to ‘nuclei_mean_7’.

  • group_by (Sequence[str]) – Column names to group by when calculating percentiles. Defaults to (‘Plate’, ‘Row’, ‘gene_symbol’).

  • percentiles (Sequence[float]) – Percentiles to select representative cells. Defaults to (10, 30, 50, 70, 90).

  • pad (int) – Padding size to apply around each extracted image. Defaults to 50.

  • guide_lines (bool) – Whether to include guide-lines on the montage. Defaults to False.

  • context (bool) – If True, uses the entire image region without segmentation labels. Provide either labels or set context to True, not both. Defaults to False.

  • gene_name_col (str) – Column name in the dataframe that contains gene names. Defaults to ‘gene_symbol’.

  • cmap (str | None) – Colormap to use for displaying images. Defaults to None.

  • vmaxq (float) – Upper quantile for color scaling. Defaults to 0.9.

  • vminq (float) – Lower quantile for color scaling. Defaults to 0.1.

  • labels_key_pattern (str | None) – String pattern of the type ‘{well}-nuclei’ to index labels if using Experiment. Defaults to None.

Returns:

A tuple containing the matplotlib Figure object and a dictionary mapping gene symbols to selected coordinates.

Example:

Return type:

tuple[Figure, dict[str, list[tuple[int, str, int, int]]]]

import pandas as pd
import xarray as xr
import matplotlib.pyplot as plt
from scallops.visualize import plot_percentile_montage

# Example usage of plot_percentile_montage function
df = pd.read_csv("data.csv")
genes_to_plot = ["GeneA", "GeneB"]
images = xr.load_dataarray("images.nc")  # Load images as xarray DataArray
labels = xr.load_dataarray(
    "labels.nc"
)  # Optional: Load labels as xarray DataArray

fig, selected = plot_percentile_montage(
    df,
    genes_to_plot,
    images,
    labels=labels,
    feature="nuclei_mean_7",
    guide_lines=True,
    context=False,
)
plt.show()