harpy.qc.image_histogram

harpy.qc.image_histogram#

harpy.qc.image_histogram(sdata, image_name, channel, bins, scale=None, range=None, ax=None, output=None, fig_kwargs=mappingproxy({}), bar_kwargs=mappingproxy({}), density=False, log_y=False, percentile_lines=None, kind='hist', exclude_zeros=True, exclude_nan=True, title=None, ncols=3, subplot_width=4, subplot_height=3.5, sharex=False, sharey=False, **kwargs)#

Generate and visualize a histogram for a specified image channel within an image of a SpatialData object.

Parameters:

  • sdata (SpatialData) – The input SpatialData object containing the image data.

  • image_name (str) – The name of the image element within sdata to analyze.

  • channel (str | int | Sequence[str | int]) – The specific channel of the image data to use for the histogram. Can be a single channel name or index, or a sequence of channel names and/or indices.

  • bins (int) – The number of bins for the histogram.

  • scale (str | None (default: None)) – Pyramid level to use when image_name is multiscale. If None, the histogram is computed from "scale0". Using a lower-resolution scale provides a faster but approximate histogram.

  • range (tuple[float, float] | None (default: None)) – The range of values for the histogram as (min, max). If not provided, range is simply (dask.array.nanmin(...), dask.array.nanmax(...)), thus excluding NaN. For kind="hist", values outside the range are ignored. For kind="ecdf", the range is used to set the x-axis limits only.

  • fig_kwargs (dict[str, Any] (default: mappingproxy({}))) – Additional keyword arguments passed to plt.subplots, such as dpi or figsize, when ax=None (and this function therefore creates the subplot(s)). Ignored if ax is provided.

  • bar_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Additional keyword arguments passed to ax.bar, such as color or alpha.

  • ax (Axes | ndarray | None (default: None)) – An existing axes object to plot the histogram. If None, a new figure and axes will be created.

  • output (str | Path (default: None)) – The path to save the generated plot. If None, the plot will not be saved.

  • density (bool (default: False)) – If True, normalize the histogram to a density instead of plotting raw counts.

  • log_y (bool (default: False)) – If True, use a logarithmic scale for the y-axis.

  • percentile_lines (Sequence[float] | None (default: None)) – Percentile values in the interval [0, 100] to visualize as vertical guide lines.

  • kind (str (default: 'hist')) – Plot kind. Choose between "hist" for a histogram and "ecdf" for an empirical cumulative distribution plot.

  • exclude_zeros (bool (default: True)) – If True, exclude zero-valued pixels before plotting and before computing percentile guide lines.

  • exclude_nan (bool (default: True)) – If True, exclude NaN values before plotting and before computing percentile guide lines.

  • title (str | None (default: None)) – Custom plot title. Defaults to the channel name. Only applied directly in the single-channel case.

  • ncols (int (default: 3)) – Number of subplot columns to use when plotting multiple channels.

  • subplot_width (float (default: 4)) – Width of each subplot column when plotting multiple channels and no explicit figsize is provided in fig_kwargs. Ignored when fig_kwargs contains figsize.

  • subplot_height (float (default: 3.5)) – Height of each subplot row when plotting multiple channels and no explicit figsize is provided in fig_kwargs. Ignored when fig_kwargs contains figsize.

  • sharex (bool (default: False)) – Whether to share the x-axis across subplots when plotting multiple channels.

  • sharey (bool (default: False)) – Whether to share the y-axis across subplots when plotting multiple channels.

  • **kwargs – Additional keyword arguments passed to dask.array.histogram() when kind="hist".

Raises:

AssertionError – If image_name is not found in sdata.images.

Return type:

Axes | ndarray

Examples

import harpy as hp

sdata = hp.datasets.pixie_example()

ax = hp.qc.image_histogram(
    sdata,
    image_name="raw_image_fov0",
    channel=hp.im.get_dataarray(sdata, element_name="raw_image_fov0").c.data,
    percentile_lines=[0.1, 99.9],
    kind="hist",
    ncols=5,
    subplot_height=3,
    subplot_width=3,
    log_y=False,
    exclude_nan=True,
    exclude_zeros=True,
    density=False,
    bins=100,
)