scitex 2.5.0__py3-none-any.whl → 2.7.3__py3-none-any.whl

scitex/plt/utils/metadata/_precision_sections.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_precision_sections.py
+
+"""
+Section-specific precision rounding utilities.
+
+This module provides functions to round numeric values in specific sections
+of the metadata dictionary (figure, axes, style, plot, etc.).
+"""
+
+from ._precision_config import PRECISION, _round_value, _round_list
+
+
+def _round_figure_section(fig_data: dict) -> dict:
+    """Round values in figure section."""
+    result = {}
+    for key, value in fig_data.items():
+        if key == "size_mm":
+            result[key] = _round_list(value, PRECISION["mm"], fixed=True)
+        elif key == "size_inch":
+            result[key] = _round_list(value, PRECISION["inch"], fixed=True)
+        elif key == "size_px":
+            result[key] = [int(v) for v in value]
+        elif key == "dpi":
+            result[key] = int(value)
+        else:
+            result[key] = value
+    return result
+
+
+def _round_axes_section(axes_data: dict) -> dict:
+    """Round values in axes section.
+
+    Handles both flat structure (legacy) and nested structure (ax_00, ax_01, ...).
+    """
+    result = {}
+    for key, value in axes_data.items():
+        # Check if this is a nested axes key
+        if key.startswith("ax_") and isinstance(value, dict):
+            result[key] = _round_single_axes_data(value)
+        else:
+            result[key] = _round_single_axes_data({key: value}).get(key, value)
+    return result
+
+
+def _round_single_axes_data(ax_data: dict) -> dict:
+    """Round values for a single axes' data."""
+    result = {}
+    for key, value in ax_data.items():
+        if key == "size_mm":
+            result[key] = _round_list(value, PRECISION["mm"], fixed=True)
+        elif key == "size_inch":
+            result[key] = _round_list(value, PRECISION["inch"], fixed=True)
+        elif key == "size_px":
+            result[key] = [int(v) for v in value]
+        elif key in ("position", "position_ratio", "bounds_figure_fraction"):
+            result[key] = _round_list(value, PRECISION["position"], fixed=True)
+        elif key == "position_in_grid":
+            result[key] = [int(v) for v in value]
+        elif key == "margins_mm":
+            result[key] = {k: _round_value(v, PRECISION["mm"], fixed=True) for k, v in value.items()}
+        elif key == "margins_inch":
+            result[key] = {k: _round_value(v, PRECISION["inch"], fixed=True) for k, v in value.items()}
+        elif key == "bbox_mm":
+            result[key] = {k: _round_value(v, PRECISION["mm"], fixed=True) for k, v in value.items()}
+        elif key == "bbox_inch":
+            result[key] = {k: _round_value(v, PRECISION["inch"], fixed=True) for k, v in value.items()}
+        elif key == "bbox_px":
+            result[key] = {k: int(v) for k, v in value.items()}
+        elif key in ("xaxis", "yaxis", "xaxis_top", "yaxis_right"):
+            result[key] = _round_axis_info(value)
+        elif key == "legend":
+            result[key] = value
+        elif key == "artists":
+            result[key] = [_round_artist(a) for a in value]
+        else:
+            result[key] = value
+    return result
+
+
+def _round_axis_info(axis_data: dict) -> dict:
+    """Round values in axis info dictionary."""
+    axis_result = {}
+    for ak, av in axis_data.items():
+        if ak == "lim":
+            axis_result[ak] = _round_list(av, PRECISION["lim"], fixed=True)
+        elif ak == "n_ticks":
+            axis_result[ak] = int(av)
+        else:
+            axis_result[ak] = av
+    return axis_result
+
+
+def _round_style_section(style_data: dict) -> dict:
+    """Round values in hierarchical style section with scopes."""
+    result = {}
+    for scope, scope_data in style_data.items():
+        if scope in ("global", "axes_default", "artist_default"):
+            result[scope] = {}
+            for category, category_data in scope_data.items():
+                if isinstance(category_data, dict):
+                    result[scope][category] = _round_style_subsection(category, category_data)
+                else:
+                    result[scope][category] = category_data
+        elif isinstance(scope_data, dict):
+            result[scope] = _round_style_subsection(scope, scope_data)
+        elif isinstance(scope_data, float):
+            if "_mm" in scope:
+                result[scope] = _round_value(scope_data, PRECISION["mm"], fixed=True)
+            elif "_pt" in scope:
+                result[scope] = _round_value(scope_data, 1, fixed=True)
+            else:
+                result[scope] = _round_value(scope_data, 2)
+        elif isinstance(scope_data, int):
+            result[scope] = scope_data
+        else:
+            result[scope] = scope_data
+    return result
+
+
+def _round_style_subsection(category: str, data: dict) -> dict:
+    """Round values in a style subsection based on category."""
+    result = {}
+    for key, value in data.items():
+        if isinstance(value, float):
+            if "_mm" in key or category in ("axes", "ticks", "lines", "markers"):
+                result[key] = _round_value(value, PRECISION["mm"], fixed=True)
+            elif "_pt" in key or category in ("fonts", "padding"):
+                result[key] = _round_value(value, 1, fixed=True)
+            else:
+                result[key] = _round_value(value, 2)
+        elif isinstance(value, int):
+            result[key] = value
+        else:
+            result[key] = value
+    return result
+
+
+def _round_plot_section(plot_data: dict) -> dict:
+    """Round values in plot section."""
+    result = {}
+    for key, value in plot_data.items():
+        if key == "artists":
+            result[key] = [_round_artist(a) for a in value]
+        elif key == "legend":
+            result[key] = value
+        else:
+            result[key] = value
+    return result
+
+
+def _round_artist(artist: dict) -> dict:
+    """Round values in a single artist."""
+    result = {}
+    for key, value in artist.items():
+        if key == "style" and isinstance(value, dict):
+            result[key] = _round_style_dict(value)
+        elif key == "backend" and isinstance(value, dict):
+            result[key] = _round_backend_dict(value)
+        elif key == "geometry" and isinstance(value, dict):
+            result[key] = _round_geometry_dict(value)
+        elif key == "zorder":
+            result[key] = int(value) if isinstance(value, (int, float)) else value
+        else:
+            result[key] = value
+    return result
+
+
+def _round_style_dict(style: dict) -> dict:
+    """Round values in legacy style dict."""
+    style_result = {}
+    for sk, sv in style.items():
+        if sk in ("linewidth_pt", "markersize_pt"):
+            style_result[sk] = _round_value(sv, PRECISION["linewidth"], fixed=True)
+        else:
+            style_result[sk] = sv
+    return style_result
+
+
+def _round_backend_dict(backend: dict) -> dict:
+    """Round values in backend dict."""
+    backend_result = {"name": backend.get("name", "matplotlib")}
+    if "artist_class" in backend:
+        backend_result["artist_class"] = backend["artist_class"]
+    if "props" in backend and isinstance(backend["props"], dict):
+        props_result = {}
+        for pk, pv in backend["props"].items():
+            if pk in ("linewidth_pt", "markersize_pt"):
+                props_result[pk] = _round_value(pv, PRECISION["linewidth"], fixed=True)
+            elif pk == "size":
+                props_result[pk] = _round_value(pv, 1, fixed=True)
+            else:
+                props_result[pk] = pv
+        backend_result["props"] = props_result
+    return backend_result
+
+
+def _round_geometry_dict(geometry: dict) -> dict:
+    """Round values in geometry dict."""
+    geom_result = {}
+    for gk, gv in geometry.items():
+        if isinstance(gv, float):
+            geom_result[gk] = _round_value(gv, 4, fixed=False)
+        else:
+            geom_result[gk] = gv
+    return geom_result
+
+
+# Backward compatibility alias
+_round_trace = _round_artist

scitex/plt/utils/metadata/_recipe_extraction.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_recipe_extraction.py
+
+"""
+Recipe metadata extraction utilities.
+
+This module provides functions to extract reconstruction recipes from axes history,
+allowing figures to be recreated from metadata and CSV data.
+"""
+
+from typing import List, Dict
+
+
+def collect_recipe_metadata(
+    fig,
+    ax=None,
+    include_recipe: bool = True,
+    auto_crop: bool = True,
+    crop_margin_mm: float = 1.0,
+) -> dict:
+    """
+    Collect minimal "recipe" metadata - much smaller than verbose schema.
+
+    Uses scitex.plt.figure.recipe schema which only includes:
+    - Figure/axes dimensions
+    - Method calls with arguments (from ax.history)
+    - Data column references for CSV linkage
+    - Top-level axes_bbox_px for canvas alignment
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        Figure to collect metadata from
+    ax : optional
+        Axes or AxesWrapper
+    include_recipe : bool
+        Whether to include reconstruction recipe
+    auto_crop : bool
+        Whether auto_crop was enabled when saving
+    crop_margin_mm : float
+        Crop margin in mm (if auto_crop was used)
+
+    Returns
+    -------
+    dict
+        Minimal metadata with recipe schema (~95% smaller than verbose)
+    """
+    # Import the recipe schema collector from _collect_figure_metadata
+    # This uses scitex.plt.figure.recipe schema (minimal)
+    from .._collect_figure_metadata import collect_recipe_metadata as _collect_recipe
+
+    return _collect_recipe(fig, ax, auto_crop=auto_crop, crop_margin_mm=crop_margin_mm)
+
+
+def _extract_calls_from_history(ax, ax_index: int) -> List[dict]:
+    """
+    Extract method call records from axis history.
+
+    Parameters
+    ----------
+    ax : AxisWrapper or matplotlib.axes.Axes
+        Axis to extract history from
+    ax_index : int
+        Index of axis in figure (for CSV column naming)
+
+    Returns
+    -------
+    list
+        List of call records: [{id, method, data_ref, kwargs}, ...]
+    """
+    calls = []
+
+    # Check for scitex wrapper with history
+    if not hasattr(ax, 'history') and not hasattr(ax, '_ax_history'):
+        return calls
+
+    # Get history dict
+    history = getattr(ax, 'history', None)
+    if history is None:
+        history = getattr(ax, '_ax_history', {})
+
+    # Get grid position
+    ax_row = 0
+    ax_col = 0
+    if hasattr(ax, "_scitex_metadata"):
+        pos = ax._scitex_metadata.get("position_in_grid", [0, 0])
+        ax_row, ax_col = pos[0], pos[1]
+
+    for trace_id, record in history.items():
+        # record format: (id, method_name, tracked_dict, kwargs)
+        if not isinstance(record, (list, tuple)) or len(record) < 3:
+            continue
+
+        call_id, method_name, tracked_dict = record[0], record[1], record[2]
+        kwargs = record[3] if len(record) > 3 else {}
+
+        call = {
+            "id": str(call_id),
+            "method": method_name,
+        }
+
+        # Build data_ref from tracked_dict to CSV column names
+        data_ref = _build_data_ref(call_id, method_name, tracked_dict, ax_row, ax_col)
+        if data_ref:
+            call["data_ref"] = data_ref
+
+        # Filter kwargs to only style-relevant ones (not data)
+        style_kwargs = _filter_style_kwargs(kwargs, method_name)
+        if style_kwargs:
+            call["kwargs"] = style_kwargs
+
+        calls.append(call)
+
+    return calls
+
+
+def _build_data_ref(trace_id, method_name: str, tracked_dict: dict,
+                    ax_row: int, ax_col: int) -> dict:
+    """
+    Build data_ref mapping from tracked_dict to CSV column names.
+
+    Parameters
+    ----------
+    trace_id : str
+        Trace identifier
+    method_name : str
+        Name of the method called
+    tracked_dict : dict
+        Data tracked by the method (contains arrays, dataframes)
+    ax_row, ax_col : int
+        Axis position in grid
+
+    Returns
+    -------
+    dict
+        Mapping of variable names to CSV column names
+    """
+    prefix = f"ax-row-{ax_row}-col-{ax_col}_trace-id-{trace_id}_variable-"
+
+    data_ref = {}
+
+    # Method-specific column naming
+    if method_name == 'hist':
+        data_ref["raw_data"] = f"{prefix}raw-data"
+        data_ref["bin_centers"] = f"{prefix}bin-centers"
+        data_ref["bin_counts"] = f"{prefix}bin-counts"
+    elif method_name in ('plot', 'scatter', 'step', 'errorbar'):
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+        if tracked_dict and 'yerr' in tracked_dict:
+            data_ref["yerr"] = f"{prefix}yerr"
+        if tracked_dict and 'xerr' in tracked_dict:
+            data_ref["xerr"] = f"{prefix}xerr"
+    elif method_name in ('bar', 'barh'):
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    elif method_name == 'stem':
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    elif method_name in ('fill_between', 'fill_betweenx'):
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y1"] = f"{prefix}y1"
+        data_ref["y2"] = f"{prefix}y2"
+    elif method_name in ('imshow', 'matshow', 'pcolormesh'):
+        data_ref["data"] = f"{prefix}data"
+    elif method_name in ('contour', 'contourf'):
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+        data_ref["z"] = f"{prefix}z"
+    elif method_name in ('boxplot', 'violinplot'):
+        data_ref["data"] = f"{prefix}data"
+    elif method_name == 'pie':
+        data_ref["x"] = f"{prefix}x"
+    elif method_name in ('quiver', 'streamplot'):
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+        data_ref["u"] = f"{prefix}u"
+        data_ref["v"] = f"{prefix}v"
+    elif method_name == 'hexbin':
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    elif method_name == 'hist2d':
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    elif method_name == 'kde':
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    # SciTeX custom methods (stx_*)
+    elif method_name == 'stx_line':
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    elif method_name in ('stx_mean_std', 'stx_mean_ci', 'stx_median_iqr', 'stx_shaded_line'):
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y_lower"] = f"{prefix}y-lower"
+        data_ref["y_middle"] = f"{prefix}y-middle"
+        data_ref["y_upper"] = f"{prefix}y-upper"
+    elif method_name in ('stx_box', 'stx_violin'):
+        data_ref["data"] = f"{prefix}data"
+    elif method_name == 'stx_scatter_hist':
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    elif method_name in ('stx_heatmap', 'stx_conf_mat', 'stx_image', 'stx_raster'):
+        data_ref["data"] = f"{prefix}data"
+    elif method_name in ('stx_kde', 'stx_ecdf'):
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    elif method_name.startswith('stx_'):
+        data_ref["x"] = f"{prefix}x"
+        data_ref["y"] = f"{prefix}y"
+    else:
+        # Generic fallback
+        if tracked_dict:
+            if 'x' in tracked_dict or 'args' in tracked_dict:
+                data_ref["x"] = f"{prefix}x"
+                data_ref["y"] = f"{prefix}y"
+
+    return data_ref
+
+
+def _filter_style_kwargs(kwargs: dict, method_name: str) -> dict:
+    """
+    Filter kwargs to only include style-relevant parameters.
+
+    Removes data arrays and internal parameters, keeps style settings
+    that affect appearance (color, linewidth, etc.).
+
+    Parameters
+    ----------
+    kwargs : dict
+        Original keyword arguments
+    method_name : str
+        Name of the method
+
+    Returns
+    -------
+    dict
+        Filtered kwargs with only style parameters
+    """
+    if not kwargs:
+        return {}
+
+    # Style-relevant kwargs to keep
+    style_keys = {
+        'color', 'c', 'facecolor', 'edgecolor', 'linecolor',
+        'linewidth', 'lw', 'linestyle', 'ls',
+        'marker', 'markersize', 'ms', 'markerfacecolor', 'markeredgecolor',
+        'alpha', 'zorder',
+        'label',
+        'bins', 'density', 'histtype', 'orientation',
+        'width', 'height', 'align',
+        'cmap', 'vmin', 'vmax', 'norm',
+        'levels', 'extend',
+        'scale', 'units',
+        'autopct', 'explode', 'shadow', 'startangle',
+    }
+
+    filtered = {}
+    for key, value in kwargs.items():
+        if key in style_keys:
+            # Skip if value is a large array (data, not style)
+            if hasattr(value, '__len__') and not isinstance(value, str):
+                if len(value) > 10:
+                    continue
+            filtered[key] = value
+
+    return filtered

scitex/plt/utils/metadata/_style_parsing.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_style_parsing.py
+
+"""
+Style dictionary restructuring utilities.
+
+This module provides functions to convert flat style dictionaries into
+hierarchical structures with explicit scopes (global, axes_default, artist_default).
+"""
+
+from typing import Dict
+
+
+def _restructure_style(flat_style: dict) -> dict:
+    """
+    Restructure flat style_mm dict into hierarchical structure with explicit scopes.
+
+    Converts:
+        {"axis_thickness_mm": 0.2, "tick_length_mm": 0.8, ...}
+    To:
+        {
+            "global": {"fonts": {...}, "padding": {...}},
+            "axes_default": {"axes": {...}, "ticks": {...}},
+            "artist_default": {"lines": {...}, "markers": {...}}
+        }
+
+    Style scopes:
+    - global: rcParams-like settings (fonts, padding) applied to entire figure
+    - axes_default: default axes appearance (can be overridden per-axes)
+    - artist_default: default artist appearance (can be overridden per-artist)
+    """
+    result = {
+        "global": {
+            "fonts": {},
+            "padding": {},
+        },
+        "axes_default": {
+            "axes": {},
+            "ticks": {},
+        },
+        "artist_default": {
+            "lines": {},
+            "markers": {},
+        },
+    }
+
+    # Mapping from flat keys to hierarchical structure (scope, category, key)
+    key_mapping = {
+        # Axes-level defaults
+        "axis_thickness_mm": ("axes_default", "axes", "thickness_mm"),
+        "axes_thickness_mm": ("axes_default", "axes", "thickness_mm"),
+        "tick_length_mm": ("axes_default", "ticks", "length_mm"),
+        "tick_thickness_mm": ("axes_default", "ticks", "thickness_mm"),
+        "n_ticks": ("axes_default", "ticks", "n_ticks"),
+        # Artist-level defaults (Line2D, markers)
+        "trace_thickness_mm": ("artist_default", "lines", "thickness_mm"),
+        "line_thickness_mm": ("artist_default", "lines", "thickness_mm"),
+        "marker_size_mm": ("artist_default", "markers", "size_mm"),
+        "scatter_size_mm": ("artist_default", "markers", "scatter_size_mm"),
+        # Global defaults (rcParams-like)
+        "font_family": ("global", "fonts", "family"),
+        "font_family_requested": ("global", "fonts", "family_requested"),
+        "font_family_actual": ("global", "fonts", "family_actual"),
+        "axis_font_size_pt": ("global", "fonts", "axis_size_pt"),
+        "tick_font_size_pt": ("global", "fonts", "tick_size_pt"),
+        "title_font_size_pt": ("global", "fonts", "title_size_pt"),
+        "legend_font_size_pt": ("global", "fonts", "legend_size_pt"),
+        "suptitle_font_size_pt": ("global", "fonts", "suptitle_size_pt"),
+        "annotation_font_size_pt": ("global", "fonts", "annotation_size_pt"),
+        "label_pad_pt": ("global", "padding", "label_pt"),
+        "tick_pad_pt": ("global", "padding", "tick_pt"),
+        "title_pad_pt": ("global", "padding", "title_pt"),
+    }
+
+    for key, value in flat_style.items():
+        if key in key_mapping:
+            scope, category, new_key = key_mapping[key]
+            result[scope][category][new_key] = value
+        else:
+            # Unknown keys go to a misc section or are kept at top level
+            # For now, skip unknown keys to keep structure clean
+            pass
+
+    # Remove empty categories within each scope
+    for scope in list(result.keys()):
+        result[scope] = {k: v for k, v in result[scope].items() if v}
+        # Remove empty scopes
+        if not result[scope]:
+            del result[scope]
+
+    return result
+
+
+def _collect_style_metadata(fig, ax) -> dict:
+    """
+    Collect style metadata from figure and axes.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        Figure to extract style from
+    ax
+        Axes or AxesWrapper to extract style from
+
+    Returns
+    -------
+    dict
+        Hierarchical style metadata
+    """
+    style_metadata = {}
+
+    # Extract style_mm from figure metadata if available
+    if hasattr(fig, "_scitex_metadata") and "style_mm" in fig._scitex_metadata:
+        flat_style = fig._scitex_metadata["style_mm"]
+        style_metadata = _restructure_style(flat_style)
+
+    # Extract style_mm from axes metadata if available
+    elif hasattr(ax, "_scitex_metadata") and "style_mm" in ax._scitex_metadata:
+        flat_style = ax._scitex_metadata["style_mm"]
+        style_metadata = _restructure_style(flat_style)
+
+    # Try to extract from wrapped axes if this is an AxisWrapper
+    elif hasattr(ax, "_ax"):
+        mpl_ax = ax._ax
+        if hasattr(mpl_ax, "_scitex_metadata") and "style_mm" in mpl_ax._scitex_metadata:
+            flat_style = mpl_ax._scitex_metadata["style_mm"]
+            style_metadata = _restructure_style(flat_style)
+
+    return style_metadata
+
+
+def _extract_mode_and_method(fig, ax) -> tuple:
+    """
+    Extract mode (display/publication) and creation method from metadata.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        Figure to extract metadata from
+    ax
+        Axes or AxesWrapper to extract metadata from
+
+    Returns
+    -------
+    tuple
+        (mode, creation_method) where each is a string or None
+    """
+    mode = None
+    creation_method = None
+
+    # Try figure metadata first
+    if hasattr(fig, "_scitex_metadata"):
+        mode = fig._scitex_metadata.get("mode")
+        creation_method = fig._scitex_metadata.get("creation_method")
+
+    # Try axes metadata if not found in figure
+    if mode is None or creation_method is None:
+        if hasattr(ax, "_scitex_metadata"):
+            if mode is None:
+                mode = ax._scitex_metadata.get("mode")
+            if creation_method is None:
+                creation_method = ax._scitex_metadata.get("creation_method")
+
+        # Try wrapped axes
+        elif hasattr(ax, "_ax"):
+            mpl_ax = ax._ax
+            if hasattr(mpl_ax, "_scitex_metadata"):
+                if mode is None:
+                    mode = mpl_ax._scitex_metadata.get("mode")
+                if creation_method is None:
+                    creation_method = mpl_ax._scitex_metadata.get("creation_method")
+
+    return mode, creation_method