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

scitex/plt/utils/_metadata/_detect.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_metadata/_detect.py
+
+"""
+Plot type detection from axes content.
+
+Detects the primary plot type by analyzing scitex history and matplotlib
+artist content.
+"""
+
+from typing import Optional, Tuple
+
+
+def _detect_plot_type(ax) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Detect the primary plot type and method from axes content.
+
+    Checks for:
+    - Lines -> "line"
+    - Scatter collections -> "scatter"
+    - Bar containers -> "bar"
+    - Patches (histogram) -> "hist"
+    - Box plot -> "boxplot"
+    - Violin plot -> "violin"
+    - Image -> "image"
+    - Contour -> "contour"
+    - KDE -> "kde"
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to analyze
+
+    Returns
+    -------
+    tuple
+        (plot_type, method) where method is the actual plotting function used,
+        or (None, None) if unclear
+    """
+    # Check scitex history FIRST (most reliable for scitex plots)
+    result = _detect_from_history(ax)
+    if result[0] is not None:
+        return result
+
+    # Check for images (takes priority)
+    if len(ax.images) > 0:
+        return "image", "imshow"
+
+    # Check for 2D density plots (hist2d, hexbin)
+    result = _detect_2d_density(ax)
+    if result[0] is not None:
+        return result
+
+    # Check for contours
+    result = _detect_contours(ax)
+    if result[0] is not None:
+        return result
+
+    # Check for bar plots and containers
+    result = _detect_bars(ax)
+    if result[0] is not None:
+        return result
+
+    # Check for patches (histogram, violin, pie)
+    result = _detect_patches(ax)
+    if result[0] is not None:
+        return result
+
+    # Check for scatter plots (PathCollection)
+    result = _detect_scatter(ax)
+    if result[0] is not None:
+        return result
+
+    # Check for line plots
+    result = _detect_lines(ax)
+    if result[0] is not None:
+        return result
+
+    return None, None
+
+
+def _detect_from_history(ax) -> Tuple[Optional[str], Optional[str]]:
+    """Detect plot type from scitex history."""
+    if not hasattr(ax, "history") or len(ax.history) == 0:
+        return None, None
+
+    # Method to (plot_type, method) mapping
+    method_map = {
+        "stx_heatmap": ("heatmap", "stx_heatmap"),
+        "stx_kde": ("kde", "stx_kde"),
+        "stx_ecdf": ("ecdf", "stx_ecdf"),
+        "stx_violin": ("violin", "stx_violin"),
+        "stx_box": ("boxplot", "stx_box"),
+        "boxplot": ("boxplot", "boxplot"),
+        "stx_line": ("line", "stx_line"),
+        "plot_scatter": ("scatter", "plot_scatter"),
+        "stx_mean_std": ("line", "stx_mean_std"),
+        "stx_mean_ci": ("line", "stx_mean_ci"),
+        "stx_median_iqr": ("line", "stx_median_iqr"),
+        "stx_shaded_line": ("line", "stx_shaded_line"),
+        "sns_boxplot": ("boxplot", "sns_boxplot"),
+        "sns_violinplot": ("violin", "sns_violinplot"),
+        "sns_scatterplot": ("scatter", "sns_scatterplot"),
+        "sns_lineplot": ("line", "sns_lineplot"),
+        "sns_histplot": ("hist", "sns_histplot"),
+        "sns_barplot": ("bar", "sns_barplot"),
+        "sns_stripplot": ("scatter", "sns_stripplot"),
+        "sns_kdeplot": ("kde", "sns_kdeplot"),
+        "scatter": ("scatter", "scatter"),
+        "bar": ("bar", "bar"),
+        "barh": ("bar", "barh"),
+        "hist": ("hist", "hist"),
+        "hist2d": ("hist2d", "hist2d"),
+        "hexbin": ("hexbin", "hexbin"),
+        "violinplot": ("violin", "violinplot"),
+        "errorbar": ("errorbar", "errorbar"),
+        "fill_between": ("fill", "fill_between"),
+        "fill_betweenx": ("fill", "fill_betweenx"),
+        "imshow": ("image", "imshow"),
+        "matshow": ("image", "matshow"),
+        "contour": ("contour", "contour"),
+        "contourf": ("contour", "contourf"),
+        "stem": ("stem", "stem"),
+        "step": ("step", "step"),
+        "pie": ("pie", "pie"),
+        "quiver": ("quiver", "quiver"),
+        "streamplot": ("stream", "streamplot"),
+        "plot": ("line", "plot"),
+    }
+
+    # Get all methods from history
+    for record in ax.history.values():
+        if isinstance(record, tuple) and len(record) >= 2:
+            method = record[1]
+            if method in method_map:
+                return method_map[method]
+
+    return None, None
+
+
+def _detect_2d_density(ax) -> Tuple[Optional[str], Optional[str]]:
+    """Detect 2D density plots (hist2d, hexbin)."""
+    if not hasattr(ax, "collections"):
+        return None, None
+
+    for coll in ax.collections:
+        coll_type = type(coll).__name__
+        if "QuadMesh" in coll_type:
+            return "hist2d", "hist2d"
+        if "PolyCollection" in coll_type and hasattr(coll, "get_array"):
+            arr = coll.get_array()
+            if arr is not None and len(arr) > 0:
+                return "hexbin", "hexbin"
+
+    return None, None
+
+
+def _detect_contours(ax) -> Tuple[Optional[str], Optional[str]]:
+    """Detect contour plots."""
+    if not hasattr(ax, "collections"):
+        return None, None
+
+    for coll in ax.collections:
+        if "Contour" in type(coll).__name__:
+            return "contour", "contour"
+
+    return None, None
+
+
+def _detect_bars(ax) -> Tuple[Optional[str], Optional[str]]:
+    """Detect bar and boxplots from containers."""
+    if len(ax.containers) == 0:
+        return None, None
+
+    if any("boxplot" in str(type(c)).lower() for c in ax.containers):
+        return "boxplot", "boxplot"
+
+    return "bar", "bar"
+
+
+def _detect_patches(ax) -> Tuple[Optional[str], Optional[str]]:
+    """Detect histogram, violin, pie from patches."""
+    if len(ax.patches) == 0:
+        return None, None
+
+    # Check for pie chart (Wedge patches)
+    if any("Wedge" in type(p).__name__ for p in ax.patches):
+        return "pie", "pie"
+
+    # If there are many rectangular patches, likely histogram
+    if len(ax.patches) > 5:
+        return "hist", "hist"
+
+    # Check for violin plot
+    if any("Poly" in type(p).__name__ for p in ax.patches):
+        return "violin", "violinplot"
+
+    return None, None
+
+
+def _detect_scatter(ax) -> Tuple[Optional[str], Optional[str]]:
+    """Detect scatter plots from PathCollection."""
+    if not hasattr(ax, "collections") or len(ax.collections) == 0:
+        return None, None
+
+    for coll in ax.collections:
+        if "PathCollection" in type(coll).__name__:
+            return "scatter", "scatter"
+
+    return None, None
+
+
+def _detect_lines(ax) -> Tuple[Optional[str], Optional[str]]:
+    """Detect line and errorbar plots."""
+    if len(ax.lines) == 0:
+        return None, None
+
+    if any(hasattr(line, "_mpl_error") for line in ax.lines):
+        return "errorbar", "errorbar"
+
+    return "line", "plot"
+
+
+# EOF

scitex/plt/utils/_metadata/_legend.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_metadata/_legend.py
+
+"""
+Legend extraction utilities for figure metadata.
+
+Extracts legend information including handles and artist references.
+"""
+
+from typing import Optional
+
+
+def _extract_legend_info(ax) -> Optional[dict]:
+    """
+    Extract legend information from axes.
+
+    Uses matplotlib terminology for legend properties.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to extract legend from
+
+    Returns
+    -------
+    dict or None
+        Legend info dictionary with matplotlib properties, or None if no legend
+    """
+    legend = ax.get_legend()
+    if legend is None:
+        return None
+
+    legend_info = {
+        "visible": legend.get_visible(),
+        "loc": legend._loc if hasattr(legend, "_loc") else "best",
+        "frameon": legend.get_frame_on() if hasattr(legend, "get_frame_on") else True,
+    }
+
+    # ncol - number of columns
+    if hasattr(legend, "_ncols"):
+        legend_info["ncol"] = legend._ncols
+    elif hasattr(legend, "_ncol"):
+        legend_info["ncol"] = legend._ncol
+
+    # Extract legend handles with artist references
+    handles = _extract_legend_handles(ax, legend)
+    if handles:
+        legend_info["handles"] = handles
+
+    return legend_info
+
+
+def _extract_legend_handles(ax, legend) -> list:
+    """Extract legend handles with artist references."""
+    handles = []
+    texts = legend.get_texts()
+    legend_handles = legend.legend_handles if hasattr(legend, "legend_handles") else []
+
+    # Get the raw matplotlib axes for accessing lines to match IDs
+    mpl_ax = ax._axis_mpl if hasattr(ax, "_axis_mpl") else ax
+
+    for i, text in enumerate(texts):
+        label_text = text.get_text()
+        handle_entry = {"label": label_text}
+
+        # Try to get artist_id from corresponding handle
+        artist_id = None
+        if i < len(legend_handles):
+            handle = legend_handles[i]
+            if hasattr(handle, "_scitex_id"):
+                artist_id = handle._scitex_id
+
+        # Fallback: find matching artist by label in axes artists
+        if artist_id is None:
+            artist_id = _find_artist_id_by_label(mpl_ax, label_text)
+
+        if artist_id:
+            handle_entry["artist_id"] = artist_id
+
+        handles.append(handle_entry)
+
+    return handles
+
+
+def _find_artist_id_by_label(mpl_ax, label_text: str) -> Optional[str]:
+    """Find artist ID by matching label in axes artists."""
+    # Check lines
+    for line in mpl_ax.lines:
+        line_label = line.get_label()
+        if line_label == label_text:
+            if hasattr(line, "_scitex_id"):
+                return line._scitex_id
+            elif not line_label.startswith("_"):
+                return line_label
+
+    # Check collections (scatter)
+    for coll in mpl_ax.collections:
+        coll_label = coll.get_label() if hasattr(coll, "get_label") else ""
+        if coll_label == label_text:
+            if hasattr(coll, "_scitex_id"):
+                return coll._scitex_id
+            elif coll_label and not coll_label.startswith("_"):
+                return coll_label
+
+    # Check patches (bar/hist/pie)
+    for patch in mpl_ax.patches:
+        patch_label = patch.get_label() if hasattr(patch, "get_label") else ""
+        if patch_label == label_text:
+            if hasattr(patch, "_scitex_id"):
+                return patch._scitex_id
+            elif patch_label and not patch_label.startswith("_"):
+                return patch_label
+
+    # Check images (imshow)
+    for img in mpl_ax.images:
+        img_label = img.get_label() if hasattr(img, "get_label") else ""
+        if img_label == label_text:
+            if hasattr(img, "_scitex_id"):
+                return img._scitex_id
+            elif img_label and not img_label.startswith("_"):
+                return img_label
+
+    return None
+
+
+# EOF

scitex/plt/utils/_metadata/_rounding.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_metadata/_rounding.py
+
+"""
+Rounding utilities for figure metadata.
+
+Provides precision-controlled rounding for various measurement types
+(mm, inch, position, etc.) to ensure consistent JSON output.
+"""
+
+from typing import List, Union
+
+# Precision settings for JSON output
+PRECISION = {
+    "mm": 2,  # Millimeters: 0.01mm precision (10 microns)
+    "inch": 3,  # Inches: 0.001 inch precision
+    "position": 3,  # Normalized position: 0.001 precision
+    "lim": 2,  # Axis limits: 2 decimal places
+    "linewidth": 2,  # Line widths: 0.01 precision
+}
+
+
+class FixedFloat:
+    """
+    A float wrapper that preserves fixed decimal places in JSON output.
+
+    Example: FixedFloat(0.25, 3) -> "0.250" in JSON
+    """
+
+    def __init__(self, value: float, precision: int):
+        self.value = round(value, precision)
+        self.precision = precision
+
+    def __repr__(self):
+        return f"{self.value:.{self.precision}f}"
+
+    def __float__(self):
+        return self.value
+
+
+def _round_value(
+    value: Union[float, int], precision: int, fixed: bool = False
+) -> Union[float, int, "FixedFloat"]:
+    """
+    Round a single value to specified precision.
+
+    Parameters
+    ----------
+    value : float or int
+        Value to round
+    precision : int
+        Number of decimal places
+    fixed : bool
+        If True, return FixedFloat with fixed decimal places (e.g., 0.250)
+        If False, return float (e.g., 0.25)
+    """
+    if isinstance(value, int):
+        if fixed:
+            return FixedFloat(float(value), precision)
+        return value
+    if isinstance(value, float):
+        if fixed:
+            return FixedFloat(value, precision)
+        return round(value, precision)
+    return value
+
+
+def _round_list(values: List, precision: int, fixed: bool = False) -> List:
+    """Round all values in a list."""
+    return [_round_value(v, precision, fixed) for v in values]
+
+
+def _round_dict(d: dict, precision_map: dict = None) -> dict:
+    """
+    Round all float values in a dict based on key-specific precision.
+
+    Parameters
+    ----------
+    d : dict
+        Dictionary to process
+    precision_map : dict, optional
+        Mapping of key patterns to precision values.
+        Default uses PRECISION settings based on key names.
+    """
+    if precision_map is None:
+        precision_map = {}
+
+    result = {}
+    for key, value in d.items():
+        # Determine precision based on key name
+        if "mm" in key.lower():
+            prec = PRECISION["mm"]
+        elif "inch" in key.lower():
+            prec = PRECISION["inch"]
+        elif "position" in key.lower() or key in ("left", "bottom", "right", "top"):
+            prec = PRECISION["position"]
+        elif "lim" in key.lower():
+            prec = PRECISION["lim"]
+        elif "width" in key.lower() and "line" in key.lower():
+            prec = PRECISION["linewidth"]
+        else:
+            prec = precision_map.get(key, 3)  # Default 3 decimals
+
+        if isinstance(value, dict):
+            result[key] = _round_dict(value, precision_map)
+        elif isinstance(value, list):
+            result[key] = _round_list(value, prec)
+        elif isinstance(value, float):
+            result[key] = _round_value(value, prec)
+        else:
+            result[key] = value
+
+    return result
+
+
+# EOF

scitex/plt/utils/_metadata/_verification.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_metadata/_verification.py
+
+"""
+CSV/JSON consistency verification for figure metadata.
+
+Provides functions to verify that exported CSV data matches
+the JSON metadata declarations.
+"""
+
+
+
+def assert_csv_json_consistency(csv_path: str, json_path: str = None) -> None:
+    """
+    Assert that CSV data file and its JSON metadata are consistent.
+
+    Raises AssertionError if the column names don't match.
+
+    Parameters
+    ----------
+    csv_path : str
+        Path to the CSV data file
+    json_path : str, optional
+        Path to the JSON metadata file. If not provided, assumes
+        the JSON is at the same location with .json extension.
+
+    Raises
+    ------
+    AssertionError
+        If CSV and JSON column names don't match
+    FileNotFoundError
+        If CSV or JSON files don't exist
+
+    Examples
+    --------
+    >>> assert_csv_json_consistency('/tmp/plot.csv')  # Passes silently if valid
+    >>> # Or use in tests:
+    >>> try:
+    ...     assert_csv_json_consistency('/tmp/plot.csv')
+    ... except AssertionError as e:
+    ...     print(f"Validation failed: {e}")
+    """
+    result = verify_csv_json_consistency(csv_path, json_path)
+
+    if result["errors"]:
+        raise FileNotFoundError("\n".join(result["errors"]))
+
+    if not result["valid"]:
+        msg_parts = ["CSV/JSON consistency check failed:"]
+        if result["missing_in_csv"]:
+            msg_parts.append(
+                f"  columns_actual missing in CSV: {result['missing_in_csv']}"
+            )
+        if result["extra_in_csv"]:
+            msg_parts.append(f"  Extra columns in CSV: {result['extra_in_csv']}")
+        if result.get("data_ref_missing"):
+            msg_parts.append(
+                f"  data_ref columns missing in CSV: {result['data_ref_missing']}"
+            )
+        raise AssertionError("\n".join(msg_parts))
+
+
+def verify_csv_json_consistency(csv_path: str, json_path: str = None) -> dict:
+    """
+    Verify consistency between CSV data file and its JSON metadata.
+
+    This function checks that:
+    1. Column names in the CSV file match those declared in JSON's columns_actual
+    2. Artist data_ref values in JSON match actual CSV column names
+
+    Parameters
+    ----------
+    csv_path : str
+        Path to the CSV data file
+    json_path : str, optional
+        Path to the JSON metadata file. If not provided, assumes
+        the JSON is at the same location with .json extension.
+
+    Returns
+    -------
+    dict
+        Verification result with keys:
+        - 'valid': bool - True if CSV and JSON are consistent
+        - 'csv_columns': list - Column names found in CSV
+        - 'json_columns': list - Column names declared in JSON
+        - 'data_ref_columns': list - Column names from artist data_ref
+        - 'missing_in_csv': list - Columns in JSON but not in CSV
+        - 'extra_in_csv': list - Columns in CSV but not in JSON
+        - 'data_ref_missing': list - data_ref columns not found in CSV
+        - 'errors': list - Any error messages
+
+    Examples
+    --------
+    >>> result = verify_csv_json_consistency('/tmp/plot.csv')
+    >>> print(result['valid'])
+    True
+    >>> print(result['missing_in_csv'])
+    []
+    """
+    import json
+    import os
+
+    import pandas as pd
+
+    result = {
+        "valid": False,
+        "csv_columns": [],
+        "json_columns": [],
+        "data_ref_columns": [],
+        "missing_in_csv": [],
+        "extra_in_csv": [],
+        "data_ref_missing": [],
+        "errors": [],
+    }
+
+    # Determine JSON path
+    if json_path is None:
+        base, _ = os.path.splitext(csv_path)
+        json_path = base + ".json"
+
+    # Check files exist
+    if not os.path.exists(csv_path):
+        result["errors"].append(f"CSV file not found: {csv_path}")
+        return result
+    if not os.path.exists(json_path):
+        result["errors"].append(f"JSON file not found: {json_path}")
+        return result
+
+    try:
+        # Read CSV columns
+        df = pd.read_csv(csv_path, nrows=0)  # Just read header
+        csv_columns = list(df.columns)
+        result["csv_columns"] = csv_columns
+    except Exception as e:
+        result["errors"].append(f"Error reading CSV: {e}")
+        return result
+
+    try:
+        # Read JSON metadata
+        with open(json_path) as f:
+            metadata = json.load(f)
+
+        # Get columns_actual from data section
+        json_columns = []
+        if "data" in metadata and "columns_actual" in metadata["data"]:
+            json_columns = metadata["data"]["columns_actual"]
+        result["json_columns"] = json_columns
+
+        # Extract data_ref columns from artists
+        data_ref_columns = _extract_data_ref_columns(metadata)
+        result["data_ref_columns"] = data_ref_columns
+
+    except Exception as e:
+        result["errors"].append(f"Error reading JSON: {e}")
+        return result
+
+    # Compare columns_actual with CSV
+    csv_set = set(csv_columns)
+    json_set = set(json_columns)
+
+    result["missing_in_csv"] = list(json_set - csv_set)
+    result["extra_in_csv"] = list(csv_set - json_set)
+
+    # Check data_ref columns exist in CSV (if there are any)
+    if data_ref_columns:
+        data_ref_set = set(data_ref_columns)
+        result["data_ref_missing"] = list(data_ref_set - csv_set)
+
+    # Valid only if columns_actual matches AND data_ref columns are found
+    result["valid"] = (
+        len(result["missing_in_csv"]) == 0
+        and len(result["extra_in_csv"]) == 0
+        and len(result["data_ref_missing"]) == 0
+    )
+
+    return result
+
+
+def _extract_data_ref_columns(metadata: dict) -> list:
+    """
+    Extract data_ref column names from metadata.
+
+    Skip 'derived_from' key as it contains descriptive text, not CSV column names.
+    Also skip 'row_index' as it's a numeric index, not a column name.
+    """
+    data_ref_columns = []
+    skip_keys = {"derived_from", "row_index"}
+
+    if "axes" in metadata:
+        for ax_key, ax_data in metadata["axes"].items():
+            if "artists" in ax_data:
+                for artist in ax_data["artists"]:
+                    if "data_ref" in artist:
+                        for key, val in artist["data_ref"].items():
+                            if key not in skip_keys and isinstance(val, str):
+                                data_ref_columns.append(val)
+
+    return data_ref_columns
+
+
+# EOF

scitex/schema/README.md

@@ -1,7 +1,7 @@
 <!-- ---
 !-- Timestamp: 2025-12-09 20:40:40
 !-- Author: ywatanabe
-!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/schema/README.md
+!-- File: /home/ywatanabe/proj/scitex-python/src/scitex/schema/README.md
 !-- --- -->
 
 # SciTeX Schema Module