Plotting 1.1 — cleanup, dependency audit, and docs

[drbenvincent]

Child of #1155 (1.1 declarative plotting migration). Depends on children A–F. Do not start early — deleting a helper before its last consumer is migrated is how #990 ended up with a duplicate-implementation cleanup commit.

Workflow

Branch from pymc6_and_pymcmarketing1_migration and open the PR against pymc6_and_pymcmarketing1_migration. Not main. See the parent issue for why.

Scope

Dead code

Delete plot_utils.py functions as their last consumer disappears — plot_posterior_over_x, _plot_ribbon, _plot_spaghetti, get_hdi_to_df, _equal_tailed_interval, _interval_bound_values, _plot_interval_band, _x_as_numeric_mesh. Check each one: some are used by tests and by the density overlay rather than by experiment code.

_plot_histogram and its mesh helper are expected to survive — the kind="histogram" density layer stays a matplotlib pcolormesh overlay because geom_tile does not work at these y-scales (see the dead-ends section of the parent issue).

Compute vs render

Resolve the duplication flagged in the #524 retro: get_plot_data_*() exists on the experiment classes, but the plot methods do not consume it and recompute predictions, impact, and intervals directly from self.pre_pred / self.post_impact and friends. Two independent code paths computing the same quantities will silently drift. Either make the plot path render from get_plot_data_*() output, or make one of them delegate to the other — but land a single source of truth. If this turns out to be substantial, split it into its own issue rather than bloating the cleanup PR.

Dependencies

Audit plotnine, polars, and tidydraws in pyproject.toml. Every plotting dependency that ships must actually be imported by causalpy/ — #1137 had to remove a tidydraws exact pin that nothing imported. Version constraints are ranges, not exact pins. environment.yml is regenerated by the pyproject2conda-yaml prek hook, never hand-edited.

Base class

Simplify BaseExperiment._render_plot if the shared seam has made parts of it redundant — in particular the arviz-darkgrid style context (per the Phase 0 theming decision) and the legend_kwargs in-place mutation, whose long docstring about plot_posterior_over_x return types will be stale once that function is gone. legend_kwargs behaviour itself is public and must not change.

Documentation and notebooks

• Update ARCHITECTURE.md with the plotting layer.
• Update docstrings and type annotations for each method's final return type.
• Re-render affected documentation notebooks. This is its own PR, after the code lands (guardrail G6). [plotting] Migrate plotting from matplotlib/xarray to tidydraws + plotnine (#988) #990 grew to 97 files and +57,952 / −28,869 largely because 28 re-rendered notebooks were committed alongside the plotting code, which made it unreviewable. Note also that some notebooks are slow or need optional dependencies (causalimpact, JAX/NumPyro) and could not be re-rendered on a laptop; plan for a faster host.
• Add a release-notes entry.

Close-out

Once everything above has landed: close #988's remaining scope, add a comment to #990 confirming the program is complete, and decide whether to finally delete the migrate-plotting-tidydraws-plotnine branch (until then it stays).

Acceptance criteria

• No unreachable plotting helpers remain; every surviving one has a named consumer.
• Single source of truth for plot-data computation, or a follow-up issue explicitly filed for it.
• No shipped plotting dependency is unimported; no exact pins.
• ARCHITECTURE.md, docstrings, and type annotations match reality.
• Notebook re-render lands as a separate PR.
• Release notes updated.
• prek run --all-files passes; make test-patch-cov passes; full suite green.

Out of scope

• Any remaining experiment migration — that belongs to the child that owns it.
• IPW and IV plots.