scitex 2.14.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/plt/utils/_metadata/__init__.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_metadata/__init__.py
+
+"""
+Figure metadata extraction package.
+
+This package provides modular utilities for extracting metadata from
+matplotlib figures, split from the original _collect_figure_metadata.py.
+
+Modules:
+- _rounding: Precision-controlled rounding utilities
+- _detect: Plot type detection
+- _csv: CSV column naming and hash computation
+- _verification: CSV/JSON consistency verification
+- _legend: Legend extraction
+- _artists: Artist extraction (lines, collections, patches, images, text)
+"""
+
+# Rounding utilities
+# Artist extraction
+from ._artists import _extract_artists, _extract_traces
+
+# CSV utilities
+from ._csv import (
+    _compute_csv_hash,
+    _compute_csv_hash_from_df,
+    _extract_csv_columns_from_history,
+    _get_csv_column_names,
+    _get_csv_columns_for_method,
+    _get_csv_columns_for_method_with_index,
+)
+
+# Plot type detection
+from ._detect import _detect_plot_type
+
+# Legend extraction
+from ._legend import _extract_legend_info
+from ._rounding import (
+    PRECISION,
+    FixedFloat,
+    _round_dict,
+    _round_list,
+    _round_value,
+)
+
+# Verification
+from ._verification import (
+    assert_csv_json_consistency,
+    verify_csv_json_consistency,
+)
+
+__all__ = [
+    # Rounding
+    "PRECISION",
+    "FixedFloat",
+    "_round_value",
+    "_round_list",
+    "_round_dict",
+    # Detection
+    "_detect_plot_type",
+    # CSV
+    "_get_csv_column_names",
+    "_extract_csv_columns_from_history",
+    "_get_csv_columns_for_method_with_index",
+    "_get_csv_columns_for_method",
+    "_compute_csv_hash_from_df",
+    "_compute_csv_hash",
+    # Verification
+    "assert_csv_json_consistency",
+    "verify_csv_json_consistency",
+    # Legend
+    "_extract_legend_info",
+    # Artists
+    "_extract_artists",
+    "_extract_traces",
+]
+
+
+# EOF

scitex/plt/utils/_metadata/_artists/__init__.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_metadata/_artists/__init__.py
+
+"""
+Artist extraction for figure metadata.
+
+This package splits the large _extract_artists function into logical modules:
+- _base: Common utilities and context setup
+- _lines: Line2D artist extraction (including boxplot/violin/stem semantics)
+- _collections: Collection artist extraction (scatter, hexbin, violin bodies)
+- _patches: Patch artist extraction (bar, pie, histogram)
+- _images: Image artist extraction
+- _text: Text artist extraction
+"""
+
+from ._extract import _extract_artists
+
+# Backward compatibility alias
+_extract_traces = _extract_artists
+
+__all__ = ["_extract_artists", "_extract_traces"]
+
+
+# EOF

scitex/plt/utils/_metadata/_artists/_base.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_metadata/_artists/_base.py
+
+"""
+Base utilities for artist extraction.
+
+Provides common context and helper functions used across artist extractors.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import matplotlib.colors as mcolors
+
+
+@dataclass
+class ExtractionContext:
+    """Context for artist extraction operations."""
+
+    ax: Any  # matplotlib axes
+    mpl_ax: Any  # raw matplotlib axes
+    ax_for_detection: Any  # axes for plot type detection
+    ax_row: int = 0
+    ax_col: int = 0
+    plot_type: Optional[str] = None
+    method: Optional[str] = None
+    skip_unlabeled: bool = False
+    id_to_history: Dict[str, tuple] = field(default_factory=dict)
+
+    # Boxplot specific
+    is_boxplot: bool = False
+    num_boxes: int = 0
+    boxplot_data: Optional[List] = None
+    boxplot_stats: List[dict] = field(default_factory=list)
+
+    # Violin specific
+    is_violin: bool = False
+
+    # Stem specific
+    is_stem: bool = False
+
+
+def create_extraction_context(ax) -> ExtractionContext:
+    """Create an extraction context from axes."""
+    from .._detect import _detect_plot_type
+
+    # Get axes position for CSV column naming
+    ax_row, ax_col = 0, 0
+    if hasattr(ax, "_scitex_metadata") and "position_in_grid" in ax._scitex_metadata:
+        pos = ax._scitex_metadata["position_in_grid"]
+        ax_row, ax_col = pos[0], pos[1]
+
+    # Get the raw matplotlib axes
+    mpl_ax = ax._axis_mpl if hasattr(ax, "_axis_mpl") else ax
+
+    # Try to find scitex wrapper for plot type detection
+    ax_for_detection = ax
+    if not hasattr(ax, "history") and hasattr(mpl_ax, "_scitex_wrapper"):
+        ax_for_detection = mpl_ax._scitex_wrapper
+
+    # Detect plot type
+    plot_type, method = _detect_plot_type(ax_for_detection)
+
+    # Plot types where internal artists should be hidden
+    internal_plot_types = {
+        "boxplot",
+        "violin",
+        "hist",
+        "bar",
+        "image",
+        "heatmap",
+        "kde",
+        "ecdf",
+        "errorbar",
+        "fill",
+        "stem",
+        "contour",
+        "pie",
+        "quiver",
+        "stream",
+    }
+    skip_unlabeled = plot_type in internal_plot_types
+
+    # Build history map
+    id_to_history = {}
+    if hasattr(ax_for_detection, "history"):
+        for record_id, record in ax_for_detection.history.items():
+            if isinstance(record, tuple) and len(record) >= 2:
+                tracking_id = record[0]
+                id_to_history[tracking_id] = record
+
+    ctx = ExtractionContext(
+        ax=ax,
+        mpl_ax=mpl_ax,
+        ax_for_detection=ax_for_detection,
+        ax_row=ax_row,
+        ax_col=ax_col,
+        plot_type=plot_type,
+        method=method,
+        skip_unlabeled=skip_unlabeled,
+        id_to_history=id_to_history,
+        is_boxplot=plot_type == "boxplot",
+        is_violin=plot_type == "violin",
+        is_stem=plot_type == "stem",
+    )
+
+    # Extract boxplot info
+    if ctx.is_boxplot:
+        _extract_boxplot_info(ctx)
+
+    return ctx
+
+
+def _extract_boxplot_info(ctx: ExtractionContext) -> None:
+    """Extract boxplot specific information."""
+    import numpy as np
+
+    if not hasattr(ctx.ax_for_detection, "history"):
+        return
+
+    for record in ctx.ax_for_detection.history.values():
+        if isinstance(record, tuple) and len(record) >= 3:
+            method_name = record[1]
+            if method_name == "boxplot":
+                tracked_dict = record[2]
+                args = tracked_dict.get("args", [])
+                if args and len(args) > 0:
+                    data = args[0]
+                    if hasattr(data, "__len__") and not isinstance(data, str):
+                        if hasattr(data[0], "__len__") and not isinstance(data[0], str):
+                            ctx.num_boxes = len(data)
+                            ctx.boxplot_data = data
+                        else:
+                            ctx.num_boxes = 1
+                            ctx.boxplot_data = [data]
+                break
+
+    # Compute boxplot statistics
+    if ctx.boxplot_data is not None:
+        for box_idx, box_data in enumerate(ctx.boxplot_data):
+            try:
+                arr = np.asarray(box_data)
+                arr = arr[~np.isnan(arr)]
+                if len(arr) > 0:
+                    q1 = float(np.percentile(arr, 25))
+                    median = float(np.median(arr))
+                    q3 = float(np.percentile(arr, 75))
+                    iqr = q3 - q1
+                    whisker_low = float(max(arr.min(), q1 - 1.5 * iqr))
+                    whisker_high = float(min(arr.max(), q3 + 1.5 * iqr))
+                    fliers = arr[(arr < whisker_low) | (arr > whisker_high)]
+                    ctx.boxplot_stats.append(
+                        {
+                            "box_index": box_idx,
+                            "median": median,
+                            "q1": q1,
+                            "q3": q3,
+                            "whisker_low": whisker_low,
+                            "whisker_high": whisker_high,
+                            "n_fliers": int(len(fliers)),
+                            "n_samples": int(len(arr)),
+                        }
+                    )
+            except (ValueError, TypeError):
+                pass
+
+
+def color_to_hex(color) -> Optional[str]:
+    """Convert color to hex string."""
+    try:
+        return mcolors.to_hex(color, keep_alpha=False)
+    except (ValueError, TypeError):
+        return None
+
+
+def get_artist_id(
+    obj,
+    index: int,
+    prefix: str,
+    scitex_id: Optional[str] = None,
+    label: Optional[str] = None,
+    semantic_id: Optional[str] = None,
+) -> str:
+    """Get a unique ID for an artist."""
+    if scitex_id:
+        return scitex_id
+    if semantic_id:
+        return semantic_id
+    if label and not label.startswith("_"):
+        return label
+    return f"{prefix}_{index}"
+
+
+# EOF

scitex/plt/utils/_metadata/_artists/_collections.py

@@ -0,0 +1,356 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_metadata/_artists/_collections.py
+
+"""
+Collection artist extraction.
+
+Handles PathCollection (scatter), PolyCollection (hexbin, violin),
+QuadMesh (hist2d), and LineCollection (errorbar) extraction.
+"""
+
+from typing import List
+
+from ._base import ExtractionContext, color_to_hex
+
+
+def extract_collections(ctx: ExtractionContext) -> List[dict]:
+    """Extract collection artists from axes."""
+    artists = []
+
+    for i, coll in enumerate(ctx.mpl_ax.collections):
+        coll_type = type(coll).__name__
+
+        if "PathCollection" in coll_type:
+            artist = _extract_scatter(ctx, i, coll)
+            if artist:
+                artists.append(artist)
+        elif "PolyCollection" in coll_type:
+            artist = _extract_poly_collection(ctx, i, coll)
+            if artist:
+                artists.append(artist)
+        elif "QuadMesh" in coll_type:
+            artist = _extract_quadmesh(ctx, i, coll)
+            if artist:
+                artists.append(artist)
+        elif coll_type == "LineCollection":
+            artist = _extract_line_collection(ctx, i, coll)
+            if artist:
+                artists.append(artist)
+
+    return artists
+
+
+def _extract_scatter(ctx: ExtractionContext, index: int, coll) -> dict:
+    """Extract PathCollection (scatter) artist."""
+    from .._csv import _get_csv_column_names
+
+    artist = {}
+    scitex_id = getattr(coll, "_scitex_id", None)
+    label = coll.get_label()
+
+    if scitex_id:
+        artist["id"] = scitex_id
+    elif label and not label.startswith("_"):
+        artist["id"] = label
+    else:
+        artist["id"] = f"scatter_{index}"
+
+    artist["mark"] = "scatter"
+
+    if label and not label.startswith("_"):
+        artist["label"] = label
+        artist["legend_included"] = True
+    else:
+        artist["legend_included"] = False
+
+    artist["zorder"] = coll.get_zorder()
+
+    # Backend layer
+    backend = {
+        "name": "matplotlib",
+        "artist_class": type(coll).__name__,
+        "props": {},
+    }
+
+    try:
+        facecolors = coll.get_facecolor()
+        if len(facecolors) > 0:
+            backend["props"]["facecolor"] = color_to_hex(facecolors[0])
+    except (ValueError, TypeError, IndexError):
+        pass
+
+    try:
+        edgecolors = coll.get_edgecolor()
+        if len(edgecolors) > 0:
+            backend["props"]["edgecolor"] = color_to_hex(edgecolors[0])
+    except (ValueError, TypeError, IndexError):
+        pass
+
+    try:
+        sizes = coll.get_sizes()
+        if len(sizes) > 0:
+            backend["props"]["size"] = float(sizes[0])
+    except (ValueError, TypeError, IndexError):
+        pass
+
+    artist["backend"] = backend
+
+    # Data reference
+    artist_id = artist.get("id", str(index))
+    artist["data_ref"] = _get_csv_column_names(artist_id, ctx.ax_row, ctx.ax_col)
+
+    return artist
+
+
+def _extract_poly_collection(ctx: ExtractionContext, index: int, coll) -> dict:
+    """Extract PolyCollection (hexbin, violin body) artist."""
+    coll_type = type(coll).__name__
+
+    # Check if hexbin
+    if hasattr(coll, "get_array"):
+        arr = coll.get_array()
+        if arr is not None and len(arr) > 0 and ctx.plot_type != "violin":
+            return _extract_hexbin(ctx, index, coll, arr)
+
+    # Violin body
+    if ctx.plot_type == "violin":
+        return _extract_violin_body(ctx, index, coll)
+
+    return None
+
+
+def _extract_hexbin(ctx: ExtractionContext, index: int, coll, arr) -> dict:
+    """Extract hexbin PolyCollection."""
+    artist = {}
+    scitex_id = getattr(coll, "_scitex_id", None)
+    label = coll.get_label() if hasattr(coll, "get_label") else ""
+
+    if scitex_id:
+        artist["id"] = scitex_id
+    elif label and not label.startswith("_"):
+        artist["id"] = label
+    else:
+        artist["id"] = f"hexbin_{index}"
+
+    artist["mark"] = "hexbin"
+    artist["role"] = "hexbin"
+    artist["legend_included"] = False
+    artist["zorder"] = coll.get_zorder()
+
+    # Backend layer
+    backend = {
+        "name": "matplotlib",
+        "artist_class": type(coll).__name__,
+        "props": {},
+    }
+
+    try:
+        cmap = coll.get_cmap()
+        if cmap:
+            backend["props"]["cmap"] = cmap.name
+    except (ValueError, TypeError, AttributeError):
+        pass
+
+    try:
+        backend["props"]["vmin"] = float(coll.norm.vmin) if coll.norm else None
+        backend["props"]["vmax"] = float(coll.norm.vmax) if coll.norm else None
+    except (ValueError, TypeError, AttributeError):
+        pass
+
+    artist["backend"] = backend
+
+    # Result info
+    try:
+        artist["result"] = {
+            "n_hexagons": int(len(arr)),
+            "count_range": [float(arr.min()), float(arr.max())]
+            if len(arr) > 0
+            else None,
+            "total_count": int(arr.sum()),
+        }
+    except (TypeError, AttributeError, ValueError):
+        pass
+
+    return artist
+
+
+def _extract_violin_body(ctx: ExtractionContext, index: int, coll) -> dict:
+    """Extract violin body PolyCollection."""
+    artist = {}
+    scitex_id = getattr(coll, "_scitex_id", None)
+
+    if scitex_id:
+        artist["id"] = f"{scitex_id}_body_{index}"
+        artist["group_id"] = scitex_id
+    else:
+        artist["id"] = f"violin_body_{index}"
+
+    artist["mark"] = "polygon"
+    artist["role"] = "violin_body"
+    artist["legend_included"] = False
+    artist["zorder"] = coll.get_zorder()
+
+    # Backend layer
+    backend = {
+        "name": "matplotlib",
+        "artist_class": type(coll).__name__,
+        "props": {},
+    }
+
+    try:
+        facecolors = coll.get_facecolor()
+        if len(facecolors) > 0:
+            backend["props"]["facecolor"] = color_to_hex(facecolors[0])
+    except (ValueError, TypeError, IndexError):
+        pass
+
+    try:
+        edgecolors = coll.get_edgecolor()
+        if len(edgecolors) > 0:
+            backend["props"]["edgecolor"] = color_to_hex(edgecolors[0])
+    except (ValueError, TypeError, IndexError):
+        pass
+
+    artist["backend"] = backend
+
+    return artist
+
+
+def _extract_quadmesh(ctx: ExtractionContext, index: int, coll) -> dict:
+    """Extract QuadMesh (hist2d) artist."""
+    artist = {}
+    scitex_id = getattr(coll, "_scitex_id", None)
+    label = coll.get_label() if hasattr(coll, "get_label") else ""
+
+    if scitex_id:
+        artist["id"] = scitex_id
+    elif label and not label.startswith("_"):
+        artist["id"] = label
+    else:
+        artist["id"] = f"hist2d_{index}"
+
+    artist["mark"] = "hist2d"
+    artist["role"] = "hist2d"
+    artist["legend_included"] = False
+    artist["zorder"] = coll.get_zorder()
+
+    # Backend layer
+    backend = {
+        "name": "matplotlib",
+        "artist_class": type(coll).__name__,
+        "props": {},
+    }
+
+    try:
+        cmap = coll.get_cmap()
+        if cmap:
+            backend["props"]["cmap"] = cmap.name
+    except (ValueError, TypeError, AttributeError):
+        pass
+
+    artist["backend"] = backend
+
+    return artist
+
+
+def _extract_line_collection(ctx: ExtractionContext, index: int, coll) -> dict:
+    """Extract LineCollection (errorbar, stem) artist."""
+    artist = {}
+    scitex_id = getattr(coll, "_scitex_id", None)
+    label = coll.get_label() if hasattr(coll, "get_label") else ""
+
+    if scitex_id:
+        artist["id"] = scitex_id
+    elif label and not label.startswith("_"):
+        artist["id"] = label
+    else:
+        artist["id"] = f"linecollection_{index}"
+
+    artist["mark"] = "line"
+
+    # Determine role
+    if ctx.plot_type == "bar" or ctx.method == "barh":
+        artist["role"] = "errorbar"
+    elif ctx.plot_type == "stem":
+        artist["role"] = "stem_stem"
+        artist["id"] = "stem_lines"
+    else:
+        artist["role"] = "line_collection"
+
+    artist["legend_included"] = False
+    artist["zorder"] = coll.get_zorder()
+
+    # Backend layer
+    backend = {
+        "name": "matplotlib",
+        "artist_class": type(coll).__name__,
+        "props": {},
+    }
+
+    try:
+        colors = coll.get_colors()
+        if len(colors) > 0:
+            backend["props"]["color"] = color_to_hex(colors[0])
+    except (ValueError, TypeError, IndexError):
+        pass
+
+    try:
+        linewidths = coll.get_linewidths()
+        if len(linewidths) > 0:
+            backend["props"]["linewidth_pt"] = float(linewidths[0])
+    except (ValueError, TypeError, IndexError):
+        pass
+
+    artist["backend"] = backend
+
+    # Data reference for errorbar/stem
+    if artist["role"] == "errorbar":
+        _add_errorbar_data_ref(ctx, artist)
+    elif artist["role"] == "stem_stem":
+        _add_stem_data_ref(ctx, artist)
+
+    return artist
+
+
+def _add_errorbar_data_ref(ctx: ExtractionContext, artist: dict) -> None:
+    """Add data_ref for errorbar LineCollection."""
+    from .._csv import _get_csv_column_names
+
+    errorbar_trace_id = None
+    error_var = "yerr" if ctx.method == "bar" else "xerr"
+
+    if hasattr(ctx.ax_for_detection, "history"):
+        for record in ctx.ax_for_detection.history.values():
+            if isinstance(record, tuple) and len(record) >= 2:
+                method_name = record[1]
+                if method_name in ("bar", "barh"):
+                    errorbar_trace_id = record[0]
+                    break
+
+    if errorbar_trace_id:
+        base_ref = _get_csv_column_names(errorbar_trace_id, ctx.ax_row, ctx.ax_col)
+        artist["data_ref"] = {
+            "x": base_ref.get("x"),
+            "y": base_ref.get("y"),
+            error_var: f"ax-row-{ctx.ax_row}-col-{ctx.ax_col}_trace-id-{errorbar_trace_id}_variable-{error_var}",
+        }
+
+
+def _add_stem_data_ref(ctx: ExtractionContext, artist: dict) -> None:
+    """Add data_ref for stem LineCollection."""
+    from .._csv import _get_csv_column_names
+
+    if hasattr(ctx.ax_for_detection, "history"):
+        for record in ctx.ax_for_detection.history.values():
+            if isinstance(record, tuple) and len(record) >= 2:
+                method_name = record[1]
+                if method_name == "stem":
+                    stem_trace_id = record[0]
+                    artist["data_ref"] = _get_csv_column_names(
+                        stem_trace_id, ctx.ax_row, ctx.ax_col
+                    )
+                    break
+
+
+# EOF