jarvisplot 2.1.5__tar.gz → 2.1.7__tar.gz

{jarvisplot-2.1.5 → jarvisplot-2.1.7}/JarvisPLOT.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: JarvisPLOT
-Version: 2.1.5
+Version: 2.1.7
 Summary: Jarvis-PLOT: YAML-driven plotting engine
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -160,12 +160,31 @@ The loop `jplot man` prints is:
    carry `JP-*` codes; `jplot explain JP-XXX-NNN` expands any of them.
 5. `jplot <file>` — render, only when the figure itself is needed.
 
-`jplot man --json` is the machine-readable manual: 15 topics, plus a
-live page for every one of the 28 layer methods and 11 transform steps
-(`jplot man scatter`, `jplot man transform.profile`). Method contracts come from
+`jplot man --json` is the machine-readable manual: a topic index, plus
+live pages for every registered layer method and transform step
+(`jplot man scatter`, `jplot man transform.profile`, `jplot man PDF1D`). Method contracts come from
 the same registry `jplot cap methods` reads, so a man page cannot drift from the
 code.
 
+For compact legends and keys composed from real layers, use
+`jplot man legend --json`. Declare `legend: {object, label, role}` on each drawing layer; components
+with the same object regroup automatically using card templates such as
+`band_line`, `line_errorbar` and `error_bounds`. The role is optional for a
+single-component object. `frame.<axes>.legend` owns card selection, `order`,
+`ncols`, position and spacing. JSON cards provide
+reusable defaults, and YAML can override them. See
+[the legend contract](docs/specs/LEGEND.md) and the
+[self-contained example](Example/compact_legend.yaml).
+
+For continuous one-dimensional distributions from raw samples, use `PDF1D`
+(CDF plus PDF) or `CDF1D` in a data transform. `coordinates.x` owns `expr`,
+`lim`, and `grid`; optional `repeat` computes independent batch means and
+standard deviations. See [the contract](docs/specs/PDF_CDF_1D.md) and the
+[runnable example](Example/pdf_cdf_1d.yaml).
+Reconstruction defaults to adaptive true CDF anchors and `monotone_c2`
+interpolation (C2 CDF / C1 PDF). Set `anchors: all` and `interpolation: pchip`
+to reproduce the original all-node reconstruction.
+
 Two things worth knowing before trusting a config:
 
 - `jplot validate` checks shape and contracts and never touches the data;

{jarvisplot-2.1.5 → jarvisplot-2.1.7}/JarvisPLOT.egg-info/SOURCES.txt

@@ -30,12 +30,14 @@ jarvisplot/data_loader_summary.py
 jarvisplot/dataset_types.py
 jarvisplot/diagnostic_guidance.py
 jarvisplot/diagnostics.py
+jarvisplot/distribution_1d_config.py
 jarvisplot/dryrun_runtime.py
 jarvisplot/expr_names.py
 jarvisplot/fix_apply.py
 jarvisplot/flowchart.py
 jarvisplot/generated_data.py
 jarvisplot/inner_func.py
+jarvisplot/legend_cards.py
 jarvisplot/man_catalog.py
 jarvisplot/man_methods.py
 jarvisplot/man_render_agent.py
@@ -53,6 +55,7 @@ jarvisplot/yaml_io.py
 jarvisplot/Figure/__init__.py
 jarvisplot/Figure/adapters_rect.py
 jarvisplot/Figure/adapters_ternary.py
+jarvisplot/Figure/adaptive_cdf_runtime.py
 jarvisplot/Figure/bin_stat_runtime.py
 jarvisplot/Figure/colorbar_runtime.py
 jarvisplot/Figure/config_runtime.py
@@ -65,6 +68,7 @@ jarvisplot/Figure/data_pipelines.py
 jarvisplot/Figure/debug_config.py
 jarvisplot/Figure/density_cell_runtime.py
 jarvisplot/Figure/design_runtime.py
+jarvisplot/Figure/distribution_1d_runtime.py
 jarvisplot/Figure/dynesty_runtime.py
 jarvisplot/Figure/figure.py
 jarvisplot/Figure/figure_types.py
@@ -74,6 +78,7 @@ jarvisplot/Figure/interp_natural_neighbor.py
 jarvisplot/Figure/interp_natural_neighbor_exact.py
 jarvisplot/Figure/layer_runtime.py
 jarvisplot/Figure/layout_runtime.py
+jarvisplot/Figure/legend_runtime.py
 jarvisplot/Figure/method_registry.py
 jarvisplot/Figure/posterior_density_runtime.py
 jarvisplot/Figure/posterior_hpd.py
@@ -117,6 +122,10 @@ jarvisplot/cards/icons/flowchart/inputfile.png
 jarvisplot/cards/icons/flowchart/opera.png
 jarvisplot/cards/icons/flowchart/outputfile.png
 jarvisplot/cards/icons/flowchart/sampler.png
+jarvisplot/cards/legends/compact/legend-card.json
+jarvisplot/cards/legends/default/legend-card.json
+jarvisplot/cards/legends/paper/legend-card.json
+jarvisplot/cards/legends/presentation/legend-card.json
 jarvisplot/manual_cards/agent-output.yaml
 jarvisplot/manual_cards/cli-map.yaml
 jarvisplot/manual_cards/data-columns.yaml
@@ -126,6 +135,7 @@ jarvisplot/manual_cards/dryrun-viz.yaml
 jarvisplot/manual_cards/field-interp.yaml
 jarvisplot/manual_cards/generated-data.yaml
 jarvisplot/manual_cards/layer-method.yaml
+jarvisplot/manual_cards/legend.yaml
 jarvisplot/manual_cards/manifest.yaml
 jarvisplot/manual_cards/method_notes.yaml
 jarvisplot/manual_cards/style-axes.yaml
@@ -139,9 +149,12 @@ jarvisplot/schema/manifest.json
 jarvisplot/schema/plot-config.json
 jarvisplot/schema/core/common.json
 jarvisplot/schema/core/dataset.json
+jarvisplot/schema/core/distribution-1d.json
 jarvisplot/schema/core/figure.json
 jarvisplot/schema/core/generated-data.json
 jarvisplot/schema/core/layer.json
+jarvisplot/schema/core/legend-card.json
+jarvisplot/schema/core/legend.json
 jarvisplot/schema/core/transform.json
 jarvisplot/schema/methods/bar.json
 jarvisplot/schema/methods/barh.json
@@ -190,6 +203,7 @@ jarvisplot/verbs/man.py
 jarvisplot/verbs/suggest.py
 jarvisplot/verbs/template.py
 jarvisplot/verbs/validate.py
+tests/test_adaptive_cdf.py
 tests/test_agent_digest.py
 tests/test_agent_envelope.py
 tests/test_axis_title.py
@@ -215,6 +229,7 @@ tests/test_debug_yaml_override.py
 tests/test_density_cell_transform.py
 tests/test_design_runtime.py
 tests/test_diagnostic_guidance.py
+tests/test_distribution_1d_transform.py
 tests/test_docs_status_labels.py
 tests/test_doctor_partial.py
 tests/test_explain.py
@@ -228,6 +243,9 @@ tests/test_interp_2d_transform.py
 tests/test_interp_natural_neighbor.py
 tests/test_interpolator_contracts.py
 tests/test_jpcontour_methods.py
+tests/test_layer_legend.py
+tests/test_legend_cards.py
+tests/test_legend_runtime.py
 tests/test_man_cli.py
 tests/test_method_contracts.py
 tests/test_parse_data_metadata.py

{jarvisplot-2.1.5 → jarvisplot-2.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: JarvisPLOT
-Version: 2.1.5
+Version: 2.1.7
 Summary: Jarvis-PLOT: YAML-driven plotting engine
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -160,12 +160,31 @@ The loop `jplot man` prints is:
    carry `JP-*` codes; `jplot explain JP-XXX-NNN` expands any of them.
 5. `jplot <file>` — render, only when the figure itself is needed.
 
-`jplot man --json` is the machine-readable manual: 15 topics, plus a
-live page for every one of the 28 layer methods and 11 transform steps
-(`jplot man scatter`, `jplot man transform.profile`). Method contracts come from
+`jplot man --json` is the machine-readable manual: a topic index, plus
+live pages for every registered layer method and transform step
+(`jplot man scatter`, `jplot man transform.profile`, `jplot man PDF1D`). Method contracts come from
 the same registry `jplot cap methods` reads, so a man page cannot drift from the
 code.
 
+For compact legends and keys composed from real layers, use
+`jplot man legend --json`. Declare `legend: {object, label, role}` on each drawing layer; components
+with the same object regroup automatically using card templates such as
+`band_line`, `line_errorbar` and `error_bounds`. The role is optional for a
+single-component object. `frame.<axes>.legend` owns card selection, `order`,
+`ncols`, position and spacing. JSON cards provide
+reusable defaults, and YAML can override them. See
+[the legend contract](docs/specs/LEGEND.md) and the
+[self-contained example](Example/compact_legend.yaml).
+
+For continuous one-dimensional distributions from raw samples, use `PDF1D`
+(CDF plus PDF) or `CDF1D` in a data transform. `coordinates.x` owns `expr`,
+`lim`, and `grid`; optional `repeat` computes independent batch means and
+standard deviations. See [the contract](docs/specs/PDF_CDF_1D.md) and the
+[runnable example](Example/pdf_cdf_1d.yaml).
+Reconstruction defaults to adaptive true CDF anchors and `monotone_c2`
+interpolation (C2 CDF / C1 PDF). Set `anchors: all` and `interpolation: pchip`
+to reproduce the original all-node reconstruction.
+
 Two things worth knowing before trusting a config:
 
 - `jplot validate` checks shape and contracts and never touches the data;

{jarvisplot-2.1.5 → jarvisplot-2.1.7}/README.md

@@ -138,12 +138,31 @@ The loop `jplot man` prints is:
    carry `JP-*` codes; `jplot explain JP-XXX-NNN` expands any of them.
 5. `jplot <file>` — render, only when the figure itself is needed.
 
-`jplot man --json` is the machine-readable manual: 15 topics, plus a
-live page for every one of the 28 layer methods and 11 transform steps
-(`jplot man scatter`, `jplot man transform.profile`). Method contracts come from
+`jplot man --json` is the machine-readable manual: a topic index, plus
+live pages for every registered layer method and transform step
+(`jplot man scatter`, `jplot man transform.profile`, `jplot man PDF1D`). Method contracts come from
 the same registry `jplot cap methods` reads, so a man page cannot drift from the
 code.
 
+For compact legends and keys composed from real layers, use
+`jplot man legend --json`. Declare `legend: {object, label, role}` on each drawing layer; components
+with the same object regroup automatically using card templates such as
+`band_line`, `line_errorbar` and `error_bounds`. The role is optional for a
+single-component object. `frame.<axes>.legend` owns card selection, `order`,
+`ncols`, position and spacing. JSON cards provide
+reusable defaults, and YAML can override them. See
+[the legend contract](docs/specs/LEGEND.md) and the
+[self-contained example](Example/compact_legend.yaml).
+
+For continuous one-dimensional distributions from raw samples, use `PDF1D`
+(CDF plus PDF) or `CDF1D` in a data transform. `coordinates.x` owns `expr`,
+`lim`, and `grid`; optional `repeat` computes independent batch means and
+standard deviations. See [the contract](docs/specs/PDF_CDF_1D.md) and the
+[runnable example](Example/pdf_cdf_1d.yaml).
+Reconstruction defaults to adaptive true CDF anchors and `monotone_c2`
+interpolation (C2 CDF / C1 PDF). Set `anchors: all` and `interpolation: pchip`
+to reproduce the original all-node reconstruction.
+
 Two things worth knowing before trusting a config:
 
 - `jplot validate` checks shape and contracts and never touches the data;

{jarvisplot-2.1.5 → jarvisplot-2.1.7}/jarvisplot/Figure/adapters_rect.py

@@ -36,7 +36,6 @@ class StdAxesAdapter:
         self._defaults = defaults or {}
         self._clip_path = clip_path  # None means no cropping
         self.config = self._load_internal_config()
-        self._legend = False
         self.status = "init"           # lifecycle: init -> configured -> drawn -> finalized
         self.needs_finalize = True      # allow some axes (e.g., logo) to opt out
 

jarvisplot-2.1.7/jarvisplot/Figure/adaptive_cdf_runtime.py

@@ -0,0 +1,131 @@
+"""Adaptive empirical-CDF anchors and a local, monotone C2 quintic interpolant.
+
+No bins, kernels, or nonlinear solver. The quartic PDF is represented in the
+Bernstein basis; nonnegative coefficients certify nonnegativity on each whole
+interval, rather than only at sampled output points.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from heapq import heappop, heappush
+
+import numpy as np
+from scipy.interpolate import BPoly, CubicSpline, PchipInterpolator
+
+from ..distribution_1d_config import AnchorSettings
+
+
+def monotone_c2(x: np.ndarray, y: np.ndarray) -> BPoly:
+    """Exact C2 Hermite quintics with locally limited slopes and curvatures.
+
+    On an interval of width h and secant m, the quartic derivative's Bernstein
+    coefficients are [d0, d0+h*a0/4, 5*m-2*(d0+d1)+h*(a1-a0)/4,
+    d1-h*a1/4, d1]. Limit curvatures first, then shrink each node's (d,a)
+    together so all five coefficients are nonnegative. Each shared node has
+    one value, slope, and curvature: the assembled CDF is C2 and PDF is C1.
+    The support endpoints have zero slope/curvature, allowing constant CDF
+    extension and zero PDF extension without a boundary derivative jump.
+    """
+    x, y = np.asarray(x, dtype=float), np.asarray(y, dtype=float)
+    if x.ndim != 1 or len(x) < 2 or y.shape != x.shape or not np.all(np.isfinite(x)) or not np.all(np.isfinite(y)):
+        raise ValueError("monotone_c2 needs matching finite 1D anchor arrays")
+    h, mass = np.diff(x), np.diff(y)
+    if np.any(h <= 0) or np.any(mass < 0):
+        raise ValueError("monotone_c2 requires strictly increasing x and nondecreasing CDF anchors")
+    # A clamped cubic estimates smooth slopes/curvatures in linear time. Its
+    # unconstrained interpolant is never returned: the quintic limiter below
+    # certifies monotonicity even where the cubic estimate would overshoot.
+    seed = CubicSpline(x, y, bc_type=((1, 0.0), (1, 0.0)))
+    slopes = np.maximum(seed(x, 1), 0.0)
+    slopes[[0, -1]] = 0.0
+    curvature = seed(x, 2)
+    # Adjacent interval constraints for the first/last PDF control coefficients.
+    lower, upper = np.full(len(x), -np.inf), np.full(len(x), np.inf)
+    lower[:-1] = -4 * slopes[:-1] / h
+    upper[1:] = 4 * slopes[1:] / h
+    curvature = np.clip(curvature, lower, upper)
+    curvature[[0, -1]] = 0.0
+    # Both contributions are nonnegative after clipping. Reducing either node
+    # cannot violate another interval's constraint, so one local pass suffices.
+    left = 2 * slopes[:-1] + h * curvature[:-1] / 4
+    right = 2 * slopes[1:] - h * curvature[1:] / 4
+    available = 5 * mass / h
+    total = left + right
+    factors = np.ones(len(h))
+    active = total > available
+    factors[active] = (available[active] / total[active]) * (1 - 32 * np.finfo(float).eps)
+    node_factors = np.ones(len(x))
+    node_factors[:-1] = np.minimum(node_factors[:-1], factors)
+    node_factors[1:] = np.minimum(node_factors[1:], factors)
+    slopes *= node_factors
+    curvature *= node_factors
+    if not np.all(np.isfinite(slopes)) or not np.all(np.isfinite(curvature)):
+        raise ValueError("monotone_c2 cannot resolve this anchor spacing; inspect support and score precision")
+    return BPoly.from_derivatives(x, np.column_stack((y, slopes, curvature)), extrapolate=False)
+
+
+def interpolate_cdf(x: np.ndarray, y: np.ndarray, method: str):
+    if method == "monotone_c2":
+        return monotone_c2(x, y)
+    if method == "pchip":
+        return PchipInterpolator(x, y, extrapolate=False)
+    raise ValueError(f"unknown CDF interpolation {method!r}")
+
+
+@dataclass(frozen=True)
+class AnchorFit:
+    curve: BPoly | PchipInterpolator
+    indices: np.ndarray
+    max_error: float
+    stop_reason: str
+
+
+def fit_anchors(x: np.ndarray, y: np.ndarray, config: AnchorSettings, interpolation: str) -> AnchorFit:
+    """Select only real empirical nodes plus the supplied support endpoints.
+
+    A bounded set of probability seeds starts the fit. Each pass evaluates
+    residuals against all empirical knots once, then scans disjoint intervals
+    and refines up to eight worst intervals. min_mass is the required observed
+    cumulative mass on EACH side of a proposed new node; it stops the selector
+    from chasing individual sample jumps. No output grid participates.
+    """
+    if config.method == "all":
+        curve = interpolate_cdf(x, y, interpolation)
+        return AnchorFit(curve, np.arange(len(x)), 0.0, "all")
+    # Retain the first empirical value and the first empirical value reaching
+    # probability one, so the fit preserves the observed onset and upper tail.
+    last = min(int(np.searchsorted(y, 1.0)), len(x) - 1)
+    selected = {0, min(1, len(x) - 1), last, len(x) - 1}
+    seed_count = min(9, config.max_points - len(selected) + 1)
+    for target in np.linspace(0, 1, seed_count)[1:-1]:
+        index = min(int(np.searchsorted(y, target)), len(x) - 1)
+        ordered = sorted(selected)
+        slot = int(np.searchsorted(ordered, index))
+        if index in selected or slot == 0 or slot == len(ordered):
+            continue
+        if min(y[index] - y[ordered[slot - 1]], y[ordered[slot]] - y[index]) >= config.min_mass:
+            selected.add(index)
+    while True:
+        indices = np.array(sorted(selected), dtype=int)
+        curve = interpolate_cdf(x[indices], y[indices], interpolation)
+        residual = np.abs(curve(x) - y)
+        error = float(np.max(residual))
+        if error <= config.tolerance:
+            return AnchorFit(curve, indices, error, "tolerance")
+        if len(selected) >= config.max_points:
+            return AnchorFit(curve, indices, error, "max_points")
+        queue = []
+        for lo, hi in zip(indices[:-1], indices[1:]):
+            # Search only nodes with enough probability mass on both sides.
+            start = max(lo + 1, int(np.searchsorted(y, y[lo] + config.min_mass, side="left")))
+            end = min(hi, int(np.searchsorted(y, y[hi] - config.min_mass, side="right")))
+            if start >= end:
+                continue
+            index = start + int(np.argmax(residual[start:end]))
+            if residual[index] > config.tolerance:
+                heappush(queue, (-float(residual[index]), index))
+        if not queue:
+            return AnchorFit(curve, indices, error, "min_mass")
+        for _ in range(min(8, config.max_points - len(selected), len(queue))):
+            _, index = heappop(queue)
+            selected.add(index)

{jarvisplot-2.1.5 → jarvisplot-2.1.7}/jarvisplot/Figure/config_runtime.py

@@ -13,6 +13,8 @@ def apply_figure_config(fig, info: Mapping) -> bool:
     fig._setup_error = None
 
     try:
+        if "legend" in info:
+            raise ValueError("Figure-level legend is not supported; declare items on layers and overall layout under frame.<axes>.legend")
         if "name" in info:
             fig.name = info["name"]
 

jarvisplot-2.1.7/jarvisplot/Figure/distribution_1d_runtime.py

@@ -0,0 +1,165 @@
+"""Raw weighted samples -> continuous CDF, optionally its analytic derivative.
+
+PDF1D and CDF1D share the reconstruction. No histogram or sample-grid
+renormalisation participates in fitting: the grid only evaluates the interpolant.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+import numpy as np
+import pandas as pd
+from scipy.interpolate import PchipInterpolator
+
+from ..distribution_1d_config import KINDS, settings
+from ..memtrace import memtrace_checkpoint, memtrace_object_inventory
+from ..utils.expression import eval_dataframe_expression
+from .adaptive_cdf_runtime import fit_anchors
+
+ALGORITHM_REVISION = "weighted-ecdf-adaptive-bernstein-c2-v3"
+
+
+def _values(df: pd.DataFrame, expr: Any, logger=None) -> np.ndarray:
+    values = np.asarray(eval_dataframe_expression(df, expr, logger=logger), dtype=float)
+    if values.ndim == 0:
+        return np.full(len(df), float(values))
+    if values.shape != (len(df),):
+        raise ValueError(f"expression {expr!r} must return one value per input row, got {values.shape}")
+    return values
+
+
+def _infer_limits(x: np.ndarray, scale: str) -> tuple[float, float]:
+    unique = np.unique(x)
+    if len(unique) < 2:
+        raise ValueError("one unique sample cannot define a continuous support; set coordinates.x.lim")
+    lo = unique[0] - 0.5 * (unique[1] - unique[0])
+    hi = unique[-1] + 0.5 * (unique[-1] - unique[-2])
+    if scale == "log":
+        if unique[0] <= 0:
+            raise ValueError("coordinates.x.scale: log requires positive samples")
+        lo = max(lo, unique[0] * 0.5)
+    if not np.isfinite(lo) or not np.isfinite(hi) or not lo < hi:
+        raise ValueError("cannot infer finite support; set coordinates.x.lim")
+    return float(lo), float(hi)
+
+
+def empirical_knots(x: np.ndarray, weights: np.ndarray, limits: tuple[float, float]):
+    """Inclusive empirical nodes plus support endpoints; return largest atom too."""
+    lo, hi = limits
+    order = np.argsort(x, kind="stable")
+    x, weights = x[order], weights[order]
+    unique, first = np.unique(x, return_index=True)
+    # Rescaling before summation avoids overflow without changing probability.
+    scaled = weights / weights.max()
+    mass = np.add.reduceat(scaled, first)
+    mass /= mass.sum()
+    cumulative = np.minimum(np.cumsum(mass), 1.0)
+    cumulative[-1] = 1.0
+    interior = (unique > lo) & (unique < hi)
+    knots = np.r_[lo, unique[interior], hi]
+    probabilities = np.r_[0.0, cumulative[interior], 1.0]
+    return knots, probabilities, float(mass.max())
+
+
+def build_cdf(x: np.ndarray, weights: np.ndarray, limits: tuple[float, float]) -> PchipInterpolator:
+    """Original all-anchor PCHIP path, useful for exact empirical-node comparisons.
+
+    A sample exactly at lo cannot retain its jump with F(lo)=0; its mass is
+    carried into the first interval. Other empirical nodes retain their CDF.
+    Production reconstruction uses fit_anchors with the selected settings.
+    """
+    knots, probabilities, _ = empirical_knots(x, weights, limits)
+    return PchipInterpolator(knots, probabilities, extrapolate=False)
+
+
+def distribution_1d(df: pd.DataFrame, cfg: Mapping[str, Any], kind: str, logger=None) -> pd.DataFrame:
+    if kind not in KINDS:
+        raise ValueError(f"unknown distribution transform {kind!r}")
+    if not isinstance(df, pd.DataFrame) or df.empty:
+        raise ValueError(f"{kind} needs a nonempty pandas sample table")
+    opts = settings(cfg)
+    memtrace_checkpoint(logger, f"pipeline.{kind}.before", df)
+    x = _values(df, opts.x["expr"], logger)
+    weights = _values(df, opts.weight["expr"], logger) if opts.weight else np.ones(len(df))
+    if not np.all(np.isfinite(x)) or not np.all(np.isfinite(weights)):
+        raise ValueError(f"{kind} needs finite samples and weights; filter invalid rows first")
+    if np.any(weights < 0):
+        raise ValueError(f"{kind} needs nonnegative probability weights; signed event weights are not a CDF")
+    work = pd.DataFrame({"x": x, "weight": weights})
+    if opts.repeat is not None:
+        if opts.repeat not in df.columns:
+            raise KeyError(f"{kind} missing repeat column {opts.repeat!r}")
+        if df[opts.repeat].isna().any():
+            raise ValueError(f"{kind} repeat identifiers must not be missing")
+        work["repeat"] = df[opts.repeat].to_numpy()
+    positive = weights > 0
+    if not positive.any():
+        raise ValueError(f"{kind} weights sum to zero")
+    limits = opts.limits or _infer_limits(x[positive], opts.scale)
+    lo, hi = limits
+    if np.any((x[positive] < lo) | (x[positive] > hi)):
+        raise ValueError(f"{kind} coordinates.x.lim must contain all positive-weight samples; filter first to truncate")
+    grid = np.geomspace(lo, hi, opts.grid) if opts.scale == "log" else np.linspace(lo, hi, opts.grid)
+    memtrace_object_inventory(logger, f"pipeline.{kind}.samples", {"samples": work})
+    curves = ("cdf", "pdf") if kind == "PDF1D" else ("cdf",)
+    mean = {key: np.zeros(opts.grid) for key in curves}
+    m2 = {key: np.zeros(opts.grid) for key in curves}
+    groups = work.groupby("repeat", sort=False, observed=True) if opts.repeat else [(None, work)]
+    n = 0
+    boundary_mass = False
+    diagnostics = []
+    for label, block in groups:
+        block = block.loc[block.weight > 0]
+        if block.empty:
+            raise ValueError(f"{kind} repeat {label!r} weights sum to zero")
+        bx, bw = block.x.to_numpy(), block.weight.to_numpy()
+        boundary_mass |= bool(np.any(bx == lo))
+        knots, probabilities, largest_jump = empirical_knots(bx, bw, limits)
+        fit = fit_anchors(knots, probabilities, opts.anchors, opts.interpolation)
+        cdf = fit.curve
+        diagnostics.append({
+            "repeat": label.item() if isinstance(label, np.generic) else label,
+            "n_anchors": len(fit.indices), "n_candidates": len(knots),
+            "max_cdf_error": fit.max_error, "stop_reason": fit.stop_reason,
+            "largest_empirical_jump": largest_jump,
+        })
+        if logger is not None:
+            logger.debug(f"{kind} repeat={label!r}: anchors={len(fit.indices)}/{len(knots)}, "
+                         f"max CDF node error={fit.max_error:.6g}, stopped={fit.stop_reason}")
+            if opts.anchors.method == "adaptive" and fit.max_error > opts.anchors.tolerance:
+                logger.warning(f"{kind} repeat={label!r}: CDF error {fit.max_error:.6g} exceeds "
+                               f"tolerance {opts.anchors.tolerance:g}; stopped at {fit.stop_reason}. "
+                               "Adjust anchors settings if finer CDF reconstruction is needed.")
+            if opts.anchors.method == "adaptive" and largest_jump > max(2 * opts.anchors.tolerance, opts.anchors.min_mass):
+                logger.warning(f"{kind} repeat={label!r}: empirical probability jump {largest_jump:.6g}; "
+                               "a continuous density spreads this discrete mass over an interval")
+        values = {"cdf": cdf(grid)}
+        if kind == "PDF1D":
+            pdf = cdf.derivative()(grid)
+            tolerance = 128 * np.finfo(float).eps * max(1.0, float(np.max(np.abs(pdf))))
+            if np.min(pdf) < -tolerance:
+                raise ValueError(f"{kind} produced a negative density beyond floating-point tolerance")
+            values["pdf"] = np.maximum(pdf, 0.0)
+        n += 1
+        for key in curves:
+            if not np.all(np.isfinite(values[key])):
+                raise ValueError(f"{kind} produced nonfinite {key}; inspect sample spacing/support")
+            delta = values[key] - mean[key]
+            mean[key] += delta / n
+            m2[key] += delta * (values[key] - mean[key])
+    out = {opts.name: grid}
+    for key in curves:
+        out[key] = mean[key]
+        out[f"{key}_std"] = np.sqrt(np.maximum(m2[key], 0.0) / (n - 1)) if n > 1 else np.full(opts.grid, np.nan)
+    out["n_repeats"] = n
+    table = pd.DataFrame(out)
+    table.attrs["distribution_1d"] = {
+        "algorithm": ALGORITHM_REVISION, "interpolation": opts.interpolation,
+        "anchor_method": opts.anchors.method, "support": limits, "repeats": diagnostics,
+    }
+    if logger is not None:
+        if boundary_mass:
+            logger.warning(f"{kind}: mass at the lower support boundary is spread over the first CDF interval")
+        logger.debug(f"{kind}: {len(df)} samples -> {opts.grid} points, {n} repeats, support={limits}, std ddof=1")
+    memtrace_checkpoint(logger, f"pipeline.{kind}.after", table)
+    return table

{jarvisplot-2.1.5 → jarvisplot-2.1.7}/jarvisplot/Figure/figure.py

@@ -14,6 +14,8 @@ from .method_registry import resolve_callable
 from .style_runtime import resolve_style_bundle_payload
 from .config_runtime import apply_figure_config
 from .design_runtime import draw_design_reference
+from .legend_runtime import apply_legend
+from ..legend_cards import merge_axes_legend, effective_axes_legend
 from .layer_runtime import (
     load_layer_runtime_data as runtime_load_layer_runtime_data,
     release_layer_runtime_data as runtime_release_layer_runtime_data,
@@ -356,15 +358,35 @@ class Figure:
     
     @frame.setter
     def frame(self, value) -> None: 
+        self._legend_disabled_axes = getattr(self, "_legend_disabled_axes", set())
+        for name, node in (value or {}).items():
+            if isinstance(node, dict) and "legend" in node:
+                declared = node["legend"]
+                if declared is False or (isinstance(declared, dict) and declared.get("enabled") is False):
+                    self._legend_disabled_axes.add(name)
+                else:
+                    self._legend_disabled_axes.discard(name)
         if self._frame is None:
             self._frame = value
         else:
+            # Legend order/roles are replacement lists, not deepmerge's
+            # default append lists. Explicit YAML also enables a disabled card
+            # default, unless enabled:false was supplied by the user.
+            value = deepcopy(value)
+            legends = {}
+            for name, node in (value or {}).items():
+                if isinstance(node, dict) and "legend" in node:
+                    legends[name] = merge_axes_legend(
+                        self._frame.get(name, {}).get("legend", False), node.pop("legend")
+                    )
             for _name, _node in (value or {}).items():
                 _color = _node.get("color") if isinstance(_node, dict) else None
                 if isinstance(_color, dict) and "cmap" in _color:
                     self._yaml_axc_cmaps.add(str(_name))
             from deepmerge import always_merger
             self._frame = always_merger.merge(self._frame, value)
+            for name, legend in legends.items():
+                self._frame.setdefault(name, {})["legend"] = legend
 
     @property
     def yaml_colorbar_cmaps(self) -> set:
@@ -383,6 +405,7 @@ class Figure:
             raise TypeError
         family, selected, bundle = resolve_style_bundle_payload(self.jpstyles, value)
         self._frame = deepcopy(bundle["Frame"])
+        self._legend_disabled_axes = set()
         self._yaml_axc_cmaps = set()
         self._style = deepcopy(bundle["Style"])
         self._debug_config = deepcopy(bundle.get("Debug", {}))
@@ -616,7 +639,6 @@ class Figure:
                 clip_path=Path(vertices, codes)  # 用 path 做 clip，transform 使用 ax.transData 已在适配器里处理
             )
             adapter._type = 'tri'
-            adapter._legend = False
             adapter.layers = []
             adapter.status = 'configured'
             self.axes["axtri"] = adapter
@@ -1075,7 +1097,6 @@ class Figure:
             adapter = StdAxesAdapter(raw_ax)
             adapter._type = "rect"
             adapter.layers = []
-            adapter._legend = self.frame['ax'].get("legend", False)
             self.axes['ax'] = adapter 
             adapter.status = 'configured'
         
@@ -1185,19 +1206,13 @@ class Figure:
         self.logger.debug("Loaded main rectangle axes -> ax")
 
     def _apply_legend_on_axes(self, ax_name: str, ax_obj, leg_cfg: dict):
-        """Apply a legend on a specific axes using a YAML dict stored under frame['axes'][ax_name]['legend'].
-        Supports an optional 'enabled' key (default True). Any 'axes' key will be ignored here."""
-        if not isinstance(leg_cfg, dict):
-            return
-        if leg_cfg.get("enabled", True) is False:
-            return
-        kw = dict(leg_cfg)
-        kw.pop("axes", None)  # per-axes legend doesn't need this
-        try:
-            (ax_obj.ax if hasattr(ax_obj, "ax") else ax_obj).legend(**kw)
-        except Exception as e:
-            if self.logger:
-                self.logger.warning(f"Legend apply failed on '{ax_name}': {e}")
+        """Apply frame.<axes>.legend after all real layer handles are available."""
+        target_ax = ax_obj.ax if hasattr(ax_obj, "ax") else ax_obj
+        layer_specs = getattr(self, "_legend_layers", {}).get(ax_name, [])
+        return apply_legend(
+            target_ax, leg_cfg, getattr(self, "_legend_layer_handles", {}).get(ax_name, {}),
+            base_dir=self._yaml_dir, layer_specs=layer_specs,
+        )
 
 
     def _install_tri_auto_clip(self, ax):
@@ -1326,10 +1341,17 @@ class Figure:
         # determined by frame config + data — never by render order.
         self._prescan_colorbar_ranges()
 
+        self._legend_layer_handles = {}
+        self._legend_layers = {}
+        axes_names = {id(ax): name for name, ax in self.axes.items()}
         for ax, ly in self._render_queue:
             runtime_load_layer_runtime_data(self, ly)
             try:
-                runtime_render_layer(self, ax, ly)
+                rendered = runtime_render_layer(self, ax, ly)
+                name = axes_names[id(ax)]
+                specs = self._legend_layers.setdefault(name, [])
+                self._legend_layer_handles.setdefault(name, {})[f"@layer:{len(specs)}"] = rendered
+                specs.append(ly.get("layer_spec", {}))
             finally:
                 runtime_release_layer_runtime_data(self, ly)
 
@@ -1340,12 +1362,14 @@ class Figure:
 
         for name, ax in self.axes.items():
             try:
-                if hasattr(ax, "_legend") and ax._legend:
-                    target_ax = ax.ax if hasattr(ax, "ax") else ax
-                    target_ax.legend(**ax._legend)
+                legend_config = self.frame.get(name, {}).get("legend", False)
+                legend_config = effective_axes_legend(
+                    legend_config, self._legend_layers.get(name, []),
+                    explicitly_disabled=name in getattr(self, "_legend_disabled_axes", set()),
+                )
+                self._apply_legend_on_axes(name, ax, legend_config)
             except Exception as e:
-                if self.logger:
-                    self.logger.warning(f"Legend draw failed on axes '{name}': {e}")
+                raise ValueError(f"Legend draw failed on axes '{name}': {e}") from e
 
         # Finalize all colorbar axes (axc and any named axc*)
         for name in list(self.axes.keys()):