scitex 2.3.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

scitex/plt/styles/SCITEX_STYLE.yaml

@@ -0,0 +1,104 @@
+# SciTeX Style Configuration
+# ===========================
+# Centralized style settings for publication-quality figures.
+# Users can modify this file or create their own YAML file.
+#
+# Units:
+#   - *_mm: millimeters (converted to points internally)
+#   - *_pt: points (1 pt = 1/72 inch)
+#
+# Usage:
+#   from scitex.plt import load_style
+#   style = load_style()  # Load default SCITEX_STYLE.yaml
+#   style = load_style("path/to/custom_style.yaml")  # Load custom style
+#   fig, ax = stx.plt.subplots(**style)
+
+# =============================================================================
+# AXES DIMENSIONS
+# =============================================================================
+# Can be scalar (applies to all) or list matching axes.flat size
+axes:
+  width_mm: 40           # Axes width in mm (scalar or list)
+  height_mm: 28          # Axes height in mm (scalar or list, 1:0.7 ratio)
+  thickness_mm: 0.2      # Spine line thickness in mm
+
+# =============================================================================
+# MARGINS AND SPACING (in mm)
+# =============================================================================
+margins:
+  left_mm: 20            # Left margin (large for labels, crop afterwards)
+  right_mm: 20           # Right margin (for colorbars)
+  bottom_mm: 20          # Bottom margin (for x-axis labels)
+  top_mm: 20             # Top margin (for titles)
+
+spacing:
+  horizontal_mm: 8       # Horizontal spacing between axes
+  vertical_mm: 10        # Vertical spacing between axes
+
+# =============================================================================
+# FONT SIZES (in points)
+# =============================================================================
+fonts:
+  family: "Arial"        # Font family (Arial for Nature-style)
+  axis_label_pt: 7       # X/Y axis label font size
+  tick_label_pt: 7       # Tick label font size
+  title_pt: 8            # Plot title font size
+  suptitle_pt: 8         # Super title font size
+  legend_pt: 6           # Legend font size
+  annotation_pt: 6       # Annotation text (stats, etc.)
+
+# =============================================================================
+# PADDING (in points)
+# =============================================================================
+padding:
+  label_pt: 0.5          # Axis label to axis distance (extremely tight)
+  tick_pt: 2.0           # Tick label to tick distance
+  title_pt: 1.0          # Title to axis top distance
+
+# =============================================================================
+# LINE THICKNESSES (in mm)
+# =============================================================================
+lines:
+  trace_mm: 0.2          # Plot line thickness
+  errorbar_mm: 0.2       # Error bar line thickness
+  errorbar_cap_mm: 0.8   # Error bar cap width
+  bar_edge_mm: 0.2       # Bar plot edge thickness
+  kde_mm: 0.2            # KDE line thickness
+  boxplot_mm: 0.2        # Boxplot line thickness
+  violin_mm: 0.2         # Violin plot line thickness
+  colorbar_mm: 0.2       # Colorbar outline thickness
+
+# =============================================================================
+# TICK MARKS (in mm)
+# =============================================================================
+ticks:
+  length_mm: 0.8         # Tick mark length
+  thickness_mm: 0.2      # Tick mark thickness
+  direction: "out"       # Tick direction: "in", "out", or "inout"
+  n_ticks: 4             # Target number of ticks per axis (3-4)
+
+# =============================================================================
+# MARKERS (in mm)
+# =============================================================================
+markers:
+  size_mm: 0.8           # Default marker size
+  scatter_mm: 0.8        # Scatter plot marker size
+  edge_width_mm: 0.1     # Marker edge width
+
+# =============================================================================
+# OUTPUT SETTINGS
+# =============================================================================
+output:
+  dpi: 300               # Resolution for saving
+  transparent: true      # Transparent background for cropping
+  format: "png"          # Default output format
+
+# =============================================================================
+# BEHAVIOR FLAGS
+# =============================================================================
+behavior:
+  auto_scale_axes: true  # Factor out powers of 10 from tick labels
+  hide_top_spine: true   # Hide top spine
+  hide_right_spine: true # Hide right spine
+  grid: false            # Show grid
+

scitex/plt/styles/__init__.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-01 21:00:00 (ywatanabe)"
+# File: ./src/scitex/plt/styles/__init__.py
+
+"""SciTeX plot styling module.
+
+This module centralizes all plot-specific default styling, including:
+- Pre-processing: Default kwargs applied before matplotlib method calls
+- Post-processing: Styling applied after matplotlib method calls
+- Style configuration with priority resolution: direct → yaml → env → default
+
+Usage:
+    from scitex.plt.styles import apply_plot_defaults, apply_plot_postprocess
+
+    # In AxisWrapper.__getattr__ wrapper:
+    apply_plot_defaults(method_name, kwargs, id_value, ax)
+    result = orig_method(*args, **kwargs)
+    apply_plot_postprocess(method_name, result, ax, kwargs)
+
+    # Style configuration
+    from scitex.plt.styles import SCITEX_STYLE, load_style
+    fig, ax = stx.plt.subplots(**SCITEX_STYLE)
+
+    # Custom YAML
+    style = load_style("path/to/my_style.yaml")
+    fig, ax = stx.plt.subplots(**style)
+"""
+
+from ._plot_defaults import apply_plot_defaults
+from ._plot_postprocess import apply_plot_postprocess
+from .presets import (
+    SCITEX_STYLE,
+    STYLE,
+    load_style,
+    save_style,
+    set_style,
+    get_style,
+    resolve_style_value,
+)
+
+__all__ = [
+    # Styling functions
+    'apply_plot_defaults',
+    'apply_plot_postprocess',
+    # Style configuration
+    'SCITEX_STYLE',
+    'STYLE',
+    'load_style',
+    'save_style',
+    'set_style',
+    'get_style',
+    'resolve_style_value',
+]
+
+
+# EOF

scitex/plt/styles/_plot_defaults.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-01 10:00:00 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/plt/styles/_plot_defaults.py
+
+"""Pre-processing default kwargs for plot methods.
+
+This module centralizes all default styling applied BEFORE matplotlib
+methods are called. Each function modifies kwargs in-place.
+
+Priority: direct kwarg → env var → YAML config → default
+
+Style values use the key format from YAML (e.g., 'lines.trace_mm').
+Env vars: SCITEX_PLT_LINES_TRACE_MM (prefix + dots→underscores + uppercase)
+"""
+
+from scitex.plt.utils import mm_to_pt
+from scitex.plt.styles.presets import resolve_style_value
+
+# Default alpha for fill regions (0.3 = semi-transparent)
+DEFAULT_FILL_ALPHA = 0.3
+
+
+# ============================================================================
+# Style helper function
+# ============================================================================
+def _get_style_value(key, default, style_dict=None):
+    """Get style value with priority: style_dict → active_style → env → yaml → default.
+
+    Args:
+        key: YAML-style key (e.g., 'lines.trace_mm')
+        default: Fallback default value
+        style_dict: Optional user-provided style dict (overrides all)
+
+    Returns:
+        Resolved style value
+    """
+    flat_key = _yaml_key_to_flat(key)
+
+    # Priority 1: User passed explicit style dict
+    if style_dict is not None and flat_key in style_dict:
+        return style_dict[flat_key]
+
+    # Priority 2: Check active style set via set_style()
+    from scitex.plt.styles.presets import _active_style
+    if _active_style is not None and flat_key in _active_style:
+        return _active_style[flat_key]
+
+    # Priority 3: Use resolve_style_value for: env → yaml → default
+    return resolve_style_value(key, None, default)
+
+
+def _yaml_key_to_flat(key):
+    """Convert YAML key to flat SCITEX_STYLE key.
+
+    Examples:
+        'lines.trace_mm' -> 'trace_thickness_mm'
+        'markers.size_mm' -> 'marker_size_mm'
+    """
+    # Mapping from YAML keys to flat keys used in SCITEX_STYLE
+    mapping = {
+        'lines.trace_mm': 'trace_thickness_mm',
+        'lines.errorbar_mm': 'errorbar_thickness_mm',
+        'lines.errorbar_cap_mm': 'errorbar_cap_width_mm',
+        'markers.size_mm': 'marker_size_mm',
+    }
+    return mapping.get(key, key)
+
+
+# ============================================================================
+# Pre-processing functions
+# ============================================================================
+def apply_plot_defaults(method_name, kwargs, id_value=None, ax=None):
+    """Apply default kwargs for a plot method before calling matplotlib.
+
+    Args:
+        method_name: Name of the matplotlib method being called
+        kwargs: Keyword arguments dict (modified in-place)
+        id_value: Optional id passed to the method
+        ax: The matplotlib axes (for methods needing axis setup)
+
+    Returns:
+        Modified kwargs dict
+
+    Note:
+        Priority: direct kwarg → style dict → env var → yaml → default
+        Users can pass `style=dict` kwarg to override env/yaml defaults.
+    """
+    # Extract optional style dict (removes 'style' key from kwargs)
+    style_dict = kwargs.pop("style", None)
+
+    # Dispatch to method-specific defaults
+    if method_name == 'plot':
+        _apply_plot_line_defaults(kwargs, id_value, style_dict)
+    elif method_name in ('bar', 'barh'):
+        _apply_bar_defaults(kwargs, style_dict)
+    elif method_name == 'errorbar':
+        _apply_errorbar_defaults(kwargs, style_dict)
+    elif method_name in ('fill_between', 'fill_betweenx'):
+        _apply_fill_defaults(kwargs)
+    elif method_name in ('quiver', 'streamplot'):
+        _apply_vector_field_defaults(method_name, kwargs, ax, style_dict)
+    elif method_name == 'boxplot':
+        _apply_boxplot_defaults(kwargs)
+    elif method_name == 'violinplot':
+        _apply_violinplot_defaults(kwargs)
+
+    return kwargs
+
+
+def _apply_plot_line_defaults(kwargs, id_value=None, style_dict=None):
+    """Apply defaults for ax.plot() method."""
+    line_width_mm = _get_style_value('lines.trace_mm', 0.2, style_dict)
+
+    # Default line width
+    if 'linewidth' not in kwargs and 'lw' not in kwargs:
+        kwargs['linewidth'] = mm_to_pt(line_width_mm)
+
+    # KDE-specific styling when id contains "kde"
+    if id_value and 'kde' in str(id_value).lower():
+        if 'linestyle' not in kwargs and 'ls' not in kwargs:
+            kwargs['linestyle'] = '--'
+        if 'color' not in kwargs and 'c' not in kwargs:
+            kwargs['color'] = 'black'
+
+
+def _apply_bar_defaults(kwargs, style_dict=None):
+    """Apply defaults for ax.bar() and ax.barh() methods."""
+    line_width_mm = _get_style_value('lines.trace_mm', 0.2, style_dict)
+
+    # Set error bar line thickness
+    if 'error_kw' not in kwargs:
+        kwargs['error_kw'] = {}
+    if 'elinewidth' not in kwargs.get('error_kw', {}):
+        kwargs['error_kw']['elinewidth'] = mm_to_pt(line_width_mm)
+    if 'capthick' not in kwargs.get('error_kw', {}):
+        kwargs['error_kw']['capthick'] = mm_to_pt(line_width_mm)
+    # Set a temporary capsize that will be adjusted in post-processing
+    if 'capsize' not in kwargs:
+        kwargs['capsize'] = 5  # Placeholder, adjusted later to 33% of bar width
+
+
+def _apply_errorbar_defaults(kwargs, style_dict=None):
+    """Apply defaults for ax.errorbar() method."""
+    line_width_mm = _get_style_value('lines.trace_mm', 0.2, style_dict)
+    cap_size_mm = _get_style_value('lines.errorbar_cap_mm', 0.8, style_dict)
+
+    if 'capsize' not in kwargs:
+        kwargs['capsize'] = mm_to_pt(cap_size_mm)
+    if 'capthick' not in kwargs:
+        kwargs['capthick'] = mm_to_pt(line_width_mm)
+    if 'elinewidth' not in kwargs:
+        kwargs['elinewidth'] = mm_to_pt(line_width_mm)
+
+
+def _apply_fill_defaults(kwargs):
+    """Apply defaults for ax.fill_between() and ax.fill_betweenx() methods."""
+    if 'alpha' not in kwargs:
+        kwargs['alpha'] = DEFAULT_FILL_ALPHA  # Transparent to see overlapping data
+
+
+def _apply_vector_field_defaults(method_name, kwargs, ax, style_dict=None):
+    """Apply defaults for ax.quiver() and ax.streamplot() methods."""
+    line_width_mm = _get_style_value('lines.trace_mm', 0.2, style_dict)
+    marker_size_mm = _get_style_value('markers.size_mm', 0.8, style_dict)
+
+    # Set equal aspect ratio for proper vector display
+    if ax is not None:
+        ax.set_aspect('equal', adjustable='datalim')
+
+    if method_name == 'streamplot':
+        if 'arrowsize' not in kwargs:
+            # arrowsize is a scaling factor; scale relative to default
+            kwargs['arrowsize'] = mm_to_pt(marker_size_mm) / 3
+        if 'linewidth' not in kwargs:
+            kwargs['linewidth'] = mm_to_pt(line_width_mm)
+
+    elif method_name == 'quiver':
+        if 'width' not in kwargs:
+            kwargs['width'] = 0.003  # Narrow arrow shaft (axes fraction)
+        if 'headwidth' not in kwargs:
+            kwargs['headwidth'] = 3  # Head width relative to shaft
+        if 'headlength' not in kwargs:
+            kwargs['headlength'] = 4
+        if 'headaxislength' not in kwargs:
+            kwargs['headaxislength'] = 3.5
+
+
+def _apply_boxplot_defaults(kwargs):
+    """Apply defaults for ax.boxplot() method."""
+    # Enable patch_artist for fillable boxes
+    if 'patch_artist' not in kwargs:
+        kwargs['patch_artist'] = True
+
+
+def _apply_violinplot_defaults(kwargs):
+    """Apply defaults for ax.violinplot() method."""
+    # Default to showing boxplot overlay (can be disabled with boxplot=False)
+    # Store the boxplot setting for post-processing, then remove from kwargs
+    # so it doesn't get passed to matplotlib's violinplot
+    if 'boxplot' not in kwargs:
+        kwargs['boxplot'] = True  # Default: add boxplot overlay
+
+    # Default to hiding extrema (min/max bars) when boxplot is shown
+    if 'showextrema' not in kwargs:
+        kwargs['showextrema'] = False
+
+
+# EOF