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

scitex/plt/utils/metadata/_collection_artists.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_collection_artists.py
+
+"""
+Collection artist extraction utilities.
+
+This module provides functions to extract PathCollection (scatter), QuadMesh (hist2d),
+PolyCollection (hexbin/violin), and other collection artists from matplotlib axes.
+"""
+
+import matplotlib.colors as mcolors
+from ._label_parsing import _get_csv_column_names
+
+
+def _extract_scatter_artists(mpl_ax, ax_row, ax_col):
+    """
+    Extract PathCollection artists (scatter points).
+
+    Parameters
+    ----------
+    mpl_ax : matplotlib.axes.Axes
+        Raw matplotlib axes
+    ax_row : int
+        Row position in grid
+    ax_col : int
+        Column position in grid
+
+    Returns
+    -------
+    list
+        List of artist dictionaries
+    """
+    artists = []
+
+    for i, coll in enumerate(mpl_ax.collections):
+        if "PathCollection" not in type(coll).__name__:
+            continue
+
+        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_{i}"
+
+        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"] = mcolors.to_hex(facecolors[0], keep_alpha=False)
+        except (ValueError, TypeError, IndexError):
+            pass
+
+        try:
+            edgecolors = coll.get_edgecolor()
+            if len(edgecolors) > 0:
+                backend["props"]["edgecolor"] = mcolors.to_hex(edgecolors[0], keep_alpha=False)
+        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_ref
+        artist_id = artist.get("id", str(i))
+        artist["data_ref"] = _get_csv_column_names(artist_id, ax_row, ax_col)
+
+        artists.append(artist)
+
+    return artists
+
+
+def _extract_hist2d_hexbin_artists(mpl_ax, ax_for_detection, plot_type):
+    """
+    Extract QuadMesh (hist2d) and PolyCollection (hexbin) artists.
+
+    Parameters
+    ----------
+    mpl_ax : matplotlib.axes.Axes
+        Raw matplotlib axes
+    ax_for_detection : axes wrapper
+        Axes wrapper with history
+    plot_type : str
+        Detected plot type
+
+    Returns
+    -------
+    list
+        List of artist dictionaries
+    """
+    artists = []
+
+    for i, coll in enumerate(mpl_ax.collections):
+        coll_type = type(coll).__name__
+
+        if coll_type == "QuadMesh":
+            artist = {}
+            artist["id"] = f"hist2d_{i}"
+            artist["mark"] = "heatmap"
+            artist["role"] = "hist2d"
+            artist["legend_included"] = False
+            artist["zorder"] = coll.get_zorder()
+
+            # Backend layer
+            backend = {
+                "name": "matplotlib",
+                "artist_class": coll_type,
+                "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
+
+            # Extract hist2d result data
+            try:
+                arr = coll.get_array()
+                if arr is not None and len(arr) > 0:
+                    import numpy as np
+                    coords = coll.get_coordinates()
+                    if coords is not None and len(coords) > 0:
+                        n_ybins = coords.shape[0] - 1
+                        n_xbins = coords.shape[1] - 1
+                        xedges = coords[0, :, 0]
+                        yedges = coords[:, 0, 1]
+
+                        artist["result"] = {
+                            "H_shape": [n_ybins, n_xbins],
+                            "n_xbins": int(n_xbins),
+                            "n_ybins": int(n_ybins),
+                            "xedges_range": [float(xedges[0]), float(xedges[-1])],
+                            "yedges_range": [float(yedges[0]), float(yedges[-1])],
+                            "count_range": [float(arr.min()), float(arr.max())],
+                            "total_count": int(arr.sum()),
+                        }
+            except (IndexError, TypeError, AttributeError, ValueError):
+                pass
+
+            artists.append(artist)
+
+        elif coll_type == "PolyCollection":
+            arr = coll.get_array() if hasattr(coll, "get_array") else None
+
+            # Check if this is hexbin
+            if arr is not None and len(arr) > 0 and plot_type == "hexbin":
+                artist = {}
+                artist["id"] = f"hexbin_{i}"
+                artist["mark"] = "heatmap"
+                artist["role"] = "hexbin"
+                artist["legend_included"] = False
+                artist["zorder"] = coll.get_zorder()
+
+                # Backend layer
+                backend = {
+                    "name": "matplotlib",
+                    "artist_class": coll_type,
+                    "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
+
+                # Add hexbin 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
+
+                artists.append(artist)
+
+    return artists
+
+
+def _extract_violin_body_artists(mpl_ax, plot_type):
+    """
+    Extract violin body (PolyCollection) artists.
+
+    Parameters
+    ----------
+    mpl_ax : matplotlib.axes.Axes
+        Raw matplotlib axes
+    plot_type : str
+        Detected plot type
+
+    Returns
+    -------
+    list
+        List of artist dictionaries
+    """
+    artists = []
+
+    if plot_type != "violin":
+        return artists
+
+    for i, coll in enumerate(mpl_ax.collections):
+        coll_type = type(coll).__name__
+
+        if coll_type == "PolyCollection" or (coll_type == "FillBetweenPolyCollection"):
+            # Check if this is a violin body (no array data)
+            arr = coll.get_array() if hasattr(coll, "get_array") else None
+            if arr is not None and len(arr) > 0:
+                continue  # This is hexbin, not violin
+
+            artist = {}
+            scitex_id = getattr(coll, "_scitex_id", None)
+            label = coll.get_label() if hasattr(coll, "get_label") else ""
+
+            if scitex_id:
+                artist["id"] = f"{scitex_id}_body_{i}"
+                artist["group_id"] = scitex_id
+            else:
+                artist["id"] = f"violin_body_{i}"
+
+            artist["mark"] = "polygon"
+            artist["role"] = "violin_body"
+            artist["legend_included"] = False
+            artist["zorder"] = coll.get_zorder()
+
+            # Backend layer
+            backend = {
+                "name": "matplotlib",
+                "artist_class": coll_type,
+                "props": {}
+            }
+            try:
+                facecolors = coll.get_facecolor()
+                if len(facecolors) > 0:
+                    backend["props"]["facecolor"] = mcolors.to_hex(facecolors[0], keep_alpha=False)
+            except (ValueError, TypeError, IndexError):
+                pass
+            try:
+                edgecolors = coll.get_edgecolor()
+                if len(edgecolors) > 0:
+                    backend["props"]["edgecolor"] = mcolors.to_hex(edgecolors[0], keep_alpha=False)
+            except (ValueError, TypeError, IndexError):
+                pass
+
+            artist["backend"] = backend
+            artists.append(artist)
+
+    return artists

scitex/plt/utils/metadata/_core.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_core.py
+
+"""
+Core metadata collection orchestration.
+
+This module provides the main collect_figure_metadata() function that orchestrates
+the collection of all metadata from matplotlib figures and axes.
+"""
+
+from typing import Dict
+import numpy as np
+
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
+# Import sub-modules
+from ._figure_metadata import _initialize_metadata_structure, _collect_figure_metadata
+from ._axes_metadata import _collect_all_axes_metadata
+from ._dimensions import _collect_grid_info, _extract_figure_dimensions
+from ._style_parsing import _restructure_style, _collect_style_metadata, _extract_mode_and_method
+from ._plot_content import _detect_plot_type, _extract_artists, _extract_legend_info
+from ._data_linkage import _compute_csv_hash
+from ._precision import _round_metadata
+
+
+def collect_figure_metadata(fig, ax=None) -> Dict:
+    """
+    Collect all metadata from figure and axes for embedding in saved images.
+
+    This function automatically extracts:
+    - Software versions (scitex, matplotlib)
+    - Timestamp
+    - Figure UUID (unique identifier)
+    - Figure/axes dimensions (mm, inch, px)
+    - DPI settings
+    - Margins
+    - Styling parameters (if available)
+    - Mode (display/publication)
+    - Creation method
+    - Plot type and axes information
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        Figure to collect metadata from
+    ax : matplotlib.axes.Axes, optional
+        Primary axes to collect dimension info from.
+        If not provided, uses first axes in figure.
+
+    Returns
+    -------
+    dict
+        Complete metadata dictionary ready for embedding via scitex.io.embed_metadata()
+
+    Examples
+    --------
+    >>> from scitex.plt.utils import create_axes_with_size_mm, collect_figure_metadata
+    >>> fig, ax = create_axes_with_size_mm(30, 21, mode='publication')
+    >>> ax.plot(x, y)
+    >>> metadata = collect_figure_metadata(fig, ax)
+    >>> print(metadata['figure']['size_mm'])
+    [30.00, 21.00]
+
+    Notes
+    -----
+    This function is automatically called by FigWrapper.savefig() when
+    embed_metadata=True (the default). You typically don't need to call it manually.
+
+    The collected metadata enables:
+    - Reproducing exact figure dimensions later
+    - Matching styling across multiple figures
+    - Documenting figure provenance
+    - Debugging dimension/DPI issues
+    """
+    # Initialize base metadata structure
+    metadata = _initialize_metadata_structure()
+
+    # Collect grid information
+    all_axes, grid_shape = _collect_grid_info(ax) if ax is not None else ([], (1, 1))
+
+    # Fallback to figure axes if no axes provided
+    if not all_axes and hasattr(fig, "axes") and len(fig.axes) > 0:
+        for idx, ax_item in enumerate(fig.axes):
+            all_axes.append((ax_item, 0, idx))
+
+    # Collect figure-level metadata
+    if all_axes:
+        try:
+            metadata["figure"] = _extract_figure_dimensions(fig)
+        except Exception as e:
+            logger.warning(f"Could not extract figure dimension info: {e}")
+
+    # Collect axes metadata
+    if all_axes:
+        try:
+            metadata["axes"] = _collect_all_axes_metadata(all_axes, fig, grid_shape)
+        except Exception as e:
+            logger.warning(f"Could not extract axes metadata: {e}")
+
+    # Extract style metadata
+    try:
+        style_meta = _collect_style_metadata(fig, ax)
+        if style_meta:
+            metadata["style"] = style_meta
+    except Exception:
+        pass  # Style is optional
+
+    # Extract mode and creation method
+    try:
+        mode, creation_method = _extract_mode_and_method(fig, ax)
+        if mode:
+            if "figure" not in metadata:
+                metadata["figure"] = {}
+            metadata["figure"]["mode"] = mode
+        if creation_method:
+            metadata["runtime"]["created_with"] = creation_method
+    except Exception:
+        pass  # Mode/method are optional
+
+    # Extract font information
+    try:
+        from .._get_actual_font import get_actual_font_name
+        actual_font = get_actual_font_name()
+        
+        if "style" in metadata:
+            if "global" not in metadata["style"]:
+                metadata["style"]["global"] = {}
+            if "fonts" not in metadata["style"]["global"]:
+                metadata["style"]["global"]["fonts"] = {}
+            
+            requested_font = metadata["style"]["global"]["fonts"].get("family", "Arial")
+            if "family" in metadata["style"]["global"]["fonts"]:
+                del metadata["style"]["global"]["fonts"]["family"]
+            metadata["style"]["global"]["fonts"]["family_requested"] = requested_font
+            metadata["style"]["global"]["fonts"]["family_actual"] = actual_font
+            
+            if requested_font != actual_font:
+                logger.warning(
+                    f"Font mismatch: Requested '{requested_font}' but using '{actual_font}'"
+                )
+        else:
+            metadata["runtime"]["font_family_actual"] = actual_font
+    except Exception:
+        pass  # Font detection is optional
+
+    # Extract plot content
+    if ax is not None:
+        try:
+            # Get primary axes for plot info
+            primary_ax = ax
+            if hasattr(ax, "_axes_scitex"):
+                axes_array = ax._axes_scitex
+                if isinstance(axes_array, np.ndarray) and axes_array.size > 0:
+                    primary_ax = axes_array.flat[0]
+                else:
+                    primary_ax = axes_array
+
+            # Find axes with history for plot type detection
+            ax_for_history = primary_ax
+            if not hasattr(primary_ax, 'history'):
+                if hasattr(primary_ax, '_scitex_wrapper'):
+                    ax_for_history = primary_ax._scitex_wrapper
+
+            # Extract plot info
+            plot_info = {}
+            
+            # Get axes position
+            ax_row, ax_col = 0, 0
+            if hasattr(primary_ax, "_scitex_metadata") and "position_in_grid" in primary_ax._scitex_metadata:
+                pos = primary_ax._scitex_metadata["position_in_grid"]
+                ax_row, ax_col = pos[0], pos[1]
+            plot_info["ax_id"] = f"ax_{ax_row:02d}_{ax_col:02d}"
+
+            # Extract title
+            ax_mpl = primary_ax._axis_mpl if hasattr(primary_ax, '_axis_mpl') else primary_ax
+            title = ax_mpl.get_title()
+            if title:
+                plot_info["title"] = title
+
+            # Detect plot type
+            plot_type, method = _detect_plot_type(ax_for_history)
+            if plot_type:
+                plot_info["type"] = plot_type
+            if method:
+                plot_info["method"] = method
+
+            if plot_info:
+                metadata["plot"] = plot_info
+
+            # Extract data hash
+            try:
+                csv_hash = _compute_csv_hash(ax_for_history)
+                if csv_hash:
+                    metadata["data"] = {"csv_hash": csv_hash}
+            except Exception:
+                pass  # Data hash is optional
+
+        except Exception as e:
+            logger.warning(f"Could not extract plot content: {e}")
+
+    # Apply precision rounding
+    metadata = _round_metadata(metadata)
+
+    return metadata

scitex/plt/utils/metadata/_csv_column_extraction.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_csv_column_extraction.py
+
+"""
+CSV column name extraction from plot history.
+
+This module provides functions to extract CSV column names from scitex history
+for linking JSON metadata to CSV data files.
+"""
+
+from typing import List
+
+
+def _extract_csv_columns_from_history(ax) -> list:
+    """
+    Extract CSV column names from scitex history for all plot types.
+
+    This function generates the exact column names that will be produced
+    by export_as_csv(), providing a mapping between JSON metadata and CSV data.
+
+    Parameters
+    ----------
+    ax : AxisWrapper or matplotlib.axes.Axes
+        The axes to extract CSV column info from
+
+    Returns
+    -------
+    list
+        List of dictionaries containing CSV column mappings for each tracked plot,
+        e.g., [{"id": "boxplot_0", "method": "boxplot", "columns": ["ax_00_boxplot_0_boxplot_0", "ax_00_boxplot_0_boxplot_1"]}]
+    """
+    # 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]
+
+    csv_columns_list = []
+
+    # Check if we have scitex history
+    if not hasattr(ax, "history") or len(ax.history) == 0:
+        return csv_columns_list
+
+    # Iterate through history to extract column names
+    for trace_index, (record_id, record) in enumerate(ax.history.items()):
+        if not isinstance(record, tuple) or len(record) < 4:
+            continue
+
+        id_val, method, tracked_dict, kwargs = record
+
+        # Generate column names
+        columns = _get_csv_columns_for_method_with_index(
+            id_val, method, tracked_dict, kwargs, ax_row, ax_col, trace_index
+        )
+
+        if columns:
+            csv_columns_list.append({
+                "id": id_val,
+                "method": method,
+                "columns": columns,
+            })
+
+    return csv_columns_list
+
+
+def _get_csv_columns_for_method_with_index(
+    id_val, method, tracked_dict, kwargs, ax_row: int, ax_col: int, trace_index: int
+) -> list:
+    """
+    Get CSV column names for a specific plotting method using trace index.
+
+    This function uses the same naming convention as _extract_traces to ensure
+    consistency between plot.traces.csv_columns and data.columns.
+
+    Parameters
+    ----------
+    id_val : str
+        The plot ID (e.g., "sine", "cosine")
+    method : str
+        The plotting method name (e.g., "plot", "scatter")
+    tracked_dict : dict
+        The tracked data dictionary
+    kwargs : dict
+        The keyword arguments passed to the plot
+    ax_row : int
+        Row index of axes in grid
+    ax_col : int
+        Column index of axes in grid
+    trace_index : int
+        Index of this trace (for deduplication)
+
+    Returns
+    -------
+    list
+        List of column names that will be in the CSV
+    """
+    from .._csv_column_naming import get_csv_column_name
+
+    columns = []
+
+    # Use simplified variable names (x, y, bins, counts, etc.)
+    if method in ("plot", "stx_line"):
+        columns = [
+            get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("y", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method in ("scatter", "plot_scatter"):
+        columns = [
+            get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("y", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method in ("bar", "barh"):
+        columns = [
+            get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("height", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method == "hist":
+        columns = [
+            get_csv_column_name("bins", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("counts", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method in ("boxplot", "stx_box"):
+        columns = [
+            get_csv_column_name("data", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method in ("violinplot", "stx_violin"):
+        columns = [
+            get_csv_column_name("data", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method == "errorbar":
+        columns = [
+            get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("y", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("yerr", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method == "fill_between":
+        columns = [
+            get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("y1", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("y2", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method in ("imshow", "stx_heatmap", "stx_image"):
+        columns = [
+            get_csv_column_name("data", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method in ("stx_kde", "stx_ecdf"):
+        columns = [
+            get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("y", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method in ("stx_mean_std", "stx_mean_ci", "stx_median_iqr", "stx_shaded_line"):
+        columns = [
+            get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("y", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("lower", ax_row, ax_col, trace_index=trace_index),
+            get_csv_column_name("upper", ax_row, ax_col, trace_index=trace_index),
+        ]
+    elif method.startswith("sns_"):
+        sns_type = method.replace("sns_", "")
+        if sns_type in ("boxplot", "violinplot"):
+            columns = [
+                get_csv_column_name("data", ax_row, ax_col, trace_index=trace_index),
+            ]
+        elif sns_type in ("scatterplot", "lineplot"):
+            columns = [
+                get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+                get_csv_column_name("y", ax_row, ax_col, trace_index=trace_index),
+            ]
+        elif sns_type == "barplot":
+            columns = [
+                get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+                get_csv_column_name("y", ax_row, ax_col, trace_index=trace_index),
+            ]
+        elif sns_type == "histplot":
+            columns = [
+                get_csv_column_name("bins", ax_row, ax_col, trace_index=trace_index),
+                get_csv_column_name("counts", ax_row, ax_col, trace_index=trace_index),
+            ]
+        elif sns_type == "kdeplot":
+            columns = [
+                get_csv_column_name("x", ax_row, ax_col, trace_index=trace_index),
+                get_csv_column_name("y", ax_row, ax_col, trace_index=trace_index),
+            ]
+
+    return columns