.ann_hist

proteopy.pl.ann_hist(adata, x=None, y=None, level_key=None, axis=None, zero_to_na=False, fill_na=None, vline=None, hline=None, show=True, save=None, **kwargs)[source]

Plot a histogram of .obs or .var annotation columns.

Thin wrapper around seaborn.histplot(). The annotation columns are collected from adata.obs or adata.var, optionally reduced to one row per level_key group, and passed to sns.histplot together with all extra keyword arguments.

Parameters:

  • adata (AnnData) – AnnData holding the annotations.

  • x (str | None) – Annotation column plotted on the x axis. Same meaning as x in seaborn.histplot(), except that it names a .obs/.var column.

  • y (str | None) – Annotation column plotted on the y axis. Same meaning as y in seaborn.histplot(). Pass only y for a horizontal histogram, or both x and y for a bivariate histogram. At least one of x and y is required.

  • level_key (str | list[str] | None) – Column(s) defining the level the annotation belongs to. Annotations often describe a higher level than the axis and are repeated for every row of that level, e.g. protein_q_value is repeated for all peptides of a protein in a peptide-level AnnData. With level_key="protein_id", each protein contributes one value instead of one per peptide.

  • axis ({"obs", "var"} | None) – Annotation axis holding the columns. If None, it is inferred from where the columns live.

  • zero_to_na (bool) – If True, replace zeros with NaN in the numeric x / y columns before plotting.

  • fill_na (float | int | str | None) – If not None, replace NaN in the x / y columns with this value, e.g. "missing" for str or categorical annotations.

  • vline (dict | list[dict] | None) – Vertical line(s) drawn with matplotlib.axes.Axes.axvline(). A dict defines one line, a list of dicts several. Keys: value (required, numeric x position), color (default "red"), linestyle (default "dashed") and text (default None). Lines with text are listed in a legend to the right of the plot. On a categorical axis, category i sits at position i.

  • hline (dict | list[dict] | None) – Horizontal line(s) drawn with matplotlib.axes.Axes.axhline(). Same format as vline, with value as the y position.

  • show (bool) – Call matplotlib.pyplot.show() at the end.

  • save (str | Path | None) – Save the figure to this path. If None, do not save.

  • **kwargs – Passed verbatim to seaborn.histplot() (e.g. bins, binwidth, stat, discrete, shrink, element, kde, log_scale, hue, multiple, palette). See https://seaborn.pydata.org/generated/seaborn.histplot.html for the full list and what each argument does. hue and weights given as strings name .obs/.var columns from the same frame as x/y. data and ax are reserved.

Returns:

The Axes the histogram was drawn on.

Return type:

Axes

Raises:

  • KeyError – If a referenced column is missing.

  • ValueError – If neither x nor y is given, axis is None and a plotted column exists in both .obs and .var, the plotted columns come from different annotation axes, a plotted column is not constant within a level_key group, or a vline / hline dict has unknown keys or no finite numeric value.

  • TypeError – If a reserved keyword is passed, a column has an unsupported dtype (e.g. bool or datetime), or vline / hline is not a dict or a list of dicts.

Notes

Non-numeric values are ordered by category order for categorical columns, otherwise lexicographically after str coercion. To impose a custom order, store the column as an ordered Categorical:

>>> adata.var["fraction"] = pd.Categorical(
...     adata.var["fraction"],
...     categories=["F1", "F2", "F10"],
...     ordered=True,
... )

Examples

>>> import proteopy as pr
>>> adata = pr.load.toy_simple_peptides(
...     n_proteins=10,
...     n_peptides_per_protein=(
...         [5] * 1 + [6] * 2 + [7] * 5 + [8] * 2
...     ),
... )
>>> pr.pl.ann_hist(
...     adata,
...     x="Protein.Q.Value",
...     level_key="protein_id",
...     vline=[
...         {"value": 0.01, "text": "1% FDR"},
...         {"value": 0.05, "color": "grey", "text": "5% FDR"},
...     ],
...     bins=50,
... )
>>> pr.pl.ann_hist(
...     adata,
...     x="Q.Value",
...     y="Q.Value.Global",
... )
>>> pr.pl.ann_hist(adata, x="condition", shrink=0.8)