tsdynamics 5.2.2__tar.gz → 5.2.3__tar.gz

{tsdynamics-5.2.2 → tsdynamics-5.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsdynamics
-Version: 5.2.2
+Version: 5.2.3
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent

{tsdynamics-5.2.2 → tsdynamics-5.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "tsdynamics"
-version = "5.2.2"
+version = "5.2.3"
 description = "Zero-warmup Rust-engine ODE/DDE/SDE integration, discrete maps, and chaos analysis for dynamical systems."
 readme = "README.md"
 requires-python = ">=3.12,<4.0"

{tsdynamics-5.2.2 → tsdynamics-5.2.3}/src/tsdynamics/__init__.py

@@ -46,9 +46,10 @@ Reachable submodules (bound on the top-level namespace, so they show up in
   capability.
 - :mod:`~tsdynamics.errors` — the :class:`~tsdynamics.errors.TSDynamicsError`
   hierarchy that public entry points raise.
-- :mod:`~tsdynamics.viz` — the backend-agnostic ``PlotSpec`` IR (no renderer
-  ships yet).  Resolved **lazily** (via ``__getattr__``) so a plain
-  ``import tsdynamics`` pulls in no plotting machinery.
+- :mod:`~tsdynamics.viz` — the backend-agnostic ``PlotSpec`` IR plus its
+  self-registering renderers (matplotlib / Plotly / JSON / three.js).  Resolved
+  **lazily** (via ``__getattr__``) so a plain ``import tsdynamics`` pulls in no
+  plotting machinery — ``ts.viz`` imports it (and caches it) on first access.
 - :mod:`~tsdynamics.engine`, :mod:`~tsdynamics.solvers` — advanced/internal: the
   Rust-facing compile/run seam and the solver registry.  Reachable for inspection
   but rarely imported directly.
@@ -362,10 +363,10 @@ bifurcation_diagram = orbit_diagram  #: discoverable spelling of :func:`orbit_di
 basins = basins_of_attraction  #: short alias of :func:`basins_of_attraction`
 
 # Single source of truth for the package version; rewritten by python-semantic-release.
-__version__ = "5.2.2"
+__version__ = "5.2.3"
 
 # Built-in system classes are NOT bound into this namespace — that would bury the
-# submodules (``analysis``, ``data``, ``systems``, …) under ~149 model names in
+# submodules (``analysis``, ``data``, ``systems``, …) under ~150 model names in
 # ``dir()`` / autocomplete. The canonical path is ``tsdynamics.systems.<Name>``
 # (e.g. ``tsdynamics.systems.Lorenz``). For backwards compatibility, ``tsd.Lorenz``
 # and ``from tsdynamics import Lorenz`` still resolve, lazily, via ``__getattr__``
@@ -429,7 +430,7 @@ def __getattr__(name: str) -> Any:
     * ``tsdynamics.viz`` — imported on first access (and cached) so a plain
       ``import tsdynamics`` pulls in no plotting/IR machinery; ``viz`` still shows
       in ``__all__`` / ``dir()`` for discoverability.
-    * ``tsdynamics.Lorenz`` and friends — the ~149 built-in system classes,
+    * ``tsdynamics.Lorenz`` and friends — the ~150 built-in system classes,
       resolved from :mod:`tsdynamics.systems` (the canonical path) instead of
       binding all of them into the namespace, which keeps ``dir()`` / autocomplete
       focused on the curated public API.

tsdynamics-5.2.3/src/tsdynamics/analysis/_plotbuilder.py

@@ -0,0 +1,434 @@
+"""Analysis-facing :class:`~tsdynamics.viz.spec.PlotSpec` builder (the result-side seam).
+
+The trajectory side funnels every plot through the parameterised
+:mod:`tsdynamics.viz.producers`; the **analysis** side — the ~two-dozen
+:class:`~tsdynamics.analysis._result.AnalysisResult` ``to_plot_spec`` methods —
+used to each hand-assemble the same ``Layer(...)`` / ``Axis(...)`` /
+``PlotSpec(...)`` boilerplate inline.  This module is the analysis counterpart of
+the producers: a handful of small, engine-free, backend-free helpers that
+encapsulate the recurring build-layers / set-axes / wrap-and-copy-meta patterns,
+so a result class describes *what* it draws (a scaling fit, a diagnostic curve, a
+sparse recurrence scatter, a bar readout, an image) and the IR vocabulary lives
+**here**, in one place, instead of being threaded through every result module.
+
+Like the producers it imports the :mod:`tsdynamics.viz.spec` IR **lazily** (every
+function-body import is deferred), so building a result — or merely importing
+:mod:`tsdynamics` — never pulls a plotting library.
+
+The catalogue
+-------------
+Two layers of helper:
+
+- **Layer / annotation constructors** — :func:`line`, :func:`line3d`,
+  :func:`scatter`, :func:`markers`, :func:`bar`, :func:`image`, :func:`area`,
+  :func:`errorbar`, :func:`histogram` (one per low-level mark a result draws) and
+  :func:`vline` / :func:`hline` / :func:`span` / :func:`text` (the reference
+  overlays).  A result builds its drawables with these and never names a raw
+  :class:`~tsdynamics.viz.spec.PlotKind` mark.
+- **Spec assemblers** — :func:`spec` (the general "resolve the kind, set the
+  labelled axes, attach legend / colorbar / annotations / meta" wrapper every
+  bespoke site shares) plus the named-pattern shortcuts :func:`scaling_fit` (the
+  log--log SCATTER + fit-region MARKERS + fit LINE schema the dimension /
+  Lyapunov-from-data estimators emit) and :func:`diagonal` (the ``y = x``
+  reference line a return map / cobweb draws under its scatter).
+
+Every produced spec uses only the closed
+:class:`~tsdynamics.viz.spec.Layer` channel vocabulary and the frozen
+:class:`~tsdynamics.viz.spec.PlotKind` enum, so it round-trips losslessly through
+:meth:`~tsdynamics.viz.spec.PlotSpec.to_dict` /
+:meth:`~tsdynamics.viz.spec.PlotSpec.from_dict` exactly as the hand-built specs
+did — this is a *refactor*, output-equivalent by construction.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from tsdynamics.viz.spec import Annotation, Layer, PlotKind, PlotSpec
+
+__all__ = [
+    "area",
+    "bar",
+    "diagonal",
+    "errorbar",
+    "histogram",
+    "hline",
+    "image",
+    "line",
+    "line3d",
+    "markers",
+    "scaling_fit",
+    "scatter",
+    "spec",
+    "text",
+    "vline",
+]
+
+
+# ---------------------------------------------------------------------------
+# Layer constructors (one per low-level mark a result draws)
+# ---------------------------------------------------------------------------
+
+
+def _layer(
+    mark: str,
+    data: Mapping[str, Any],
+    *,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build one :class:`~tsdynamics.viz.spec.Layer` (the lazy-import choke point)."""
+    from tsdynamics.viz.spec import Layer, PlotKind
+
+    return Layer(
+        PlotKind(mark),
+        dict(data),
+        label=label,
+        style=dict(style) if style else {},
+    )
+
+
+def line(
+    x: Any,
+    y: Any,
+    *,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build a 2-D ``LINE`` layer over ``(x, y)``."""
+    return _layer("line", {"x": x, "y": y}, label=label, style=style)
+
+
+def line3d(
+    x: Any,
+    y: Any,
+    z: Any,
+    *,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build a 3-D ``LINE3D`` layer over ``(x, y, z)``."""
+    return _layer("line3d", {"x": x, "y": y, "z": z}, label=label, style=style)
+
+
+def scatter(
+    x: Any,
+    y: Any,
+    *,
+    cat: Any = None,
+    c: Any = None,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build a 2-D ``SCATTER`` point cloud over ``(x, y)``.
+
+    ``cat`` (per-point category index, paired with a categorical palette) and
+    ``c`` (per-point scalar colour field) are optional extra channels.
+    """
+    data: dict[str, Any] = {"x": x, "y": y}
+    if cat is not None:
+        data["cat"] = cat
+    if c is not None:
+        data["c"] = c
+    return _layer("scatter", data, label=label, style=style)
+
+
+def markers(
+    x: Any,
+    y: Any,
+    *,
+    z: Any = None,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build a ``MARKERS`` layer over ``(x, y)`` (a few points), optionally 3-D (``z``)."""
+    data: dict[str, Any] = {"x": x, "y": y}
+    if z is not None:
+        data["z"] = z
+    return _layer("markers", data, label=label, style=style)
+
+
+def bar(
+    y: Any,
+    *,
+    x: Any = None,
+    cat: Any = None,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build a ``BAR`` layer of heights ``y``, positioned by ``x`` (index) or ``cat`` (category)."""
+    data: dict[str, Any] = {"y": y}
+    if cat is not None:
+        data["cat"] = cat
+    if x is not None:
+        data["x"] = x
+    return _layer("bar", data, label=label, style=style)
+
+
+def image(
+    c: Any,
+    *,
+    x: Any = None,
+    y: Any = None,
+    z: Any = None,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build an ``IMAGE`` layer with color field ``c`` (and optional ``x`` / ``y`` / ``z``)."""
+    data: dict[str, Any] = {"c": c}
+    if x is not None:
+        data["x"] = x
+    if y is not None:
+        data["y"] = y
+    if z is not None:
+        data["z"] = z
+    return _layer("image", data, label=label, style=style)
+
+
+def area(
+    x: Any,
+    y: Any,
+    *,
+    lo: Any,
+    hi: Any,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build an ``AREA`` band layer (``lo <= hi`` envelope around ``y`` over ``x``)."""
+    return _layer("area", {"x": x, "y": y, "lo": lo, "hi": hi}, label=label, style=style)
+
+
+def errorbar(
+    x: Any,
+    y: Any,
+    err: Any,
+    *,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build an ``ERRORBAR`` layer (symmetric ``err`` magnitudes over ``(x, y)``)."""
+    return _layer("errorbar", {"x": x, "y": y, "err": err}, label=label, style=style)
+
+
+def histogram(
+    x: Any,
+    *,
+    label: str | None = None,
+    style: Mapping[str, Any] | None = None,
+) -> Layer:
+    """Build a ``HISTOGRAM`` layer over the sample values ``x``."""
+    return _layer("histogram", {"x": x}, label=label, style=style)
+
+
+# ---------------------------------------------------------------------------
+# Annotation constructors (reference lines / shaded bands / text overlays)
+# ---------------------------------------------------------------------------
+
+
+def vline(x: float, *, text: str = "", style: Mapping[str, Any] | None = None) -> Annotation:
+    """Build a vertical reference line at constant ``x``."""
+    from tsdynamics.viz.spec import Annotation
+
+    return Annotation(kind="vline", x=float(x), text=text, style=dict(style) if style else {})
+
+
+def hline(y: float, *, text: str = "", style: Mapping[str, Any] | None = None) -> Annotation:
+    """Build a horizontal reference line at constant ``y``."""
+    from tsdynamics.viz.spec import Annotation
+
+    return Annotation(kind="hline", y=float(y), text=text, style=dict(style) if style else {})
+
+
+def span(
+    lo: float,
+    hi: float,
+    *,
+    axis: str = "x",
+    text: str = "",
+    style: Mapping[str, Any] | None = None,
+) -> Annotation:
+    """Build a shaded band between ``lo`` and ``hi`` along ``axis`` (a rejection tail / fit region)."""
+    from tsdynamics.viz.spec import Annotation
+
+    return Annotation(
+        kind="span",
+        span=(float(lo), float(hi)),
+        axis=axis,  # type: ignore[arg-type]
+        text=text,
+        style=dict(style) if style else {},
+    )
+
+
+def text(x: float, y: float, label: str, *, style: Mapping[str, Any] | None = None) -> Annotation:
+    """Build a text overlay at ``(x, y)``."""
+    from tsdynamics.viz.spec import Annotation
+
+    return Annotation(
+        kind="text", x=float(x), y=float(y), text=label, style=dict(style) if style else {}
+    )
+
+
+# ---------------------------------------------------------------------------
+# Spec assemblers
+# ---------------------------------------------------------------------------
+
+
+def spec(
+    kind: str | None,
+    default: PlotKind | str,
+    *,
+    layers: Sequence[Layer],
+    xlabel: str = "",
+    ylabel: str = "",
+    zlabel: str | None = None,
+    title: str = "",
+    ndim: int | None = None,
+    aspect: str = "auto",
+    xlimits: tuple[float, float] | None = None,
+    ylimits: tuple[float, float] | None = None,
+    xscale: str = "linear",
+    yscale: str = "linear",
+    xcategories: Sequence[str] | None = None,
+    xticks: Sequence[float] | None = None,
+    annotations: Sequence[Annotation] | None = None,
+    legend: bool | Any = False,
+    colorbar: Any = None,
+    clim: tuple[float, float] | None = None,
+    meta: Mapping[str, Any] | None = None,
+) -> PlotSpec:
+    """Assemble a finished :class:`~tsdynamics.viz.spec.PlotSpec` from labelled axes + layers.
+
+    The single "resolve the semantic kind, build the labelled
+    :class:`~tsdynamics.viz.spec.Axis` pair (or triple), attach the optional
+    legend / colorbar / annotations / clim and copy meta" wrapper every bespoke
+    ``to_plot_spec`` opens and closes with.  ``kind`` is the caller's override (or
+    ``None``) and ``default`` the result's natural kind — resolved through the
+    closed :class:`~tsdynamics.viz.spec.PlotKind` vocabulary exactly as before.
+
+    ``ndim`` defaults to ``3`` when a ``zlabel`` is given, else ``2``.  ``legend``
+    accepts a ready :class:`~tsdynamics.viz.spec.Legend`, or ``True`` for a default
+    one, or ``False`` for none.  The ``meta`` mapping is shallow-copied onto the
+    spec (provenance is never shared by reference).
+    """
+    from tsdynamics.viz.spec import Axis, Legend, PlotKind, PlotSpec
+
+    spec_kind = PlotKind(kind) if kind is not None else PlotKind(default)
+    z_axis = Axis(label=zlabel) if zlabel is not None else None
+    resolved_ndim = ndim if ndim is not None else (3 if z_axis is not None else 2)
+
+    if legend is True:
+        legend_obj: Any = Legend()
+    elif legend is False:
+        legend_obj = None
+    else:
+        legend_obj = legend
+
+    return PlotSpec(
+        kind=spec_kind,
+        ndim=resolved_ndim,  # type: ignore[arg-type]
+        aspect=aspect,  # type: ignore[arg-type]
+        title=title,
+        x=Axis(
+            label=xlabel,
+            scale=xscale,  # type: ignore[arg-type]
+            limits=xlimits,
+            categories=xcategories,
+            ticks=xticks,
+        ),
+        y=Axis(label=ylabel, scale=yscale, limits=ylimits),  # type: ignore[arg-type]
+        z=z_axis,
+        layers=list(layers),
+        legend=legend_obj,
+        colorbar=colorbar,
+        clim=clim,
+        annotations=list(annotations) if annotations else [],
+        meta=dict(meta) if meta else {},
+    )
+
+
+def scaling_fit(
+    kind: str | None,
+    x: Any,
+    y: Any,
+    *,
+    fit_region: tuple[int, int],
+    slope: float,
+    line_y: Any | None = None,
+    intercept: float | None = None,
+    curve_label: str = "curve",
+    xlabel: str = "",
+    ylabel: str = "",
+    title: str = "",
+    default: PlotKind | str | None = None,
+    meta: Mapping[str, Any] | None = None,
+) -> PlotSpec:
+    r"""Build the log--log ``SCALING_FIT`` schema shared by every scaling estimator.
+
+    The recurring three-layer figure: a ``SCATTER`` of the whole ``(x, y)`` curve,
+    a ``MARKERS`` highlight of the fitted scaling region ``x[lo:hi+1]``, and a
+    ``LINE`` of the fit of the given ``slope`` drawn across the fit region — the
+    schema the fractal-dimension estimators, ``LyapunovFromData`` and the
+    uncertainty exponent all emit, so a single ``result.plot.scaling()`` renders
+    them identically.
+
+    The fit line is given **either** as a ready ``line_y`` array (already evaluated
+    at ``[x[lo], x[hi]]``, e.g. when the line is anchored to a centroid) **or** via
+    ``intercept`` (then ``y = intercept + slope * [x[lo], x[hi]]``).  The
+    fit-region layers are added only when the curve is non-empty and the region is
+    valid (``hi >= lo``).
+
+    Parameters
+    ----------
+    kind : str or None
+        The caller's semantic-kind override.
+    x, y : array-like
+        The log--log curve.
+    fit_region : tuple of int
+        ``(lo, hi)`` **inclusive** index bounds of the fitted scaling region.
+    slope : float
+        The estimated slope (the dimension / exponent) — used in the fit-line
+        label ``slope = <slope>``.
+    line_y : array-like, optional
+        The fit-line ordinates at ``[x[lo], x[hi]]``; mutually exclusive with
+        ``intercept``.
+    intercept : float, optional
+        The fit-line intercept (``y = intercept + slope * x``); used when
+        ``line_y`` is not given.
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    lo, hi = fit_region
+    layers: list[Layer] = [scatter(x, y, label=curve_label)]
+    if x.size and hi >= lo:
+        layers.append(markers(x[lo : hi + 1], y[lo : hi + 1], label="fit region"))
+        fit_x = np.array([x[lo], x[hi]], dtype=float)
+        if line_y is not None:
+            fit_y = np.asarray(line_y, dtype=float)
+        else:
+            fit_y = float(intercept if intercept is not None else 0.0) + slope * fit_x
+        layers.append(line(fit_x, fit_y, label=f"slope = {slope:.3g}"))
+    return spec(
+        kind,
+        default if default is not None else "scaling_fit",
+        layers=layers,
+        xlabel=xlabel,
+        ylabel=ylabel,
+        title=title,
+        meta=meta,
+    )
+
+
+def diagonal(x: Any, y: Any, *, label: str = "$v_{n+1}=v_n$") -> Layer:
+    r"""Build the ``y = x`` reference ``LINE`` spanning the combined range of ``x`` and ``y``.
+
+    The fixed-point locus a first-return map / cobweb draws under its scatter — a
+    line from ``(m, m)`` to ``(M, M)`` where ``[m, M]`` is the range of both
+    series combined.
+    """
+    both = np.concatenate([np.asarray(x, dtype=float), np.asarray(y, dtype=float)])
+    diag = np.array([float(both.min()), float(both.max())])
+    return line(diag, diag, label=label)

{tsdynamics-5.2.2 → tsdynamics-5.2.3}/src/tsdynamics/analysis/_result_array.py

@@ -11,7 +11,6 @@ from typing import Any, ClassVar
 
 import numpy as np
 
-from tsdynamics._result_common import resolve_plot_kind
 from tsdynamics.analysis._result_base import AnalysisResult
 from tsdynamics.analysis._result_json import _fmt, _jsonify
 from tsdynamics.analysis._result_viz import VisualizationNotInstalled
@@ -175,68 +174,57 @@ class ArrayResult(AnalysisResult):
         VisualizationNotInstalled
             If the array is empty or higher-than-2-D (nothing generic to draw).
         """
-        from tsdynamics.viz.spec import Axis, Layer, Legend, PlotKind, PlotSpec
+        from . import _plotbuilder as pb
 
         arr = np.asarray(self.values, dtype=float)
         title = type(self).__name__
-        meta = dict(self.meta) if self.meta else {}
 
         if arr.ndim == 1 and arr.size:
-            spec_kind = resolve_plot_kind(kind, PlotKind.DIAGNOSTIC_CURVE)
-            layer = Layer(PlotKind.LINE, {"x": np.arange(arr.size, dtype=float), "y": arr})
-            return PlotSpec(
-                kind=spec_kind,
-                ndim=2,
+            return pb.spec(
+                kind,
+                "diagnostic_curve",
+                layers=[pb.line(np.arange(arr.size, dtype=float), arr)],
+                xlabel="index",
+                ylabel="value",
                 title=title,
-                x=Axis(label="index"),
-                y=Axis(label="value"),
-                layers=[layer],
-                meta=meta,
+                meta=self.meta,
             )
 
         if arr.ndim == 2 and arr.shape[0] and arr.shape[1] in (2, 3):
             if arr.shape[1] == 3:
-                spec_kind = resolve_plot_kind(kind, PlotKind.PHASE_PORTRAIT_3D)
-                layer = Layer(PlotKind.LINE3D, {"x": arr[:, 0], "y": arr[:, 1], "z": arr[:, 2]})
-                return PlotSpec(
-                    kind=spec_kind,
-                    ndim=3,
+                return pb.spec(
+                    kind,
+                    "phase_portrait_3d",
+                    layers=[pb.line3d(arr[:, 0], arr[:, 1], arr[:, 2])],
+                    xlabel="x1",
+                    ylabel="x2",
+                    zlabel="x3",
                     title=title,
-                    x=Axis(label="x1"),
-                    y=Axis(label="x2"),
-                    z=Axis(label="x3"),
-                    layers=[layer],
-                    meta=meta,
+                    meta=self.meta,
                 )
-            spec_kind = resolve_plot_kind(kind, PlotKind.PHASE_PORTRAIT_2D)
-            layer = Layer(PlotKind.SCATTER, {"x": arr[:, 0], "y": arr[:, 1]})
-            return PlotSpec(
-                kind=spec_kind,
-                ndim=2,
+            return pb.spec(
+                kind,
+                "phase_portrait_2d",
+                layers=[pb.scatter(arr[:, 0], arr[:, 1])],
                 aspect="equal",
+                xlabel="x1",
+                ylabel="x2",
                 title=title,
-                x=Axis(label="x1"),
-                y=Axis(label="x2"),
-                layers=[layer],
-                meta=meta,
+                meta=self.meta,
             )
 
         if arr.ndim == 2 and arr.shape[0]:
-            spec_kind = resolve_plot_kind(kind, PlotKind.LINE_FAMILY)
             idx = np.arange(arr.shape[0], dtype=float)
-            layers = [
-                Layer(PlotKind.LINE, {"x": idx, "y": arr[:, j]}, label=f"[{j}]")
-                for j in range(min(arr.shape[1], 12))
-            ]
-            return PlotSpec(
-                kind=spec_kind,
-                ndim=2,
-                title=title,
-                x=Axis(label="index"),
-                y=Axis(label="value"),
+            layers = [pb.line(idx, arr[:, j], label=f"[{j}]") for j in range(min(arr.shape[1], 12))]
+            return pb.spec(
+                kind,
+                "line_family",
                 layers=layers,
-                legend=Legend(),
-                meta=meta,
+                xlabel="index",
+                ylabel="value",
+                title=title,
+                legend=True,
+                meta=self.meta,
             )
 
         raise VisualizationNotInstalled(

{tsdynamics-5.2.2 → tsdynamics-5.2.3}/src/tsdynamics/analysis/_result_base.py

@@ -15,7 +15,6 @@ from typing import TYPE_CHECKING, Any, ClassVar
 
 import numpy as np
 
-from tsdynamics._result_common import resolve_plot_kind
 from tsdynamics.analysis._result_json import _fmt, _is_frame_scalar, _jsonify
 from tsdynamics.analysis._result_viz import VisualizationNotInstalled, _PlotAccessor
 
@@ -289,37 +288,32 @@ class AnalysisResult:
             bespoke ``to_plot_spec`` is required.  Subclasses with such a result
             override this method.
         """
-        from tsdynamics.viz.spec import Axis, Layer, PlotKind, PlotSpec
+        from . import _plotbuilder as pb
 
-        spec_kind = resolve_plot_kind(kind, PlotKind.DIAGNOSTIC_CURVE)
         arrays, scalars = self._plottable_fields()
 
-        layers: list[Layer] = []
+        layers = []
         xlabel, ylabel = "index", "value"
         if len(arrays) >= 2 and arrays[0][1].size == arrays[1][1].size:
             (xname, x), (yname, y) = arrays[0], arrays[1]
-            layers.append(Layer(PlotKind.LINE, {"x": x, "y": y}, label=yname))
+            layers.append(pb.line(x, y, label=yname))
             xlabel, ylabel = xname, yname
         elif arrays:
             yname, y = arrays[0]
-            layers.append(
-                Layer(PlotKind.LINE, {"x": np.arange(y.size, dtype=float), "y": y}, label=yname)
-            )
+            layers.append(pb.line(np.arange(y.size, dtype=float), y, label=yname))
             ylabel = yname
         elif scalars:
             names = [n for n, _ in scalars]
             vals = np.array([v for _, v in scalars], dtype=float)
-            layers.append(
-                Layer(PlotKind.MARKERS, {"x": np.arange(vals.size, dtype=float), "y": vals})
-            )
-            return PlotSpec(
-                kind=spec_kind,
-                ndim=2,
+            return pb.spec(
+                kind,
+                "diagnostic_curve",
+                layers=[pb.markers(np.arange(vals.size, dtype=float), vals)],
+                xlabel="field",
+                xticks=list(range(len(names))),
+                ylabel="value",
                 title=type(self).__name__,
-                x=Axis(label="field", ticks=list(range(len(names)))),
-                y=Axis(label="value"),
-                layers=layers,
-                meta=dict(self.meta) if self.meta else {},
+                meta=self.meta,
             )
         else:
             raise VisualizationNotInstalled(
@@ -328,14 +322,14 @@ class AnalysisResult:
                 "bespoke to_plot_spec(); export it with .to_dict() meanwhile."
             )
 
-        return PlotSpec(
-            kind=spec_kind,
-            ndim=2,
-            title=type(self).__name__,
-            x=Axis(label=xlabel),
-            y=Axis(label=ylabel),
+        return pb.spec(
+            kind,
+            "diagnostic_curve",
             layers=layers,
-            meta=dict(self.meta) if self.meta else {},
+            xlabel=xlabel,
+            ylabel=ylabel,
+            title=type(self).__name__,
+            meta=self.meta,
         )
 
     def overlay_on(self, base: PlotSpec, *, kind: str | None = None) -> PlotSpec: