jarvisplot 2.0.5__tar.gz → 2.0.6__tar.gz

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/JarvisPLOT.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: JarvisPLOT
-Version: 2.0.5
+Version: 2.0.6
 Summary: Jarvis-PLOT: YAML-driven plotting engine
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/JarvisPLOT.egg-info/SOURCES.txt

@@ -137,6 +137,7 @@ jarvisplot/schema/methods/fill.json
 jarvisplot/schema/methods/fill_between.json
 jarvisplot/schema/methods/fill_betweenx.json
 jarvisplot/schema/methods/hist.json
+jarvisplot/schema/methods/hist2d.json
 jarvisplot/schema/methods/imshow.json
 jarvisplot/schema/methods/jpcontour.json
 jarvisplot/schema/methods/jpcontourf.json

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: JarvisPLOT
-Version: 2.0.5
+Version: 2.0.6
 Summary: Jarvis-PLOT: YAML-driven plotting engine
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/jarvisplot/Figure/colorbar_runtime.py

@@ -56,6 +56,20 @@ def axc_color_config(frame: Mapping[str, Any], cb_name: str = "axc") -> dict:
     return out
 
 
+def layer_cmap_wins(fig, cb_name: str, color_cfg: Mapping[str, Any]) -> bool:
+    """Whether a layer's own ``cmap`` may override ``frame[cb_name].color.cmap``.
+
+    A cmap that reached the frame from the **style card** is a preset: the
+    card says what this colorbar normally looks like, and a layer naming its
+    own is the more specific statement, so the layer wins.  A cmap written in
+    the **project YAML** is the author talking about this one figure, so it
+    wins instead.  Same defaults < card < YAML order the Debug block uses.
+    """
+    if color_cfg.get("cmap") is None:
+        return True
+    return str(cb_name) not in (getattr(fig, "yaml_colorbar_cmaps", None) or set())
+
+
 # ---------------------------------------------------------------------------
 # Scalar helpers
 # ---------------------------------------------------------------------------
@@ -151,6 +165,55 @@ _CONTOUR_LIKE_METHODS = frozenset({
     "jpcontour", "jpcontourf",
 })
 
+#: Methods that bin their own data: the colour channel is the bin content, so
+#: there is no ``z`` column for the pre-scan to read.  It has to run the same
+#: binning matplotlib will run.
+_BINNED_COLOR_METHODS = frozenset({"hist2d"})
+
+
+def _hist2d_bin_values(df, coor: dict, style: dict):
+    """Reproduce the bin contents ``Axes.hist2d`` will colour.
+
+    ``Axes.hist2d`` is ``np.histogram2d`` followed by ``pcolormesh``, so the
+    same call with the same ``bins`` / ``range`` / ``density`` / ``weights``
+    gives the pre-scan the colour range without drawing anything.
+    """
+    if df is None:
+        return None
+
+    def _channel(key):
+        src = coor.get(key)
+        if isinstance(src, dict) and "expr" in src:
+            return eval_dataframe_expression(df, src["expr"], logger=None)
+        if src is None:
+            src = style.get(key)
+        if src is None or isinstance(src, str):
+            return None
+        return np.asarray(src, dtype=float)
+
+    x = _channel("x")
+    y = _channel("y")
+    if x is None or y is None:
+        return None
+
+    values, _, _ = np.histogram2d(
+        np.asarray(x, dtype=float),
+        np.asarray(y, dtype=float),
+        bins=style.get("bins", 10),
+        range=style.get("range"),
+        density=bool(style.get("density", False)),
+        weights=_channel("weights"),
+    )
+    # `cmin` / `cmax` blank a bin out entirely; a blanked bin must not drag the
+    # colorbar range with it.
+    cmin = style.get("cmin")
+    cmax = style.get("cmax")
+    if cmin is not None:
+        values = values[values >= float(cmin)]
+    if cmax is not None:
+        values = values[values <= float(cmax)]
+    return values
+
 
 def layer_uses_color(style: dict, coor: dict, method_key: str) -> bool:
     """Return True if this layer will need a colorbar."""
@@ -169,16 +232,30 @@ def layer_uses_color(style: dict, coor: dict, method_key: str) -> bool:
     if method_key in _COLORED_Z_METHODS and _is_numeric_color_source(style_z):
         return True
 
+    # A self-binning method always has a colour channel -- its own bin contents.
+    if method_key in _BINNED_COLOR_METHODS:
+        return True
+
     return False
 
 
-def collect_layer_color_range(df, coor: dict, style: dict, *, scale: str | None = None):
+def collect_layer_color_range(
+    df, coor: dict, style: dict, *, scale: str | None = None, method_key: str | None = None
+):
     """Extract (data_min, data_max) for the colour channel of a single layer.
 
     Returns (None, None) when no finite data is available.
     """
     arr = None
-    if isinstance(coor.get("z"), dict) and "expr" in coor["z"]:
+    if str(method_key or "").strip().lower() in _BINNED_COLOR_METHODS:
+        try:
+            arr = _hist2d_bin_values(df, coor, style)
+        except Exception:
+            # A malformed bins/range only stops the colorbar from being
+            # pre-sized.  Let the real draw call raise it, where the error
+            # names the layer instead of surfacing out of the pre-scan.
+            arr = None
+    elif isinstance(coor.get("z"), dict) and "expr" in coor["z"]:
         arr = eval_dataframe_expression(df, coor["z"]["expr"], logger=None)
     elif isinstance(coor.get("c"), dict) and "expr" in coor["c"]:
         arr = eval_dataframe_expression(df, coor["c"]["expr"], logger=None)
@@ -394,13 +471,14 @@ def collect_and_attach_colorbar(
     if not axc._cb.get("used"):
         frame = getattr(fig, "frame", {})
         color_cfg = axc_color_config(frame, cb_name)
-        if color_cfg.get("cmap") is None and style.get("cmap") is not None:
+        if style.get("cmap") is not None and layer_cmap_wins(fig, cb_name, color_cfg):
             color_cfg["cmap"] = style.get("cmap")
         data_range = collect_layer_color_range(
             df,
             coor,
             style,
             scale=color_cfg.get("scale"),
+            method_key=method_key,
         )
         if data_range != (None, None):
             axc._cb.update(

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/jarvisplot/Figure/debug_config.py

@@ -238,6 +238,21 @@ DEFAULT_DEBUG = {
         "bottom": {"show": True},
     },
     "colorbar_gap": {"show": True, "template": "%.3f cm"},
+    # A layout reference has no layers, so nothing feeds the colorbar and it
+    # stays an empty box -- the one part of the page the reference cannot
+    # show.  Fill it with the card's own colormap.  A colorbar a layer did
+    # feed is a real result and is left alone.
+    "colorbar_preview": {
+        "show": True,
+        "samples": 256,
+        "fallback_cmap": "viridis",
+        "imshow": {
+            "aspect": "auto",
+            "interpolation": "bilinear",
+            "origin": "lower",
+            "zorder": 1,
+        },
+    },
     # The layout panel. One type scale for every figure: the box is sized to
     # its content and may run past the axes, rather than shrinking its text to
     # fit a short axes and printing the same numbers at a different size on

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/jarvisplot/Figure/design_runtime.py

@@ -36,6 +36,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 
 import matplotlib as mpl
+import numpy as np
 
 
 from .debug_config import resolve_debug_config as _debug_config
@@ -110,6 +111,51 @@ def _position(ax):
         return None
 
 
+def _preview_colorbar(fig, name, cfg):
+    """Paint an empty colorbar axes with the colormap its card would use.
+
+    ``Figure._finalize_axc`` returns early when no layer fed the bar, which is
+    always the case for a pure layout reference (``layers: []``).  The result
+    is a blank box exactly where the reader wants to judge the bar's width and
+    height, so fill it here.  A bar a layer really did feed keeps its result:
+    this only ever touches ``_cb['used'] is False``.
+    """
+    axc = fig.axes.get(name)
+    if axc is None:
+        return
+    if dict(getattr(axc, "_cb", None) or {}).get("used"):
+        return
+
+    from .colorbar_runtime import axc_color_config, axc_is_horizontal
+
+    cmap = axc_color_config(fig.frame, name).get("cmap") or cfg["fallback_cmap"]
+    is_h = axc_is_horizontal(fig.frame, name)
+    ramp = np.linspace(0.0, 1.0, int(cfg["samples"])).reshape(-1, 1)
+    if is_h:
+        ramp = ramp.reshape(1, -1)
+
+    raw = _raw(axc)
+    raw.imshow(
+        ramp,
+        cmap=cmap,
+        extent=(*raw.get_xlim(), *raw.get_ylim()),
+        **cfg["imshow"],
+    )
+
+    # ``_finalize_axc`` returns on ``_cb['used'] is False`` -- before it reaches
+    # ``minorticks_on`` and ``_apply_axc_tick_config``.  So an unfed colorbar
+    # keeps matplotlib's default ticks: both sides, pointing out, full-size
+    # labels, no minor locator.  The reference is meant to show the tick
+    # treatment the card asks for, so run the same two steps here.
+    from matplotlib.ticker import AutoMinorLocator
+
+    axis = raw.xaxis if is_h else raw.yaxis
+    axis.set_minor_locator(AutoMinorLocator())
+    apply = getattr(fig, "_apply_axc_tick_config", None)
+    if callable(apply):
+        apply(name, axc)
+
+
 def _axis_info_lines(name, pos, w_cm, h_cm, *, detail_cfg, fig=None):
     """Return the three-line layout entry used in the information panel."""
     l, b, w, h = pos
@@ -381,6 +427,9 @@ def _draw(fig) -> None:
                     vertical_label_side=margin_side,
                 )
 
+        if name.startswith("axc") and _shown(debug["colorbar_preview"]):
+            _preview_colorbar(fig, name, debug["colorbar_preview"])
+
         if name.startswith("axc") and primary_pos is not None:
             # gap between the primary axes' right edge and this colorbar's left edge
             pl, pb, pw, ph = primary_pos

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/jarvisplot/Figure/figure.py

@@ -23,6 +23,7 @@ from .layout_runtime import (
     apply_axis_endpoints,
     apply_auto_ticks,
     apply_axis_title,
+    apply_grid,
     apply_manual_ticks,
     SIDE_AXES,
     ensure_rect_axes,
@@ -33,6 +34,7 @@ from .layout_runtime import (
 )
 from .colorbar_runtime import (
     axc_color_config,
+    layer_cmap_wins,
     axc_is_horizontal,
     collect_layer_color_range,
     layer_uses_color,
@@ -246,6 +248,10 @@ class Figure:
         # self._jpdatas:  Optional[list]  =   []
         self._logger    = None
         self._frame     = {}
+        # Colorbar axes whose cmap the project YAML names outright.  A cmap
+        # that only came from the style card is a preset the layer may
+        # override; one written here is not.
+        self._yaml_axc_cmaps: set = set()
         self._outinfo   = {}
         self._output_metadata = {}
         self._yaml_dir  = None  # directory of the active YAML file (used to resolve relative paths)
@@ -348,8 +354,17 @@ class Figure:
         if self._frame is None:
             self._frame = value
         else:
+            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)
+
+    @property
+    def yaml_colorbar_cmaps(self) -> set:
+        """Colorbar axes whose cmap came from the YAML rather than the card."""
+        return self._yaml_axc_cmaps
             
     @property
     def style(self) -> Optional[dict]: 
@@ -363,6 +378,7 @@ class Figure:
             raise TypeError
         family, selected, bundle = resolve_style_bundle_payload(self.jpstyles, value)
         self._frame = deepcopy(bundle["Frame"])
+        self._yaml_axc_cmaps = set()
         self._style = deepcopy(bundle["Style"])
         self._debug_config = deepcopy(bundle.get("Debug", {}))
         self._default_layers = deepcopy(bundle.get("Layers", []))
@@ -883,7 +899,9 @@ class Figure:
             if not layer_uses_color(style, coor, method_key):
                 continue
 
-            if style.get("cmap") is not None:
+            if style.get("cmap") is not None and layer_cmap_wins(
+                self, cb_name, axc_color_config(self.frame, cb_name)
+            ):
                 cb_style_cmaps.setdefault(cb_name, style.get("cmap"))
 
             # Load data for color range only — do not append health observations
@@ -893,7 +911,9 @@ class Figure:
             if df is not None:
                 df = self._ensure_pandas_data(df, reason="prescan:colorbar")
                 color_cfg = axc_color_config(self.frame, cb_name)
-                lo, hi = collect_layer_color_range(df, coor, style, scale=color_cfg.get("scale"))
+                lo, hi = collect_layer_color_range(
+                    df, coor, style, scale=color_cfg.get("scale"), method_key=method_key
+                )
                 if lo is not None or hi is not None:
                     cb_ranges.setdefault(cb_name, []).append((lo, hi))
             # Release immediately to preserve memory profile
@@ -905,7 +925,7 @@ class Figure:
             if axc_obj is None or not hasattr(axc_obj, "_cb"):
                 continue
             color_cfg = axc_color_config(self.frame, cb_name)
-            if color_cfg.get("cmap") is None and cb_name in cb_style_cmaps:
+            if cb_name in cb_style_cmaps and layer_cmap_wins(self, cb_name, color_cfg):
                 color_cfg["cmap"] = cb_style_cmaps[cb_name]
             axc_obj._cb.update(
                 precompute_colorbar_cb(color_cfg, ranges, logger=self.logger)
@@ -1004,6 +1024,8 @@ class Figure:
         self.ax.tick_params(**self.frame['ax']['ticks'].get("major", {}))
         self.ax.tick_params(**self.frame['ax']['ticks'].get("minor", {}))
         
+        apply_grid(self, self.axes['ax'], 'ax')
+
         self._apply_axis_endpoints(self.axes['ax'], self.frame['ax'].get('xaxis', {}), "x")
         self._apply_axis_endpoints(self.axes['ax'], self.frame['ax'].get('yaxis', {}), "y")
 

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/jarvisplot/Figure/layout_runtime.py

@@ -85,6 +85,42 @@ def hide_log_minor_tick_labels(ax_obj, which: str) -> None:
         )
 
 
+def apply_grid(fig, ax_obj, ax_name: str) -> None:
+    """Draw the configured major / minor grid on a rectangular axes.
+
+    Shaped like ``ticks``: one block per matplotlib call, splatted verbatim
+    into ``Axes.grid``.  Ternary cards keep their own hand-drawn grid under
+    ``grid.sep`` / ``grid.style``, so only the two call blocks are read here
+    and every other key in the node is left alone -- which is also why the
+    dead ``grid`` blocks the rect cards inherited stay dead.
+
+    ``axisbelow`` is a sibling key rather than a ``grid`` kwarg because it is
+    the only thing that decides whether the grid lands over or under the data:
+    a ``zorder`` passed to ``Axes.grid`` sets the gridline's own zorder, but
+    the Axis artist is drawn as a unit at the zorder ``set_axisbelow`` gives
+    it, so the kwarg alone never lifts a grid above a filled layer.
+    """
+    grid_cfg = fig.frame.get(ax_name, {}).get("grid", {})
+    if not isinstance(grid_cfg, dict):
+        return
+    target = ax_obj.ax if hasattr(ax_obj, "ax") else ax_obj
+
+    if "axisbelow" in grid_cfg:
+        target.set_axisbelow(grid_cfg["axisbelow"])
+
+    for which in ("major", "minor"):
+        block = grid_cfg.get(which)
+        if not isinstance(block, dict) or not block:
+            continue
+        try:
+            target.grid(**block)
+        except Exception as exc:
+            if getattr(fig, "logger", None):
+                fig.logger.warning(
+                    f"grid.{which} on axes '{ax_name}' ignored: {exc}"
+                )
+
+
 def ensure_rect_axes(fig, ax_name: str, kwgs: dict):
     if not is_rect_ax(ax_name):
         allowed = ", ".join(repr(n) for n in SIDE_AXES)
@@ -159,9 +195,18 @@ def ensure_rect_axes(fig, ax_name: str, kwgs: dict):
         if isinstance(ylabel_coords, dict) and {"x", "y"} <= set(ylabel_coords):
             ax_obj.yaxis.set_label_coords(ylabel_coords["x"], ylabel_coords["y"])
 
-    ax_obj.tick_params(**fig.frame.get(ax_name, {}).get("ticks", {}).get("both", {}))
-    ax_obj.tick_params(**fig.frame.get(ax_name, {}).get("ticks", {}).get("major", {}))
-    ax_obj.tick_params(**fig.frame.get(ax_name, {}).get("ticks", {}).get("minor", {}))
+    ticks_cfg = fig.frame.get(ax_name, {}).get("ticks", {})
+    ax_obj.tick_params(**ticks_cfg.get("both", {}))
+    ax_obj.tick_params(**ticks_cfg.get("major", {}))
+    ax_obj.tick_params(**ticks_cfg.get("minor", {}))
+
+    # `ticks.x/y.positions` was honoured on ax and on the colorbars but never
+    # here, so a side or numbered axes silently kept matplotlib's automatic
+    # locator -- even though has_manual_ticks already reads this same node.
+    apply_manual_ticks(fig, ax_obj, "x", ticks_cfg.get("x", {}) or {})
+    apply_manual_ticks(fig, ax_obj, "y", ticks_cfg.get("y", {}) or {})
+
+    apply_grid(fig, ax_obj, ax_name)
 
     apply_axis_endpoints(fig, ax_obj, fig.frame.get(ax_name, {}).get("xaxis", {}), "x")
     apply_axis_endpoints(fig, ax_obj, fig.frame.get(ax_name, {}).get("yaxis", {}), "y")

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/jarvisplot/Figure/method_registry.py

@@ -41,6 +41,7 @@ METHOD_DISPATCH: Dict[str, str] = {
     "plot":         "plot",
     "scatter":      "scatter",
     "hist":         "hist",
+    "hist2d":       "hist2d",
     "errorbar":     "errorbar",
     "fill":         "fill",
     "fill_between": "fill_between",

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/jarvisplot/cards/a4paper/2x1/rect5x1.json

@@ -101,6 +101,8 @@
                     "left": true,
                     "right": true,
                     "bottom": true,
+                    "labelbottom": false,
+                    "labeltop": false,
                     "which": "both"
                 },
                 "major": {
@@ -155,6 +157,8 @@
                     "left": true,
                     "right": true,
                     "bottom": true,
+                    "labelbottom": false,
+                    "labeltop": false,
                     "which": "both"
                 },
                 "major": {
@@ -209,6 +213,8 @@
                     "left": true,
                     "right": true,
                     "bottom": true,
+                    "labelbottom": false,
+                    "labeltop": false,
                     "which": "both"
                 },
                 "major": {
@@ -263,6 +269,8 @@
                     "left": true,
                     "right": true,
                     "bottom": true,
+                    "labelbottom": false,
+                    "labeltop": false,
                     "which": "both"
                 },
                 "major": {

{jarvisplot-2.0.5 → jarvisplot-2.0.6}/jarvisplot/cards/a4paper/2x1/rect_cmap.json

@@ -143,6 +143,9 @@
             ]
         },
         "axc": {
+            "color": {
+                "cmap": "jarvis_rainbow2"
+            },
             "label": {
                 "ylabel": "",
                 "loc": "center",
@@ -401,6 +404,17 @@
             "show": true,
             "template": "%.3f cm"
         },
+        "colorbar_preview": {
+            "show": true,
+            "samples": 256,
+            "fallback_cmap": "viridis",
+            "imshow": {
+                "aspect": "auto",
+                "interpolation": "bilinear",
+                "origin": "lower",
+                "zorder": 1
+            }
+        },
         "panel": {
             "show": true,
             "pad_x_max": 0.018,