Feature: pl.ann_hist

[idf-io]

Summary

Annotations in .obs / .var often belong to a higher level than the
axis. A protein q-value, for example, is repeated on every peptide of
the protein in peptide-level data, so a plain histogram counts each
protein once per peptide. pr.pl.ann_hist() plots any .obs / .var
annotation (int, float, str, object or categorical) as a histogram.
With level_key, it first reduces the data to one value per level and
checks that the value is constant within each level.

Related issues

None

General checklist

• Branch name and commit subjects follow the repo conventions
• HISTORY.md updated under [Unreleased]
• CI is green (flake8, pylint, pytest). Locally, flake8 and pylint
  (errors only) are clean and the full suite passes (560 tests). CI
  has not run yet.

---

✨ Feature

What it adds:

pr.pl.ann_hist(), a thin wrapper around
seaborn.histplot.
All extra kwargs are passed to histplot unchanged.

• x / y name annotation columns and keep their histplot meaning:
  one of them gives a univariate histogram, both give a bivariate one.
  hue and weights, when given as strings, are read as columns too.
• level_key (str or list) keeps one row per group. It raises a
  ValueError listing example groups if a plotted column varies within
  a group.
• axis ("obs" / "var") is inferred when None. It raises if a
  column exists in both .obs and .var, or if the columns come from
  different axes. Passing axis resolves the first case.
• vline / hline take a dict or a list of dicts with the keys
  value, color (default "red"), linestyle (default "dashed")
  and text. They draw full-span reference lines, and lines with
  text get a legend to the right of the plot.
• zero_to_na / fill_na apply to the extracted x / y values.
  fill_na also accepts a string label for categorical data.
• Non-numeric values follow the AGENTS.md ordering rule: category order
  for categorical columns, otherwise lexicographic.

Example usage:

import proteopy as pr

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,
)

• Follows the AGENTS.md function and module conventions. ax is
  not implemented yet; passing it raises TypeError.
• Tests added for the new behavior. Not done in this PR. I
  checked behaviour by hand with a scratch script covering
  level_key, the consistency check, axis resolution, ordering,
  fill_na / zero_to_na, vline / hline, save and reserved
  kwargs. Unit tests should follow, including the two ordering tests
  from AGENTS.md rule 4.
• Numpydoc docstring with an example. Note: the examples use
  pr.load.toy_simple_peptides(), which does not exist on main yet.
• Added to the Sphinx API docs (pl.rst, Metadata exploration)
• Relevant tutorial notebooks updated, or none affected (none)
• N/A: algorithm reimplemented from published work

Review attention:

• _collapse_to_level(): the consistency check uses
  groupby(...).nunique(dropna=False), so NaN counts as a distinct
  value.
• _draw_lines(): calling ax.legend() replaces seaborn's hue
  legend, so the old legend is re-attached with ax.add_artist.
• save uses bbox_inches="tight" so the legend outside the axes is
  not clipped.
• sns.distplot was considered as the backend but not used, because
  it is deprecated and handles numeric data only.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 proteopy | 🛠️ Build #35074294 | 📁 Comparing d21ba48 against latest (b336e80)

  🔍 Preview build  

6 files changed · + 2 added · ± 4 modified

+ Added

• api/generated/proteopy.pl.ann_hist.html
• _modules/proteopy/pl/ann_hist.html

± Modified

• changelog.html
• genindex.html
• _modules/index.html
• api/pl.html

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d21ba48fdd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[idf-io]