jarvisplot 2.0.4__tar.gz → 2.0.6__tar.gz

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

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

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

@@ -53,6 +53,7 @@ jarvisplot/Figure/adapters_ternary.py
 jarvisplot/Figure/colorbar_runtime.py
 jarvisplot/Figure/config_runtime.py
 jarvisplot/Figure/data_pipelines.py
+jarvisplot/Figure/debug_config.py
 jarvisplot/Figure/density_cell_runtime.py
 jarvisplot/Figure/design_runtime.py
 jarvisplot/Figure/dynesty_runtime.py
@@ -80,6 +81,8 @@ jarvisplot/cards/a4paper/2x1/dynesty_runplot.json
 jarvisplot/cards/a4paper/2x1/rect.json
 jarvisplot/cards/a4paper/2x1/rect5x1.json
 jarvisplot/cards/a4paper/2x1/rect_cmap.json
+jarvisplot/cards/a4paper/2x1/rect_marginal.json
+jarvisplot/cards/a4paper/2x1/rectratio.json
 jarvisplot/cards/a4paper/2x1/ternary.json
 jarvisplot/cards/a4paper/2x1/ternary_cmap.json
 jarvisplot/cards/a4paper/4x1/rect.json
@@ -105,6 +108,7 @@ jarvisplot/cards/icons/flowchart/sampler.png
 jarvisplot/manual_cards/agent-output.yaml
 jarvisplot/manual_cards/cli-map.yaml
 jarvisplot/manual_cards/data-columns.yaml
+jarvisplot/manual_cards/debug-overlay.yaml
 jarvisplot/manual_cards/diagnostics.yaml
 jarvisplot/manual_cards/dryrun-viz.yaml
 jarvisplot/manual_cards/layer-method.yaml
@@ -133,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
@@ -171,6 +176,7 @@ tests/test_agent_digest.py
 tests/test_agent_envelope.py
 tests/test_axis_title.py
 tests/test_capabilities.py
+tests/test_card_debug_shape.py
 tests/test_cli_help.py
 tests/test_cli_verbs.py
 tests/test_cmaps.py
@@ -183,6 +189,9 @@ tests/test_data_describe.py
 tests/test_data_head_eval.py
 tests/test_data_loader_contracts.py
 tests/test_data_pipelines.py
+tests/test_debug_config.py
+tests/test_debug_switches.py
+tests/test_debug_yaml_override.py
 tests/test_density_cell_transform.py
 tests/test_design_runtime.py
 tests/test_diagnostic_guidance.py
@@ -209,5 +218,6 @@ tests/test_suggest.py
 tests/test_suggest_axes.py
 tests/test_template_catalog.py
 tests/test_template_json.py
+tests/test_ternary_debug.py
 tests/test_transform_contracts.py
 tests/test_validate_no_matplotlib.py

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

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

{jarvisplot-2.0.4 → 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.6/jarvisplot/Figure/debug_config.py

@@ -0,0 +1,466 @@
+#!/usr/bin/env python3
+
+"""Defaults and merge rules for the design-reference debug overlay.
+
+Split out of :mod:`design_runtime` so the configuration surface has one owner
+and can be tested without importing matplotlib. The drawing code reads only
+what this module hands it -- there are no literals below the unpack.
+
+**Every appearance value lives in a block named after the matplotlib callable
+that consumes it, and is splatted straight into that call:**
+
+.. code-block:: python
+
+    ov.plot(xs, ys, **cfg["cap"]["plot"])
+    ov.add_patch(mpl.patches.Rectangle((l, b), w, h, **cfg["outline"]["framed"]["Rectangle"]))
+
+So a block's keys are matplotlib's vocabulary, not Jarvis-PLOT's, and one
+drawn thing owns one complete kwargs table -- no shared palette to chase, no
+partial style merged with hidden Python defaults. What stays outside those
+blocks is geometry: positions, spans, thresholds and the autoscale constants
+that Python computes with before it draws.
+
+Precedence, lowest to highest:
+
+1. :data:`DEFAULT_DEBUG` -- ships with the package, always present.
+2. A style card's root ``Debug`` block (``jarvisplot/cards/**/*.json``).
+3. A YAML ``Figures[].debug`` mapping, for one figure only.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Mapping
+
+from ..diagnostics import did_you_mean
+
+__all__ = [
+    "CALL_BLOCKS",
+    "DEFAULT_DEBUG",
+    "deep_update",
+    "merge_debug_config",
+    "resolve_debug_config",
+]
+
+
+# Colours are written out in full inside every call block below; these names
+# exist only to keep that table readable and to make the roles obvious. They
+# are not a runtime indirection -- a card overrides the block, not a palette.
+_DIM = "#1F21E9"      # dimension lines, arrowheads and their labels
+_BOX = "#111111"      # outline of a framed axes
+_MARGIN = "#FF3FA4"   # figure border, caption, frameless-axes outline
+_NAME = "#1A237E"     # text inside the axes-layout panel
+_PANEL = "#FFEC73"    # the panel's own background
+_TERNARY = "#FF42A1"  # ternary tick anchors and label leaders
+
+# The overlay sits above every real artist; text above its own artists.
+_Z_OVERLAY, _Z_ARTIST, _Z_TEXT = 10000, 10001, 10002
+
+# Background box shared by the dimension labels and the caption. Written into
+# each ``text`` block in full; the alpha differs between them.
+_LABEL_BBOX = {"boxstyle": "square,pad=0.12", "fc": "white", "ec": "none"}
+
+# Typography shared by the dimension labels, likewise written out in full.
+_LABEL_FONT = {
+    "fontsize": 5.0,
+    "fontweight": "normal",
+    "family": "monospace",
+    "clip_on": False,
+    "zorder": _Z_TEXT,
+}
+
+
+DEFAULT_DEBUG = {
+    # Which axes gets fully dimensioned and hosts the info panel. First match wins.
+    "primary_order": ["ax", "ax0", "ax1", "axtri"],
+    "units": {"cm_per_inch": 2.54, "pt_per_inch": 72.0},
+    # The transparent full-figure axes every annotation is drawn onto.
+    "overlay": {"add_axes": {"zorder": _Z_OVERLAY}},
+    "figure": {
+        "border": {
+            "show": True,
+            "Rectangle": {"fill": False, "ec": _MARGIN, "lw": 0.9, "zorder": _Z_ARTIST},
+        },
+        "caption": {
+            "show": True,
+            "x": 0.5,
+            "y": 0.995,
+            "template": "design reference  ·  figure %.2f cm × %.2f cm",
+            "text": {
+                "color": _MARGIN,
+                "fontsize": 6.0,
+                "ha": "center",
+                "va": "top",
+                "rotation": 0,
+                "fontweight": "bold",
+                "family": "DejaVu Sans",
+                "clip_on": False,
+                "zorder": _Z_TEXT,
+                "bbox": {**_LABEL_BBOX, "alpha": 0.82},
+            },
+        },
+        # Drawn through the shared dimension machinery, so it has no call block
+        # of its own -- only where it sits and how its number reads.
+        "height_marker": {"show": True, "x": 0.035, "template": "%.2f cm"},
+    },
+    "axes": {
+        "frameless_extension_max": 0.018,
+        "frameless_extension_min": 0.006,
+        "frameless_extension_factor": 0.09,
+        "outline": {
+            "show": True,
+            # A framed axes keeps the neutral reference outline; a frameless
+            # one (axlogo, say) is marked as a design box instead.
+            "framed": {
+                "Rectangle": {"fill": False, "ec": _BOX, "lw": 0.45, "zorder": _Z_ARTIST},
+            },
+            "frameless": {
+                "Rectangle": {"fill": False, "ec": _MARGIN, "lw": 0.45, "zorder": _Z_ARTIST},
+            },
+        },
+        # Hash marks past the corners, drawn for frameless axes only.
+        "corner_ticks": {
+            "show": True,
+            "plot": {
+                "color": _MARGIN,
+                "lw": 0.45,
+                "solid_capstyle": "projecting",
+                "clip_on": False,
+                "zorder": _Z_ARTIST,
+            },
+        },
+    },
+    # One dimension line: two terminal cap bars, an arrow, and a label. Every
+    # measured distance in the overlay is drawn with these four calls.
+    "dimension": {
+        "cap_half_pt": 5.0,
+        "narrow_threshold_pt": 24.0,
+        "narrow_length_pt": 8.0,
+        "narrow_scale_factor": 0.45,
+        "narrow_scale_min": 3.0,
+        "narrow_scale_max": 6.0,
+        "label_gap": 0.008,
+        "corner_gap": 0.018,
+        "colorbar_line_offset": 0.024,
+        "cap": {
+            "plot": {
+                "color": _DIM,
+                "lw": 0.7,
+                "solid_capstyle": "projecting",
+                "clip_on": False,
+                "zorder": _Z_ARTIST,
+            },
+        },
+        # Short gaps get two inward-pointing arrows whose tails extend outside
+        # the interval; ``mutation_scale`` is computed from the span, between
+        # ``narrow_scale_min`` and ``narrow_scale_max``.
+        "narrow_arrow": {
+            "annotate": {
+                "zorder": _Z_ARTIST,
+                "arrowprops": {
+                    "arrowstyle": "-|>",
+                    "shrinkA": 0,
+                    "shrinkB": 0,
+                    "color": _DIM,
+                    "lw": 0.7,
+                },
+            },
+        },
+        "wide_arrow": {
+            "annotate": {
+                "zorder": _Z_ARTIST,
+                "arrowprops": {
+                    "arrowstyle": "<|-|>",
+                    "shrinkA": 0,
+                    "shrinkB": 0,
+                    "color": _DIM,
+                    "lw": 0.7,
+                    "mutation_scale": 6.0,
+                },
+            },
+        },
+        "hlabel": {
+            "text": {
+                **_LABEL_FONT,
+                "color": _DIM,
+                "ha": "center",
+                "va": "top",
+                "rotation": 0,
+                "bbox": {**_LABEL_BBOX, "alpha": 0.5},
+            },
+        },
+        "vlabel_left": {
+            "text": {
+                **_LABEL_FONT,
+                "color": _DIM,
+                "ha": "right",
+                "va": "center",
+                "rotation": 90,
+                "bbox": {**_LABEL_BBOX, "alpha": 0.5},
+            },
+        },
+        "vlabel_right": {
+            "text": {
+                **_LABEL_FONT,
+                "color": _DIM,
+                "ha": "left",
+                "va": "center",
+                "rotation": 90,
+                "bbox": {**_LABEL_BBOX, "alpha": 0.5},
+            },
+        },
+    },
+    "numbered_axes": {
+        "show": True,
+        "right_edge": 1.0,
+        "marker_step": 0.040,
+        "label_side": "left",
+        "template": "%.3f cm",
+        "top": {"show": True},
+        "bottom": {"show": True},
+    },
+    # Primary-axes margin dimensions. The top/bottom pair rides the primary
+    # axes' right border -- just inside it, mirroring where ``left`` sits --
+    # so it tracks the axes it measures and leaves the layout panel the whole
+    # left side. ``left`` measures along the top edge and keeps its own place.
+    "margins": {
+        "template": "%.3f cm",
+        "label_side": "right",
+        # Axes that get no margin dimensions at all. A logo plate is placed by
+        # eye in a corner, not designed against the page edges, so measuring it
+        # only adds a column that collides with the ones that matter.
+        "exclude": ["axlogo"],
+        # Axes that end at the same x would draw on top of each other, so each
+        # one after the first steps this far further inside the border.
+        "marker_step": 0.040,
+        "left": {"show": True},
+        "top": {"show": True},
+        "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
+    # every card.
+    "panel": {
+        "show": True,
+        "pad_x_max": 0.018,
+        "pad_x_min": 0.004,
+        "pad_x_factor": 0.025,
+        "pad_y_max": 0.018,
+        "pad_y_min": 0.004,
+        "pad_y_factor": 0.035,
+        "entry_gap": 5.0,
+        "char_width_factor": 0.62,
+        "detail_lines_per_entry": 2.0,
+        "text_inset_x": 0.008,
+        "text_inset_y": 0.006,
+        "box": {
+            "FancyBboxPatch": {
+                "boxstyle": "round,pad=0.004",
+                "facecolor": _PANEL,
+                "alpha": 0.5,
+                "edgecolor": "none",
+                "linewidth": 0.0,
+                "zorder": _Z_ARTIST,
+            },
+        },
+        # ``size`` is used as written on every figure; ``fontsize`` is the one
+        # text kwarg Python supplies, and it supplies exactly this.
+        "header": {
+            "label": "axes layout",
+            "size": 6.0,
+            "leading": 1.20,
+            "text": {
+                "color": _NAME,
+                "fontweight": "bold",
+                "ha": "left",
+                "va": "top",
+                "family": "monospace",
+                "clip_on": True,
+                "zorder": _Z_TEXT,
+            },
+        },
+        "name": {
+            "size": 7.0,
+            "leading": 1.15,
+            "text": {
+                "color": _NAME,
+                "fontweight": "bold",
+                "ha": "left",
+                "va": "top",
+                "family": "monospace",
+                "clip_on": True,
+                "zorder": _Z_TEXT,
+            },
+        },
+        "detail": {
+            "size": 4.6,
+            "leading": 1.08,
+            "rect_template": "  rect=[%.3f, %.3f, %.3f, %.3f]",
+            "size_template": "  width: %.3f cm  height: %.3f cm",
+            "text": {
+                "color": _NAME,
+                "fontweight": "normal",
+                "ha": "left",
+                "va": "top",
+                "family": "monospace",
+                "clip_on": True,
+                "zorder": _Z_TEXT,
+            },
+        },
+    },
+    # Ternary tick anchors and label leader lines, drawn during axtri build.
+    "ternary": {
+        "tick_anchors": {
+            "show": True,
+            "scatter": {"s": 1.0, "marker": ".", "c": _TERNARY, "clip_on": False},
+        },
+        "label_leaders": {
+            "show": True,
+            "plot": {
+                "marker": ".",
+                "linestyle": "-",
+                "lw": 0.3,
+                "markersize": 1,
+                "c": _TERNARY,
+                "clip_on": False,
+            },
+        },
+    },
+}
+
+
+#: Blocks named after the matplotlib callable that receives them. Their keys
+#: are matplotlib's vocabulary, so the merge stops validating inside them --
+#: the same way ``layers[].style`` is a delegated zone in the YAML schema.
+#: Jarvis-PLOT does not enumerate what matplotlib accepts.
+CALL_BLOCKS = (
+    "add_axes",
+    "annotate",
+    "plot",
+    "scatter",
+    "text",
+    "FancyBboxPatch",
+    "Rectangle",
+)
+
+
+def deep_update(base: Mapping, override: Mapping | None) -> dict:
+    """Layer one override mapping over another, without validating either.
+
+    Used to combine a style card's ``Debug`` block with a figure's YAML
+    ``debug:`` mapping. Validation is deliberately not done here: both are
+    partial by design, so checking them against each other would report every
+    key the card happens not to mention. :func:`merge_debug_config` validates
+    the combined result against :data:`DEFAULT_DEBUG` once, later.
+
+    Non-mapping values replace rather than merge -- notably lists, so a card
+    overriding ``primary_order`` sets it instead of appending to it.
+    """
+    merged = deepcopy(dict(base))
+    if not isinstance(override, Mapping):
+        return merged
+    for key, value in override.items():
+        if isinstance(value, Mapping) and isinstance(merged.get(key), Mapping):
+            merged[key] = deep_update(merged[key], value)
+        else:
+            merged[key] = deepcopy(value)
+    return merged
+
+
+def _is_delegated(key: str) -> bool:
+    return key in CALL_BLOCKS
+
+
+def merge_debug_config(
+    base: Mapping,
+    override: Mapping | None,
+    *,
+    path: str = "",
+    problems: list[str] | None = None,
+) -> tuple[dict, list[str]]:
+    """Merge a ``Debug`` block over the defaults, reporting what it had to drop.
+
+    Returns ``(merged, problems)``. Two things used to fail in silence here and
+    now surface instead:
+
+    - a key the defaults do not define was carried through as inert junk, so a
+      typo looked exactly like a working override;
+    - a scalar written where the defaults hold a mapping was discarded outright.
+
+    Inside a call block (see :data:`CALL_BLOCKS`) neither check applies: those
+    keys belong to matplotlib. Overrides there are layered key by key, so a
+    card may change one arrow property without restating the rest.
+
+    Neither ever raises. A bad ``Debug`` block degrades to the defaults and says
+    so once, because a debug overlay must never be able to break a plot.
+    """
+    problems = [] if problems is None else problems
+    merged = deepcopy(dict(base))
+    if not isinstance(override, Mapping):
+        return merged, problems
+
+    for key, value in override.items():
+        where = f"{path}{key}"
+        if key not in merged:
+            hint = did_you_mean(str(key), [str(k) for k in merged])
+            suffix = f" Did you mean {hint[0]!r}?" if hint else ""
+            problems.append(f"{where}: unknown Debug key, ignored.{suffix}")
+            continue
+
+        if _is_delegated(str(key)):
+            # matplotlib kwargs: take the override wholesale, validate nothing.
+            if isinstance(merged[key], Mapping) and isinstance(value, Mapping):
+                merged[key] = deep_update(merged[key], value)
+            else:
+                merged[key] = deepcopy(value)
+            continue
+
+        if isinstance(merged[key], Mapping):
+            if isinstance(value, Mapping):
+                merged[key], _ = merge_debug_config(
+                    merged[key], value, path=f"{where}.", problems=problems
+                )
+            else:
+                problems.append(
+                    f"{where}: expected a mapping, got "
+                    f"{type(value).__name__}; kept the default."
+                )
+            continue
+
+        merged[key] = deepcopy(value)
+
+    return merged, problems
+
+
+def resolve_debug_config(fig) -> dict:
+    """Return the merged debug settings, logging anything the merge dropped."""
+    merged, problems = merge_debug_config(
+        DEFAULT_DEBUG,
+        getattr(fig, "debug_config", getattr(fig, "_debug_config", None)),
+    )
+    if problems:
+        logger = getattr(fig, "logger", None)
+        warn = getattr(logger, "warning", None)
+        if callable(warn):
+            try:
+                warn("Debug config:\n\t" + "\n\t".join(problems))
+            except Exception:
+                pass
+    return merged