feat: aa.plot_comparison grouped comparison barplot (prototype #311)

[breimanntools]

Status: SOLID — works, green local tests, full ripple done. One integration
step (re-authoring the live γ-secretase cell 28) is left for the maintainer
because the paper notebook needs xgboost, which is not installed in the agent
env; the identical figure is proven by the executed example notebook + unit tests.

Part of #305 / prototype for #311.

What this adds

Top-level aa.plot_comparison(df_eval, group=..., condition=..., value=..., baseline=50, baseline_label=None, annotate=True, group_order=None, condition_order=None, colors=None, bar_width=0.8, ax=None, figsize=(7, 4.2), xlabel=None, ylabel="Score", title=None, ylim=None, fontsize_annotations=10)
→ returns the Axes.

A grouped method × condition barplot built from a tidy eval frame:

• auto bar offsets / widths for N groups (bar count = groups × conditions);
• optional per-bar value labels (annotate);
• optional dashed chance / baseline line with an auto label (baseline /
  baseline_label);
• house colors via plot_get_clist; follows plotting.md (library plot code
  never calls plt.show() / tight_layout() / plot_settings(); returns the Axes).

Replaces the fully-manual matplotlib of a hand-built grouped barplot (the
x ± w/2 offsets + per-bar ax.text loop + axhline(50) in γ-secretase cell 28).

Files

• aaanalysis/plotting/_plot_comparison.py — the function (frontend + Validate block).
• aaanalysis/plotting/__init__.py, aaanalysis/__init__.py — re-export (feat: aa.plot_comparison — grouped comparison barplot with value labels + chance line #311 is
  on the approved wire-to-public-API list; additive __all__ entry).
• tests/unit/plotting_tests/test_plot_comparison.py — 33 tests (positive +
  negative per public param; bar count, baseline-when-set, annotations, ValueErrors).
• examples/plotting/plot_comparison.ipynb — executed, inline backend, display_df
  • plt.tight_layout()/plt.show(); renders the γ-sec cell-28 figure
    (61/60/75 vs 71/74/94, baseline 50) via one call.
• docs/source/api.rst (autosummary), docs/source/index/release_notes.rst
  (Unreleased), docs/_cheatsheet/content.py (cheat-sheet row).

Local gates (all green)

• tests/unit/plotting_tests/ → 319 passed (33 new).
• tests/unit/api_tests/ → 175 passed (param-coverage, abbreviation registry,
  backend-import-hygiene, utils barrel).
• docstring checker → 0 defects (1 advisory RAISES-UNDOCUMENTED, matching the
  sibling plot_rank which also omits a Raises section); doc/signature drift → 0.
• import aaanalysis resolves cleanly with plot_comparison in aa.__all__.

What to review

• API surface / param names (locked subset group/condition/value/baseline/ annotate/ax plus the optional extras baseline_label, group_order,
  condition_order, colors, bar_width, ylim, fontsize_annotations,
  labels/title/figsize — mirrors the plot_rank extras pattern).
• Default ylabel="Score" (generic) vs leaving it None.
• Repeated (group, condition) cells are averaged (mean); confirm that
  policy vs erroring on duplicates.
• Return type is Axes (per the issue), unlike plot_rank which returns
  (fig, ax) — confirm the intended house convention here.

γ-secretase cell-28 re-authoring (KPI — recommended drop-in for the maintainer)

The paper notebook can't be re-executed in the agent env (No module named 'xgboost'), so its committed outputs are left intact. With the maintainer's full
env, cell 28 collapses to:

aa.plot_settings()
df_eval = pd.DataFrame({
    "group":     ["Scale-based"] * 3 + ["CPP"] * 3,
    "condition": cols * 2,
    "value":     res_scale + res_cpp,
})
aa.plot_comparison(df_eval, baseline=50, baseline_label="random (50%)",
                   colors={"Scale-based": "tab:gray", "CPP": "tab:red"},
                   ylabel="Balanced accuracy [%]", ylim=(0, 108),
                   title="Feature engineering x data expansion")
plt.tight_layout(); plt.show()

This removes the manual offsets, the per-bar ax.text loop, and the axhline —
the issue KPI. The example notebook in this PR renders the equivalent figure.

BLOCKED / TODO

• Re-run γ-secretase use_case1_gamma_secretase.ipynb with xgboost installed and
  swap cell 28 to the snippet above (could not execute here).

🤖 Generated with Claude Code

---

Critical self-review (review-and-improve pass)

Rendered the figure to PNG across several scenarios (percent, fractional AUC,
5 groups, tall bars) and inspected for real defects. Found and fixed:

• Value labels broke on fractional metrics (major). The hardcoded f"{h:.0f}"
  rendered AUC-style values in [0, 1] as "0"/"1" for every bar (0.62, 0.72,
  0.82, 0.92 all became "1"). Added _auto_annotation_fmt (no decimals for
  integer-valued scores, two decimals for fractional, one otherwise) plus an
  explicit annotation_fmt override.
• Legend overlapped the data (major, plot quality). The inside ax.legend()
  sat on top of the tallest bars and clipped their value labels (e.g. the "94"
  label vanished behind the legend box). Moved the legend outside the axes
  (upper right, frameless) so it never collides with bars or labels.
• Return type now (fig, ax) to match the sibling plot_rank (same epic)
  instead of a bare Axes — the open question flagged in the original PR body is
  resolved toward the family convention. Tests and the example notebook updated to
  unpack fig, ax.
• Cryptic error on non-distinct columns. Passing the same column for two of
  group/condition/value produced an opaque pandas groupby error; added an
  explicit up-front ValueError.
• Broken cross-reference. See Also pointed to a non-existent
  aaanalysis.plot_eval_heatmap; repointed to the real aaanalysis.pipe.plot_eval
  and added plot_rank.
• Minor: extend the y headroom slightly even when annotate=False; validate
  annotation_fmt in the Validate block.

Tests: 39 unit tests (adds fractional-precision, mean-aggregation, annotation_fmt,
distinct-column, and (fig, ax) cases) plus param_coverage / backend-import-hygiene
green; docstring checker 0 defects (the advisory RAISES-UNDOCUMENTED is consistent
with plot_rank, which also omits a Raises section); the example notebook
re-executes under nbmake with embedded outputs.

Residual: the library default palette (plot_get_clist) is used for auto colors;
the tab:gray/tab:red literals appear only in user-facing example/test call sites
(demonstrating the colors arg), not in library code. The γ-secretase notebook
swap remains blocked on xgboost in the agent env (unchanged from the original PR).

Iterative review log

• Round 2 (correctness & edge cases): fixed a duplicate entry in group_order/condition_order (cryptic TypeError / silent extra x-tick + wrong bar count) by de-duplicating the explicit order; added an up-front ValueError for a non-numeric value column (was a cryptic pandas mean error). +4 regression tests (dup group/condition order, partial grid, non-numeric value).
• Round 3 (plot quality): rendered percent + fractional values, 2/5 groups, tall bars, and long condition names under plot_settings() + default rcParams. Found the free-floating chance (...) baseline text overlapped the bars when the baseline sat near bar heights (AUC vs 0.5); moved it into the outside legend via the axhline label. Added an additive xtick_rotation arg (default 0, output unchanged) so long condition names stay legible. Residual: on very dense clusters (>=5 groups) adjacent per-bar value labels can still touch — inherent to value labels on narrow bars.
• Round 4 (efficiency & simplicity): hoisted the loop-invariant 0.01*max(heights_max,1) label gap out of the per-bar annotation loop and replaced .values.astype(float) with a single to_numpy(dtype=float) conversion. Output byte-identical (46 tests unchanged). No dead code / redundant validation found otherwise; the empty/distinct-column/bar_width==0 guards each cover a case check_df/check_number_range do not.
• Round 5 (guides, docs & tests): frontend Validate covers every public param (including the new xtick_rotation, positive+negative tested); no ADR refs / print / tab: literals in library code; docstring checker 0 defects (RAISES advisory matches sibling plot_rank), doc/signature drift 0; (fig, ax) return matches sibling plot_rank. Refreshed + re-executed the example notebook (nbmake green, embedded PNGs) to cover xtick_rotation and the legend baseline. Full local gate: plotting + api meta-tests 507 passed.