Add optional matplotlib plotting API faithful to R NNS colors

Introduce `nns.plotting`, an optional (`ovvo-nns[plot]`) visual plotting
subpackage that is color/element-faithful to R NNS `plot = TRUE` output but
not pixel-diffed.

- pyproject: add `[plot]` optional extra (matplotlib>=3.7); keep core
  NumPy/SciPy-only; matplotlib imported lazily per function with a clear
  ImportError when absent. Add mypy override for matplotlib.*.
- palette.py: pin exact R grDevices hex, flagging the fidelity traps where R
  and matplotlib disagree (green -> #00FF00, grey -> #BEBEBE); rainbow() emulates
  R's HSV rainbow(n).
- Plot functions for reg, part, arma, arma_optim, cdf/VaR, fsd/ssd/tsd, anova,
  causation, norm, seas, diff, and copula. Each takes a computed result (or the
  same inputs) plus ax=None, returns the Axes, and never calls plt.show().
- tests/plotting: Agg-backend tests asserting artist colors and which element
  they sit on (no pixel/PDF comparison); palette trap tests; lazy-import tests.
- docs/plot_parity_policy.md + README: document the new opt-in API.
- CI: install the plot extra and run the plotting color-fidelity tests.

Author: claude

.github/workflows/native-backend-ci.yml

@@ -27,9 +27,10 @@ jobs:
           python -m pip install -U pip
           python -m pip install build scikit-build-core nanobind pytest ruff mypy numpy scipy
           python -m pip install hypothesis pytest-benchmark pytest-xdist
+          python -m pip install "matplotlib>=3.7"
 
-      - name: Install package editable
-        run: python -m pip install -e .
+      - name: Install package editable (with optional plot extra)
+        run: python -m pip install -e ".[plot]"
 
       - name: Run native import smoke test
         run: python -c "import nns._nnscore as c; print(c.lpm(2.0, 0.0, [-2.0, -1.0, 0.5, 3.0]))"
@@ -40,6 +41,9 @@ jobs:
       - name: Run parity from committed R cache
         run: NNS_R_CACHE_ONLY=1 python -m pytest -q tests/parity
 
+      - name: Run plotting color-fidelity tests
+        run: python -m pytest -q tests/plotting
+
       - name: Run vignette examples
         run: |
           if [ -f tests/docs/test_vignette_examples.py ]; then

README.md

@@ -39,6 +39,15 @@ The public package is Python-native and does not call R at runtime. Some core ke
 pip install ovvo-nns
 ```
 
+For the optional matplotlib plotting API (`nns.plotting`), install the extra:
+
+```bash
+pip install "ovvo-nns[plot]"
+```
+
+The core stays NumPy/SciPy-only; matplotlib is required only for `nns.plotting`
+and is imported lazily. See [`docs/plot_parity_policy.md`](docs/plot_parity_policy.md).
+
 Use the package as `nns`:
 
 ```python
@@ -138,7 +147,7 @@ Important boundaries:
 - Stochastic exact stream parity is not expected because Python paths use NumPy random generation.
 - Factor and class ordering should be passed explicitly when ordering matters.
 - Direct raw-factor `nns_m_reg(..., factor_2_dummy=True)` is intentionally guarded. Use `prepare_factor_predictors(...)` before `nns_m_reg(...)`.
-- Plotting arguments are generally ignored and data is returned instead.
+- Compute functions' `plot` arguments are ignored and data is returned instead; visual plotting is a separate opt-in API in `nns.plotting` (install `ovvo-nns[plot]`), color/element-faithful to R but not pixel-diffed.
 
 See [behavior conventions](docs/conventions.md) for detailed compatibility notes.
 

docs/plot_parity_policy.md

@@ -2,15 +2,38 @@
 
 ## Summary
 
-Graphics-device artifacts are **intentionally not compared** in CI parity. The
-parity suite validates the **returned values** of NNS functions, never the
-generated plots, PDFs, or other graphics-device output.
+Graphics-device artifacts are **intentionally not pixel-compared** in CI
+parity. The parity suite validates the **returned values** of NNS functions,
+never byte-/pixel-identical plot, PDF, or other graphics-device output.
 
 This is a deliberate, permanent policy decision — not an unresolved migration
 blocker. R plotting and Python plotting use different graphics stacks, and a
 faithful value-level port does not require byte-identical (or pixel-identical)
 plot artifacts.
 
+## A visual plotting API now exists (`nns.plotting`)
+
+The Python port now ships an **optional** plotting API in the `nns.plotting`
+subpackage (`pip install ovvo-nns[plot]`). It is **color/element-faithful to R
+but not pixel-diffed**: tests assert *artist colors and which element they sit
+on*, never rendered images.
+
+- matplotlib is an optional extra (`[project.optional-dependencies].plot`). The
+  NNS core stays NumPy/SciPy-only; matplotlib is imported lazily inside each
+  plot function and a clear `ImportError("install ovvo-nns[plot]")` is raised if
+  it is absent. matplotlib is **never** imported at package top level.
+- Each `plot_*` function takes an already-computed NNS result (or the same raw
+  inputs) plus a keyword `ax=None`, returns the `Axes`/`Figure`, and **never**
+  calls `plt.show()`. The compute functions' `plot=False` default behavior is
+  untouched; plotting is a separate opt-in call.
+- Colors are pinned in `nns.plotting.palette` to the exact R `grDevices` hex
+  used by `tools/NNS/R/*.R`. R and matplotlib agree on `steelblue`/`red` but
+  **disagree** on `green` (R `#00FF00` vs mpl `#008000`) and `grey` (R `#BEBEBE`
+  vs mpl `#808080`); the palette pins those so the port stays faithful.
+- Plotting tests live in `tests/plotting/`, run on the headless `Agg` backend,
+  and assert `mcolors.to_hex(...)` of line/scatter/patch artists — **no**
+  pixel/PDF comparison.
+
 ## What is compared
 
 - Numeric return values (scalars, vectors, matrices, nested result dicts) from
@@ -46,9 +69,9 @@ any `*.pdf`, `plot3d`, or `rgl`; the CI workflow
 (`.github/workflows/native-backend-ci.yml`) runs only the invariant suite, the
 cache-only parity suite, `ruff`, `mypy`, and `python -m build`.
 
-## When (and only when) image comparison would be in scope
+## Image comparison remains out of scope
 
-Image or PDF comparison would only be considered if and when the Python package
-grows a real, first-class plotting API that needs validation. There is no such
-API today. Until one exists, no PDF/image comparison is attempted, and adding
-one is explicitly out of scope.
+Even though a first-class plotting API (`nns.plotting`) now exists, image or PDF
+comparison is still **out of scope**. The API is validated by asserting artist
+colors and the element each color sits on (faithful to R's `col=` usage), which
+is sufficient for a value-level port. No PDF/image diffing is attempted.

pyproject.toml

@@ -37,9 +37,15 @@ dependencies = [
     "scipy",
 ]
 
+[project.optional-dependencies]
+# Optional visual plotting API. The core stays NumPy/SciPy-only; install with
+#   pip install ovvo-nns[plot]
+plot = ["matplotlib>=3.7"]
+
 [dependency-groups]
 dev = [
     "hypothesis",
+    "matplotlib>=3.7",
     "mypy",
     "pytest",
     "pytest-benchmark",
@@ -113,6 +119,11 @@ strict = true
 files = ["src/nns", "tests"]
 mypy_path = ["tests"]
 
+# matplotlib is an optional extra; allow type-checking without it installed.
+[[tool.mypy.overrides]]
+module = ["matplotlib.*"]
+ignore_missing_imports = true
+
 [tool.cibuildwheel]
 # Native (C++17 / nanobind) extension: build CPython wheels across 3.11-3.13.
 # scikit-build-core fetches cmake/ninja as build deps, so no system CMake needed.

src/nns/plotting/__init__.py

@@ -0,0 +1,70 @@
+"""Optional matplotlib plotting API for NNS, faithful to R NNS ``plot = TRUE``.
+
+This subpackage is an **optional extra**. The NNS core stays NumPy/SciPy-only;
+matplotlib is required only here and is imported lazily inside each plot
+function (``pip install ovvo-nns[plot]``).
+
+Design contract for every ``plot_*`` function:
+
+* Accept an already-computed NNS result (or the same raw inputs) plus a keyword
+  ``ax=None`` and return the matplotlib ``Axes`` (or ``Figure`` for 3-D).
+* Never call ``plt.show()`` -- the caller controls display and saving.
+* Be **color/element-faithful** to R (see :mod:`nns.plotting.palette`), not
+  pixel-diffed.
+
+Colors are exposed via :mod:`nns.plotting.palette`; the only same-named colors
+that must *not* be trusted from matplotlib are ``green`` (-> ``#00FF00``) and
+``grey`` (-> ``#BEBEBE``).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from nns.plotting import palette as palette
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from nns.plotting.anova import plot_nns_anova as plot_nns_anova
+    from nns.plotting.arma import plot_nns_arma as plot_nns_arma
+    from nns.plotting.arma import plot_nns_arma_optim as plot_nns_arma_optim
+    from nns.plotting.causation import plot_nns_causation as plot_nns_causation
+    from nns.plotting.copula import plot_nns_copula as plot_nns_copula
+    from nns.plotting.differentiation import plot_nns_diff as plot_nns_diff
+    from nns.plotting.dominance import plot_fsd as plot_fsd
+    from nns.plotting.dominance import plot_ssd as plot_ssd
+    from nns.plotting.dominance import plot_tsd as plot_tsd
+    from nns.plotting.normalization import plot_nns_norm as plot_nns_norm
+    from nns.plotting.partial_moments import plot_nns_cdf as plot_nns_cdf
+    from nns.plotting.regression import plot_nns_part as plot_nns_part
+    from nns.plotting.regression import plot_nns_reg as plot_nns_reg
+    from nns.plotting.seasonality import plot_nns_seas as plot_nns_seas
+
+_EXPORTS = {
+    "plot_nns_anova": ("nns.plotting.anova", "plot_nns_anova"),
+    "plot_nns_arma": ("nns.plotting.arma", "plot_nns_arma"),
+    "plot_nns_arma_optim": ("nns.plotting.arma", "plot_nns_arma_optim"),
+    "plot_nns_causation": ("nns.plotting.causation", "plot_nns_causation"),
+    "plot_nns_copula": ("nns.plotting.copula", "plot_nns_copula"),
+    "plot_nns_diff": ("nns.plotting.differentiation", "plot_nns_diff"),
+    "plot_fsd": ("nns.plotting.dominance", "plot_fsd"),
+    "plot_ssd": ("nns.plotting.dominance", "plot_ssd"),
+    "plot_tsd": ("nns.plotting.dominance", "plot_tsd"),
+    "plot_nns_norm": ("nns.plotting.normalization", "plot_nns_norm"),
+    "plot_nns_cdf": ("nns.plotting.partial_moments", "plot_nns_cdf"),
+    "plot_nns_part": ("nns.plotting.regression", "plot_nns_part"),
+    "plot_nns_reg": ("nns.plotting.regression", "plot_nns_reg"),
+    "plot_nns_seas": ("nns.plotting.seasonality", "plot_nns_seas"),
+}
+
+__all__ = sorted((*_EXPORTS, "palette"))
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _EXPORTS:
+        raise AttributeError(f"module 'nns.plotting' has no attribute {name!r}")
+    from importlib import import_module
+
+    module_name, attr_name = _EXPORTS[name]
+    value = getattr(import_module(module_name), attr_name)
+    globals()[name] = value
+    return value

src/nns/plotting/_mpl.py

@@ -0,0 +1,57 @@
+"""Lazy matplotlib loading for the optional plotting API.
+
+matplotlib is an *optional* extra (``pip install ovvo-nns[plot]``). It is never
+imported at package import time; every plot function calls :func:`require_mpl`
+to import it on demand and raises a clear, actionable error if it is absent.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from matplotlib.axes import Axes
+
+_INSTALL_HINT = (
+    "matplotlib is required for nns.plotting. Install the optional extra with "
+    "`pip install ovvo-nns[plot]`."
+)
+
+
+def require_mpl() -> Any:
+    """Import and return the ``matplotlib.pyplot`` module, or raise ImportError."""
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError as exc:  # pragma: no cover - exercised via test monkeypatch
+        raise ImportError(_INSTALL_HINT) from exc
+    return plt
+
+
+def horizontal_boxplot(ax: Axes, data: Any, **kwargs: Any) -> Any:
+    """``ax.boxplot`` rendered horizontally, compatible across matplotlib versions.
+
+    ``vert=`` was deprecated for ``orientation=`` in matplotlib 3.11; prefer the
+    new keyword when present and fall back to the old one for >= 3.7.
+    """
+    import matplotlib
+
+    version = tuple(int(p) for p in matplotlib.__version__.split(".")[:2])
+    if version >= (3, 11):
+        return ax.boxplot(data, orientation="horizontal", **kwargs)
+    return ax.boxplot(data, vert=False, **kwargs)
+
+
+def resolve_ax(ax: Axes | None) -> Axes:
+    """Return ``ax`` if given, otherwise create a fresh Axes.
+
+    Plot functions never call ``plt.show()``; they return the Axes/Figure so the
+    caller controls display and saving.
+    """
+    if ax is not None:
+        return ax
+    plt = require_mpl()
+    _, new_ax = plt.subplots()
+    return cast("Axes", new_ax)
+
+
+__all__ = ["require_mpl", "resolve_ax"]

src/nns/plotting/anova.py

@@ -0,0 +1,46 @@
+"""Plot for ``nns_anova`` (R: ANOVA.R)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from nns.plotting import palette
+from nns.plotting._mpl import horizontal_boxplot, resolve_ax
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from matplotlib.axes import Axes
+
+
+def plot_nns_anova(
+    groups: Sequence[Any],
+    *,
+    medians: bool = False,
+    ax: Axes | None = None,
+) -> Axes:
+    """Plot ANOVA group boxplots, faithful to R ``NNS.ANOVA(..., plot = TRUE)``.
+
+    * first box: ``steelblue``; remaining boxes: ``rainbow(n - 1)``
+    * grand mean/median reference line (vertical): ``red``
+    """
+    ax = resolve_ax(ax)
+    arrays = [np.asarray(g, dtype=np.float64) for g in groups]
+    n = len(arrays)
+
+    bp = horizontal_boxplot(ax, arrays, patch_artist=True)
+    rest = palette.rainbow(n - 1)
+    facecolors = ["steelblue", *[tuple(c) for c in rest]]
+    for patch, color in zip(bp["boxes"], facecolors, strict=True):
+        patch.set_facecolor(color)
+
+    centers = [float(np.median(a)) if medians else float(np.mean(a)) for a in arrays]
+    grand = float(np.mean(centers))
+    ax.axvline(grand, color="red", linewidth=4)
+    ax.set_title("NNS ANOVA")
+    ax.set_xlabel("Grand Median" if medians else "Grand Mean")
+    return ax
+
+
+__all__ = ["plot_nns_anova"]