scitex 2.4.3__py3-none-any.whl → 2.7.0__py3-none-any.whl

scitex/plt/utils/_colorbar.py

@@ -47,9 +47,7 @@ def style_colorbar(cbar):
 
     # Style the ticks
     cbar.ax.tick_params(
-        width=line_width,
-        length=tick_length,
-        labelsize=COLORBAR_TICK_FONTSIZE
+        width=line_width, length=tick_length, labelsize=COLORBAR_TICK_FONTSIZE
     )
 
     # Style the colorbar axis spines
@@ -85,9 +83,9 @@ def colorbar(mappable, ax=None, n_ticks=4, **kwargs):
 
     # Set better defaults for colorbar placement
     defaults = {
-        'fraction': 0.046,  # Fraction of axes to use for colorbar
-        'pad': 0.04,        # Padding between axes and colorbar
-        'aspect': 20,       # Aspect ratio of colorbar
+        "fraction": 0.046,  # Fraction of axes to use for colorbar
+        "pad": 0.04,  # Padding between axes and colorbar
+        "aspect": 20,  # Aspect ratio of colorbar
     }
 
     # Update defaults with any user-provided kwargs
@@ -99,7 +97,7 @@ def colorbar(mappable, ax=None, n_ticks=4, **kwargs):
     cbar = plt.colorbar(mappable, ax=ax, **kwargs)
 
     # Limit number of ticks to match main axes style (3-4 ticks)
-    cbar.locator = MaxNLocator(nbins=n_ticks, min_n_ticks=2, prune='both')
+    cbar.locator = MaxNLocator(nbins=n_ticks, min_n_ticks=2, prune="both")
     cbar.update_ticks()
 
     # Apply publication-quality styling
@@ -107,17 +105,17 @@ def colorbar(mappable, ax=None, n_ticks=4, **kwargs):
 
     # If using constrained_layout, ensure the figure updates
     if ax is not None:
-        fig = ax.figure if hasattr(ax, 'figure') else ax[0].figure
-        if hasattr(fig, 'get_constrained_layout') and fig.get_constrained_layout():
+        fig = ax.figure if hasattr(ax, "figure") else ax[0].figure
+        if hasattr(fig, "get_constrained_layout") and fig.get_constrained_layout():
             # Force a layout update
             fig.canvas.draw_idle()
 
     return cbar
 
 
-def add_shared_colorbar(fig, axes, mappable, location='right', **kwargs):
+def add_shared_colorbar(fig, axes, mappable, location="right", **kwargs):
     """Add a single colorbar shared by multiple axes.
-    
+
     Parameters
     ----------
     fig : matplotlib.figure.Figure
@@ -130,22 +128,22 @@ def add_shared_colorbar(fig, axes, mappable, location='right', **kwargs):
         Where to place the colorbar (default: 'right')
     **kwargs : dict
         Additional keyword arguments passed to fig.colorbar
-        
+
     Returns
     -------
     colorbar : matplotlib.colorbar.Colorbar
         The colorbar instance
     """
     defaults = {
-        'shrink': 0.8,      # Shrink colorbar to match axes height
-        'aspect': 30,       # Make it thinner for shared colorbars
+        "shrink": 0.8,  # Shrink colorbar to match axes height
+        "aspect": 30,  # Make it thinner for shared colorbars
     }
-    
+
     # Update defaults with any user-provided kwargs
     for key, value in defaults.items():
         if key not in kwargs:
             kwargs[key] = value
-    
+
     # Create the shared colorbar
     cbar = fig.colorbar(mappable, ax=axes, location=location, **kwargs)
 
@@ -155,4 +153,4 @@ def add_shared_colorbar(fig, axes, mappable, location='right', **kwargs):
     return cbar
 
 
-# EOF
+# EOF

scitex/plt/utils/_configure_mpl.py

@@ -180,9 +180,7 @@ def configure_mpl(
         # Spine width from YAML (converted from mm to pt)
         "axes.linewidth": axes_linewidth,
         # Custom color cycle
-        "axes.prop_cycle": plt.cycler(
-            color=list(RGBA_NORM_FOR_CYCLE.values())
-        ),
+        "axes.prop_cycle": plt.cycler(color=list(RGBA_NORM_FOR_CYCLE.values())),
         # Line width from YAML (converted from mm to pt)
         "lines.linewidth": line_width,
         "lines.markersize": 6.0,
@@ -227,12 +225,8 @@ def configure_mpl(
 
         except Exception as e:
             if verbose:
-                print(
-                    f"⚠️  LaTeX rendering failed, falling back to mathtext: {e}"
-                )
-                print(
-                    "    This may be due to missing LaTeX fonts or Node.js conflicts"
-                )
+                print(f"⚠️  LaTeX rendering failed, falling back to mathtext: {e}")
+                print("    This may be due to missing LaTeX fonts or Node.js conflicts")
 
             # Enhanced fallback to mathtext with better configuration
             mpl_config.update(
@@ -271,7 +265,8 @@ def configure_mpl(
         except Exception:
             # Search for Arial font files and register them
             arial_paths = [
-                f for f in fm.findSystemFonts()
+                f
+                for f in fm.findSystemFonts()
                 if os.path.basename(f).lower().startswith("arial")
             ]
 
@@ -295,7 +290,12 @@ def configure_mpl(
                 {
                     "text.usetex": False,
                     "font.family": "Arial",
-                    "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "Liberation Sans"],
+                    "font.sans-serif": [
+                        "Arial",
+                        "Helvetica",
+                        "DejaVu Sans",
+                        "Liberation Sans",
+                    ],
                     "mathtext.fontset": "dejavusans",
                     "mathtext.default": "regular",
                 }
@@ -306,7 +306,12 @@ def configure_mpl(
                 {
                     "text.usetex": False,
                     "font.family": "sans-serif",
-                    "font.sans-serif": ["Helvetica", "DejaVu Sans", "Liberation Sans", "sans-serif"],
+                    "font.sans-serif": [
+                        "Helvetica",
+                        "DejaVu Sans",
+                        "Liberation Sans",
+                        "sans-serif",
+                    ],
                     "mathtext.fontset": "dejavusans",
                     "mathtext.default": "regular",
                 }
@@ -315,6 +320,7 @@ def configure_mpl(
             # Warn user about missing Arial using scitex.logging
             try:
                 from scitex.logging import getLogger
+
                 logger = getLogger(__name__)
                 logger.warning(
                     "Arial font not found. Using fallback fonts (Helvetica/DejaVu Sans). "
@@ -323,17 +329,19 @@ def configure_mpl(
             except ImportError:
                 # Fallback to warnings if scitex.logging not available
                 import warnings
+
                 warnings.warn(
                     "Arial font not found on system. Using fallback fonts (Helvetica/DejaVu Sans). "
                     "For publication-quality figures with Arial, install Microsoft Core Fonts: "
                     "sudo apt-get install ttf-mscorefonts-installer && fc-cache -fv",
                     UserWarning,
-                    stacklevel=2
+                    stacklevel=2,
                 )
 
         # Suppress matplotlib's own font warnings
         import logging
-        logging.getLogger('matplotlib.font_manager').setLevel(logging.ERROR)
+
+        logging.getLogger("matplotlib.font_manager").setLevel(logging.ERROR)
 
         # Set fallback mode to mathtext
         try:

scitex/plt/utils/_crop.py

@@ -54,10 +54,10 @@ def find_content_area(image_path: str) -> Tuple[int, int, int, int]:
             # Sample background color from corners (more robust than assuming white)
             h, w = img_array.shape[:2]
             corners = [
-                img_array[0, 0],           # top-left
-                img_array[0, w-1],         # top-right
-                img_array[h-1, 0],         # bottom-left
-                img_array[h-1, w-1],       # bottom-right
+                img_array[0, 0],  # top-left
+                img_array[0, w - 1],  # top-right
+                img_array[h - 1, 0],  # bottom-left
+                img_array[h - 1, w - 1],  # bottom-right
             ]
             # Use median of corners as background color (robust to one corner having content)
             bg_color = np.median(corners, axis=0).astype(np.uint8)
@@ -68,7 +68,12 @@ def find_content_area(image_path: str) -> Tuple[int, int, int, int]:
         else:
             # Grayscale: detect background from corners
             h, w = img_array.shape
-            corners = [img_array[0, 0], img_array[0, w-1], img_array[h-1, 0], img_array[h-1, w-1]]
+            corners = [
+                img_array[0, 0],
+                img_array[0, w - 1],
+                img_array[h - 1, 0],
+                img_array[h - 1, w - 1],
+            ]
             bg_value = np.median(corners)
             is_content = np.abs(img_array.astype(np.int16) - bg_value) > 10
 
@@ -91,6 +96,7 @@ def crop(
     margin: int = 12,
     overwrite: bool = False,
     verbose: bool = False,
+    return_offset: bool = False,
 ) -> str:
     """
     Crop a figure image to its content area with a specified margin.
@@ -112,11 +118,16 @@ def crop(
         Whether to overwrite the input file (default: False)
     verbose : bool, optional
         Whether to print detailed information (default: False)
+    return_offset : bool, optional
+        If True, also return the crop offset (left, upper) for metadata adjustment.
+        Default is False.
 
     Returns
     -------
-    str
-        Path to the saved cropped image
+    str or tuple
+        Path to the saved cropped image. If return_offset=True, returns
+        (path, offset_dict) where offset_dict has keys 'left', 'upper', 'right', 'lower'
+        representing the crop boundaries.
 
     Raises
     ------
@@ -150,14 +161,16 @@ def crop(
 
     if verbose:
         print(f"Original image dimensions: {original_width}x{original_height}")
-        if 'dpi' in img.info:
+        if "dpi" in img.info:
             print(f"Original DPI: {img.info['dpi']}")
 
     # Find the content area (returns left, upper, right, lower)
     left, upper, right, lower = find_content_area(input_path)
 
     if verbose:
-        print(f"Content area detected at: left={left}, upper={upper}, right={right}, lower={lower}")
+        print(
+            f"Content area detected at: left={left}, upper={upper}, right={right}, lower={lower}"
+        )
 
     # Calculate the coordinates with margin, clamping to the image boundaries
     left = max(left - margin, 0)
@@ -167,7 +180,7 @@ def crop(
 
     if verbose:
         print(f"Cropping to: left={left}, upper={upper}, right={right}, lower={lower}")
-        print(f"New dimensions: {right-left}x{lower-upper}")
+        print(f"New dimensions: {right - left}x{lower - upper}")
 
     # Crop the image using PIL (lossless operation)
     cropped_img = img.crop((left, upper, right, lower))
@@ -176,17 +189,20 @@ def crop(
     save_kwargs = {}
 
     # Preserve DPI if it exists
-    if 'dpi' in img.info:
-        save_kwargs['dpi'] = img.info['dpi']
+    if "dpi" in img.info:
+        save_kwargs["dpi"] = img.info["dpi"]
 
     ext = os.path.splitext(output_path)[1].lower()
-    if ext in ['.png']:
+    if ext in [".png"]:
         # PNG: lossless compression, preserve all metadata including text chunks
-        save_kwargs['compress_level'] = 0  # No compression for maximum quality and speed
-        save_kwargs['optimize'] = False
+        save_kwargs["compress_level"] = (
+            0  # No compression for maximum quality and speed
+        )
+        save_kwargs["optimize"] = False
 
         # Preserve PNG text chunks (tEXt, zTXt, iTXt) where scitex metadata is stored
         from PIL import PngImagePlugin
+
         pnginfo = PngImagePlugin.PngInfo()
 
         # Copy all text chunks from original image
@@ -197,30 +213,30 @@ def crop(
                 except Exception:
                     pass  # Skip if can't add this chunk
 
-        save_kwargs['pnginfo'] = pnginfo
-    elif ext in ['.jpg', '.jpeg']:
+        save_kwargs["pnginfo"] = pnginfo
+    elif ext in [".jpg", ".jpeg"]:
         # JPEG: maximum quality for daily use (quality=100, no compression artifacts)
-        save_kwargs['quality'] = 100
-        save_kwargs['subsampling'] = 0  # No chroma subsampling (best quality)
-        save_kwargs['optimize'] = False
+        save_kwargs["quality"] = 100
+        save_kwargs["subsampling"] = 0  # No chroma subsampling (best quality)
+        save_kwargs["optimize"] = False
 
         # Preserve EXIF metadata where scitex metadata is stored
         try:
             import piexif
 
             # Try to load existing EXIF data
-            if 'exif' in img.info:
+            if "exif" in img.info:
                 # piexif.load() reads the EXIF bytes
-                exif_dict = piexif.load(img.info['exif'])
+                exif_dict = piexif.load(img.info["exif"])
                 # Re-dump to bytes for saving
                 exif_bytes = piexif.dump(exif_dict)
-                save_kwargs['exif'] = exif_bytes
+                save_kwargs["exif"] = exif_bytes
         except ImportError:
             # piexif not available, try PIL's built-in EXIF
-            if hasattr(img, 'getexif'):
+            if hasattr(img, "getexif"):
                 exif = img.getexif()
                 if exif:
-                    save_kwargs['exif'] = exif
+                    save_kwargs["exif"] = exif
         except Exception:
             # If EXIF reading fails, continue without it
             pass
@@ -230,16 +246,33 @@ def crop(
 
     # Calculate space saved
     final_width, final_height = cropped_img.size
-    area_reduction = 1 - ((final_width * final_height) / (original_width * original_height))
+    area_reduction = 1 - (
+        (final_width * final_height) / (original_width * original_height)
+    )
     area_reduction_pct = area_reduction * 100
 
     if verbose:
         print(f"Image processed: {input_path}")
-        print(f"Size changed from {original_width}x{original_height} to {final_width}x{final_height}")
+        print(
+            f"Size changed from {original_width}x{original_height} to {final_width}x{final_height}"
+        )
         print(f"Saved {area_reduction_pct:.1f}% of the original area")
         if output_path != input_path:
             print(f"Saved to: {output_path}")
 
+    if return_offset:
+        offset = {
+            'left': left,
+            'upper': upper,
+            'right': right,
+            'lower': lower,
+            'original_width': original_width,
+            'original_height': original_height,
+            'new_width': final_width,
+            'new_height': final_height,
+        }
+        return output_path, offset
+
     return output_path
 
 

scitex/plt/utils/_csv_column_naming.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-08
+# File: ./src/scitex/plt/utils/_csv_column_naming.py
+
+"""
+Single source of truth for CSV column naming in scitex.
+
+This module ensures consistent column naming between:
+- CSV export (_export_as_csv)
+- JSON metadata (_collect_figure_metadata)
+- GUI editors (reading CSV data back)
+
+Column naming convention:
+    {domain-name-value}_{domain-name-value}_...
+
+    - Underscore (_) separates different domains
+    - Hyphen (-) within domain name and between name-value
+
+Format:
+    ax-row-{row}-col-{col}_trace-id-{trace_id}_variable-{variable}
+
+Where:
+    - ax-row-{row}-col-{col}: axes position in grid
+    - trace-id-{id}: unique identifier for the trace, which can be:
+        * User-provided id kwarg (e.g., "sine", "my-data")
+        * Generated from label (e.g., "sin-x" from "sin(x)")
+        * Auto-generated index (e.g., "0", "1")
+    - variable-{var}: type of data variable (e.g., "x", "y", "bins", "heights")
+
+Examples:
+    ax-row-0-col-0_trace-id-sine_variable-x       (row 0, col 0, id "sine", x)
+    ax-row-0-col-0_trace-id-sine_variable-y       (row 0, col 0, id "sine", y)
+    ax-row-0-col-1_trace-id-0_variable-x          (row 0, col 1, auto id 0, x)
+    ax-row-1-col-0_trace-id-my-data_variable-bins (row 1, col 0, "my-data", bins)
+"""
+
+__all__ = [
+    "get_csv_column_name",
+    "get_csv_column_prefix",
+    "parse_csv_column_name",
+    "sanitize_trace_id",
+]
+
+
+def sanitize_trace_id(trace_id: str) -> str:
+    """Sanitize trace ID for use in CSV column names.
+
+    Removes or replaces characters that could cause issues in column names.
+    Uses hyphen (-) for word separation within values.
+
+    Parameters
+    ----------
+    trace_id : str
+        Raw trace identifier (label, id kwarg, or generated)
+
+    Returns
+    -------
+    str
+        Sanitized trace ID safe for CSV column names
+
+    Examples
+    --------
+    >>> sanitize_trace_id("sin(x)")
+    'sin-x'
+    >>> sanitize_trace_id("My Data")
+    'my-data'
+    """
+    if not trace_id:
+        return "unnamed"
+
+    # Replace problematic characters with hyphen (word separator within values)
+    sanitized = str(trace_id).lower()
+    result = []
+    for char in sanitized:
+        if char.isalnum():
+            result.append(char)
+        elif char in (" ", "_", "(", ")", "[", "]", "{", "}", "/", "\\", ".", "-"):
+            result.append("-")
+        # Skip other characters
+
+    sanitized = "".join(result)
+
+    # Remove consecutive hyphens
+    while "--" in sanitized:
+        sanitized = sanitized.replace("--", "-")
+
+    # Remove leading/trailing hyphens
+    sanitized = sanitized.strip("-")
+
+    return sanitized if sanitized else "unnamed"
+
+
+def get_csv_column_prefix(
+    ax_row: int = 0, ax_col: int = 0, trace_id: str = None, trace_index: int = None
+) -> str:
+    """Get CSV column prefix for a trace.
+
+    Format: ax-row-{row}-col-{col}_trace-id-{id}_variable-
+    - Underscore (_) separates domains
+    - Hyphen (-) within domain names and between name-value
+
+    Parameters
+    ----------
+    ax_row : int
+        Row position of axes in grid (default: 0)
+    ax_col : int
+        Column position of axes in grid (default: 0)
+    trace_id : str, optional
+        Trace identifier (from label or id kwarg). If None, uses trace_index.
+    trace_index : int, optional
+        Index of trace when no trace_id is provided (default: 0)
+
+    Returns
+    -------
+    str
+        Column prefix like "ax-row-0-col-0_trace-id-sine_variable-"
+
+    Examples
+    --------
+    >>> get_csv_column_prefix(trace_id="sine")
+    'ax-row-0-col-0_trace-id-sine_variable-'
+    >>> get_csv_column_prefix(ax_row=1, ax_col=2, trace_index=0)
+    'ax-row-1-col-2_trace-id-0_variable-'
+    """
+    if trace_id:
+        safe_id = sanitize_trace_id(trace_id)
+    elif trace_index is not None:
+        safe_id = str(trace_index)
+    else:
+        safe_id = "0"
+
+    return f"ax-row-{ax_row}-col-{ax_col}_trace-id-{safe_id}_variable-"
+
+
+def get_csv_column_name(
+    variable: str,
+    ax_row: int = 0,
+    ax_col: int = 0,
+    trace_id: str = None,
+    trace_index: int = None,
+) -> str:
+    """Get full CSV column name for a data field.
+
+    Format: ax-row-{row}-col-{col}_trace-id-{id}_variable-{var}
+    - Underscore (_) separates domains
+    - Hyphen (-) within domain names and between name-value
+
+    Parameters
+    ----------
+    variable : str
+        Variable name (e.g., "x", "y", "bins", "heights")
+    ax_row : int
+        Row position of axes in grid (default: 0)
+    ax_col : int
+        Column position of axes in grid (default: 0)
+    trace_id : str, optional
+        Trace identifier (from label or id kwarg)
+    trace_index : int, optional
+        Index of trace when no trace_id is provided
+
+    Returns
+    -------
+    str
+        Full column name like "ax-row-0-col-0_trace-id-sine_variable-x"
+
+    Examples
+    --------
+    >>> get_csv_column_name("x", trace_id="sin(x)")
+    'ax-row-0-col-0_trace-id-sin-x_variable-x'
+    >>> get_csv_column_name("y", ax_row=1, ax_col=2, trace_index=0)
+    'ax-row-1-col-2_trace-id-0_variable-y'
+    """
+    prefix = get_csv_column_prefix(ax_row, ax_col, trace_id, trace_index)
+    # Variable names are simple (x, y, bins, etc.)
+    safe_variable = variable.lower()
+    return f"{prefix}{safe_variable}"
+
+
+def parse_csv_column_name(column_name: str) -> dict:
+    """Parse CSV column name to extract components.
+
+    Format: ax-row-{row}-col-{col}_trace-id-{id}_variable-{var}
+    - Underscore (_) separates domains
+    - Hyphen (-) within domain names and between name-value
+
+    Parameters
+    ----------
+    column_name : str
+        Full column name (e.g., "ax-row-0-col-0_trace-id-sine_variable-x")
+
+    Returns
+    -------
+    dict
+        Dictionary with keys:
+        - ax_row: int
+        - ax_col: int
+        - trace_id: str
+        - variable: str
+        - valid: bool (True if parsing succeeded)
+
+    Examples
+    --------
+    >>> parse_csv_column_name("ax-row-0-col-0_trace-id-sine_variable-x")
+    {'ax_row': 0, 'ax_col': 0, 'trace_id': 'sine', 'variable': 'x', 'valid': True}
+    >>> parse_csv_column_name("ax-row-1-col-2_trace-id-my-data_variable-bins")
+    {'ax_row': 1, 'ax_col': 2, 'trace_id': 'my-data', 'variable': 'bins', 'valid': True}
+    """
+    result = {
+        "ax_row": 0,
+        "ax_col": 0,
+        "trace_id": "",
+        "variable": "",
+        "valid": False,
+    }
+
+    if not column_name or not column_name.startswith("ax-row-"):
+        return result
+
+    try:
+        # Split by underscore to get domain groups
+        parts = column_name.split("_")
+        # Expected: ["ax-row-0-col-0", "trace-id-sine", "variable-x"]
+
+        for part in parts:
+            if part.startswith("ax-row-"):
+                # Parse ax-row-{row}-col-{col}
+                # Remove "ax-row-" prefix and split by "-col-"
+                rest = part[7:]  # Remove "ax-row-"
+                if "-col-" in rest:
+                    row_str, col_str = rest.split("-col-")
+                    result["ax_row"] = int(row_str)
+                    result["ax_col"] = int(col_str)
+            elif part.startswith("trace-id-"):
+                # Extract trace id (everything after "trace-id-")
+                result["trace_id"] = part[9:]
+            elif part.startswith("variable-"):
+                # Extract variable (everything after "variable-")
+                result["variable"] = part[9:]
+
+        # Validate we got all required fields
+        if result["variable"]:
+            result["valid"] = True
+
+    except (ValueError, IndexError):
+        pass
+
+    return result
+
+
+def get_trace_columns_from_df(
+    df, trace_id: str = None, trace_index: int = None, ax_row: int = 0, ax_col: int = 0
+) -> dict:
+    """Find CSV columns for a specific trace in a DataFrame.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        DataFrame with CSV data
+    trace_id : str, optional
+        Trace identifier to search for
+    trace_index : int, optional
+        Trace index to search for (if trace_id not provided)
+    ax_row : int
+        Row position of axes
+    ax_col : int
+        Column position of axes
+
+    Returns
+    -------
+    dict
+        Dictionary mapping variable names to column names, e.g.:
+        {'x': 'ax-row-0-col-0_trace-id-sine_variable-x',
+         'y': 'ax-row-0-col-0_trace-id-sine_variable-y'}
+    """
+    result = {}
+    prefix = get_csv_column_prefix(ax_row, ax_col, trace_id, trace_index)
+
+    for col in df.columns:
+        if col.startswith(prefix):
+            # Extract variable from column name
+            variable = col[len(prefix):]
+            result[variable] = col
+
+    return result
+
+
+# EOF