# Legacy Plotting Reference (Maintenance Only)

This document captures the **legacy plotting contracts** and **rendering semantics** for maintenance and debugging. It is **not** a normative architecture decision and is not required for new rendering backends. The legacy matplotlib renderer remains the canonical reference for pixel-level behaviour.

Source of truth:
- `src/calibrated_explanations/legacy/plotting.py`

## Status
- ADR-024 / ADR-025: superseded — do not reintroduce ADR-enforced contract changes for legacy plotting. This maintenance reference documents the current observed behaviors and conventions and is the canonical source for stability-focused fixes.

## Input contracts (summary)
- Legacy entry points: `_plot_probabilistic`, `_plot_regression`, `_plot_triangular`, `_plot_alternative`, `_plot_global`.
- `show=False` and missing `path/title` short-circuits rendering and bypasses matplotlib dependency checks.
- `save_ext` defaults to `("svg", "pdf", "png")`; filenames are built as `path + title + ext` without separators.
- Instance plots require aligned `features_to_plot` and `instance` arrays and optional `column_names` for labels.
- Interval rendering depends on `interval=True`, non-null `idx`, and non-one-sided explanations.
- Global plots rely on the explainer’s `predict`/`predict_proba` and build uncertainty as `high - low`.

## Rendering semantics (summary)
- Figure width is fixed at 10 inches; height scales with `num_to_show`.
- Probability and interval gauges are drawn with layered `fill_betweenx` bands.
- Classification and regression swap colour palettes and axis labels as described in the legacy code.
- Alternative and triangular plots rely on helper routines (`__plot_proba_triangle`, `__color_brew`, `__get_fill_color`).
- `_plot_global` always calls `plt.show()` unless `show=False` is provided.

## Fallback & visibility policy
- Legacy plot code follows the repo-wide fallback visibility policy: any runtime fallback or simplification MUST emit an `INFO` log and a `warnings.warn(..., UserWarning)` (see `.github/copilot-instructions.md` and `docs/improvement/RELEASE_PLAN_v1.md`). Tests that rely on fallbacks should assert the warning via `pytest.warns(UserWarning)`.

## Testing guidance
- Existing legacy plotting regression tests live in `tests/legacy/test_plotting.py`. Prefer extending these for fixes to preserve image parity.
- For new tests that exercise fallback behavior, use `pytest.warns(UserWarning)` to assert visible fallbacks.
- When comparing images, prefer pixel-tolerant assertions or checksum comparisons produced by the existing image-fixture tooling (see `tests/legacy/README.md` if present).

## When to consult this doc
- Regression or bugfix work on legacy plots.
- Debugging parity regressions against historical images.
- Supporting tests that inspect exported primitives from the legacy renderer.

For detailed behaviour, consult `src/calibrated_explanations/legacy/plotting.py` and the in-code comments around each helper.