Add a real-data example notebook and run it in CI

[hamed]

Adds examples/census_income.ipynb — self-contained, committed with its outputs, and executed in CI like the quickstart.

What it shows

The existing examples measure hand-written toy rows and synthetic normal draws. They demonstrate the API, but not the thing the library exists for: deciding whether the gap between two models survives resampling.

This one downloads the Census Income ("Adult") set from OpenML, trains a gradient-boosted tree and a deliberately handicapped logistic regression, and runs the full pipeline over both.

	average precision (5–95)	recall @ precision ≥ 0.80 (5–95)	AUC (5–95)
gradient boosting	[0.816, 0.835]	[0.593, 0.639]	[0.925, 0.931]
logistic regression	[0.634, 0.660]	[0.227, 0.309]	[0.825, 0.836]

No pair overlaps, so the notebook ends on a decision instead of two bare numbers. 48,842 rows, 23.9% positive, 14,653 held out, 100 replicas.

Why this dataset

Measured the alternatives against the same pipeline before choosing:

dataset	AP band width	verdict
iris (setosa vs rest)	0.000	perfectly separable — invisible band
iris (versicolor vs virginica)	0.000	same
breast_cancer	0.015	AUC 0.994, band hugs the ceiling
census income	0.017 / 0.025, on metrics at 0.83 and 0.65	genuinely hard

Iris and breast_cancer are bundled and need no network, which is why they were the obvious candidates — but logistic regression is near-perfect on both, the band collapses, and the resulting figure argues against the library. Census Income is hard enough that the intervals carry information.

CI

The notebook job gains a step and now guards both notebooks in the working tree. The checker compares text/plain payloads, so every printed number is pinned — a change that moves a metric fails the build, which is the regression signal you asked for.

Verified reproducible: executed, then re-executed through scripts/check_example_notebook.py, matching. Both models are bitwise-deterministic across runs on fixed seeds, and the house float_format = "{:.3f}" absorbs floating-point jitter across machines.

This costs the notebook job a network dependency on OpenML. A fetch failure there is a flake, not a package defect; the comment in test.yml says so. Runtime is about 10 seconds — the whole replicas pipeline over 2.96M bootstrapped rows takes ~4.5s.

Portability details

• The AUC cell selects its columns before groupby.apply rather than passing include_groups=False, which needs pandas 2.2 — the notebook's own install line asks only for replicas[pandas,plot].
• The notebook extra declares scikit-learn>=1.4, the floor for HistGradientBoostingClassifier(categorical_features="from_dtype").
• Ruff flagged an unused pr_band import in the first draft; the notebook is linted like any other file now that Move the reference design notebook into docs/ #10 split the per-file ignores.

Note on the dataset

Census Income has documented baggage as a fairness benchmark (Ding et al., Retiring Adult, 2021). The notebook says so in prose, uses it only as a hard imbalanced classification problem, and does not facet any result by the race or sex columns.

Verification

ruff check, ruff format --check, 135 tests, and the notebook checker all pass.

🤖 Generated with Claude Code