harpy.qc.metric_histogram

harpy.qc.metric_histogram#

harpy.qc.metric_histogram(sdata, table_name, labels_name=None, column='total_counts', display_column=None, dataframe='auto', ax=None, bins='auto', range=None, quantile_range=None, histplot_kwargs=mappingproxy({}), median_line_kwargs=mappingproxy({}), median_text_kwargs=mappingproxy({}), figsize=(5.5, 4.5), title=None, color=None, show_median=True, show_std=True, ylabel=None)#

Plot a QC metric histogram for an AnnData table.

This function is read-only and expects QC metrics to already be present on the selected table, typically after running scanpy.pp.calculate_qc_metrics() during preprocessing.

Parameters:

  • sdata (SpatialData) – SpatialData object containing the table.

  • table_name (str) – Table element in sdata.tables.

  • labels_name (str | Iterable[str] | None (default: None)) – Labels element or elements used to subset the selected table via ProcessTable. If None, all observations in table_name are used.

  • column (str (default: 'total_counts')) – QC metric column to plot. The column is searched in .obs and/or .var depending on dataframe.

  • display_column (str | None (default: None)) – Display name used for the title and x-axis label. If None, column is converted into a readable label.

  • dataframe (Literal['obs', 'var', 'auto'] (default: 'auto')) – Which annotation dataframe to search for column. With "auto", the function first checks adata.obs and adata.var and raises if the column is ambiguous or absent.

  • ax (Axes | None (default: None)) – Matplotlib axes to draw on. If None, a new figure and axes are created.

  • bins (int | str (default: 'auto')) – Histogram bin specification passed to seaborn.histplot(). The default "auto" uses NumPy’s automatic bin estimator.

  • range (tuple[float, float] | None (default: None)) – Lower and upper bounds of the histogram x-axis. Values outside this range are excluded from the plotted histogram, but are still included when calculating the median and standard deviation annotations.

  • quantile_range (tuple[float, float] | None (default: None)) – Quantile interval used to derive the histogram x-axis automatically when range is None. Values outside this interval are excluded from the plotted histogram, but are still included when calculating the median and standard deviation annotations.

  • histplot_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Keyword arguments passed to seaborn.histplot().

  • median_line_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Keyword arguments passed to matplotlib.axes.Axes.axvline() for the median guide line.

  • median_text_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Keyword arguments passed to matplotlib.axes.Axes.text() for the median annotation.

  • figsize (tuple[float, float] (default: (5.5, 4.5))) – Figure size used when ax is None.

  • title (str | None (default: None)) – Plot title. Defaults to display_column.

  • color (str | None (default: None)) – Histogram color. If None, a metric-specific default is used when available.

  • show_median (bool (default: True)) – If True, add a dashed median line and annotate the median.

  • show_std (bool (default: True)) – If True, include the standard deviation in the annotation box.

  • ylabel (str | None (default: None)) – Y-axis label. If None, a label is chosen based on the selected dataframe.

Return type:

Axes

Returns:

: matplotlib.axes.Axes containing the histogram.

Examples

import harpy as hp

sdata = hp.datasets.xenium_human_ovarian_cancer(
    subset=True,
    processed=True,
)

hp.qc.metric_histogram(
    sdata,
    table_name="table_transcriptomics_preprocessed",
    labels_name="nucleus_segmentation_mask",
    column="total_counts",
    dataframe="obs",
    quantile_range=(0.1, 0.99),
)