harpy.qc.metrics_histogram

harpy.qc.metrics_histogram#

harpy.qc.metrics_histogram(sdata, table_name, labels_name=None, metrics=(('obs', 'total_counts'), ('obs', 'n_genes_by_counts'), ('var', 'total_counts'), ('var', 'log1p_total_counts'), ('var', 'n_cells_by_counts'), ('var', 'mean_counts')), ax=None, bins='auto', range=None, quantile_range=None, histplot_kwargs=mappingproxy({}), median_line_kwargs=mappingproxy({}), median_text_kwargs=mappingproxy({}), figsize=None, ncols=3, subplot_width=5.5, subplot_height=4.5, sharex=False, sharey=False, title=None, display_column=None, color=None, show_median=True, show_std=True)#

Plot a standard panel of QC metric histograms 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.

  • metrics (Sequence[tuple[Literal['obs', 'var'], str]] (default: (('obs', 'total_counts'), ('obs', 'n_genes_by_counts'), ('var', 'total_counts'), ('var', 'log1p_total_counts'), ('var', 'n_cells_by_counts'), ('var', 'mean_counts')))) – Sequence of (dataframe, column) tuples to plot. Defaults to a standard transcript QC panel obtained through scanpy.pp.calculate_qc_metrics().

  • ax (ndarray | Sequence[Axes] | None (default: None)) – Array-like collection of axes to draw on. If None, subplot axes are created.

  • bins (int | str | Sequence[int | str] (default: 'auto')) – Histogram bin specification passed to seaborn.histplot(). If a sequence is provided, it must match the length of metrics and each value is applied to the corresponding panel.

  • range (tuple[float, float] | None (default: None)) – Lower and upper bounds of the histogram x-axis applied to all panels.

  • quantile_range (tuple[float, float] | None (default: None)) – Quantile interval used to derive the histogram x-axis automatically when range is None.

  • 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().

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

  • figsize (tuple[float, float] | None (default: None)) – Figure size used when ax is None. If None, a size is inferred from ncols and the number of metrics.

  • ncols (int (default: 3)) – Number of subplot columns when ax is None.

  • subplot_width (float (default: 5.5)) – Width of each subplot when figsize is not provided.

  • subplot_height (float (default: 4.5)) – Height of each subplot when figsize is not provided.

  • sharex (bool (default: False)) – Whether to share x-axes across subplots when ax is None.

  • sharey (bool (default: False)) – Whether to share y-axes across subplots when ax is None.

  • title (str | None (default: None)) – Figure title applied when ax is None.

  • display_column (str | Sequence[str | None] | None (default: None)) – Display name override for the plotted metrics. If a single string is provided, it is applied to all panels. If a sequence is provided, it must match the length of metrics and each value is applied to the corresponding panel. Entries set to None fall back to a readable label derived from the metric name.

  • color (str | Sequence[str] | None (default: None)) – Histogram color override. If a single string is provided, it is applied to all panels. If a sequence is provided, it must match the length of metrics and each value is applied to the corresponding panel.

  • 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.

Return type:

ndarray

Returns:

: numpy.ndarray containing the histogram axes.

Examples

import harpy as hp

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

hp.qc.metrics_histogram(
    sdata,
    table_name="table_transcriptomics_preprocessed",
    labels_name="nucleus_segmentation_mask",
    quantile_range=(0.1, 0.99),
)