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

scitex/plt/styles/_style_loader.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-01 20:00:00 (ywatanabe)"
+# File: ./src/scitex/plt/styles/_style_loader.py
+
+"""
+Style loader for SciTeX plotting.
+
+Loads style configuration from YAML file and provides centralized access
+to all style parameters. This ensures consistency across all plotting functions.
+
+Usage:
+    from scitex.plt.styles import load_style, get_style, STYLE
+
+    # Load default style
+    style = load_style()
+    fig, ax = stx.plt.subplots(**style)
+
+    # Load with journal preset
+    style = load_style(preset="nature")
+
+    # Load custom YAML file
+    style = load_style("path/to/my_style.yaml")
+
+    # Access individual style parameters
+    from scitex.plt.styles._style_loader import STYLE
+    line_width = STYLE.lines.trace_mm
+"""
+
+__all__ = ["load_style", "get_style", "STYLE", "reload_style"]
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+import yaml
+
+from scitex.dict import DotDict
+
+
+# Path to default style file
+_DEFAULT_STYLE_PATH = Path(__file__).parent / "SCITEX_STYLE.yaml"
+
+# Global style cache
+_STYLE_CACHE: Optional[DotDict] = None
+
+
+def _deep_merge(base: Dict, override: Dict) -> Dict:
+    """Deep merge two dictionaries, with override taking precedence."""
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def _load_yaml(path: Union[str, Path]) -> Dict:
+    """Load YAML file and return as dictionary."""
+    with open(path, "r") as f:
+        return yaml.safe_load(f)
+
+
+def reload_style(
+    path: Optional[Union[str, Path]] = None,
+    preset: Optional[str] = None,
+) -> DotDict:
+    """
+    Reload style from YAML file (clears cache).
+
+    Parameters
+    ----------
+    path : str or Path, optional
+        Path to YAML style file. If None, uses default SCITEX_STYLE.yaml
+    preset : str, optional
+        Journal preset to apply: "nature", "science", "cell", "pnas"
+
+    Returns
+    -------
+    DotDict
+        Style configuration as DotDict for dot-access
+    """
+    global _STYLE_CACHE
+    _STYLE_CACHE = None
+    return load_style(path, preset)
+
+
+def load_style(
+    path: Optional[Union[str, Path]] = None,
+    preset: Optional[str] = None,
+) -> DotDict:
+    """
+    Load style configuration from YAML file.
+
+    Parameters
+    ----------
+    path : str or Path, optional
+        Path to YAML style file. If None, uses default SCITEX_STYLE.yaml
+    preset : str, optional
+        Journal preset to apply: "nature", "science", "cell", "pnas"
+
+    Returns
+    -------
+    DotDict
+        Style configuration as DotDict for dot-access
+
+    Examples
+    --------
+    >>> style = load_style()
+    >>> style.fonts.axis_label_pt
+    7
+    >>> style.lines.trace_mm
+    0.2
+    """
+    global _STYLE_CACHE
+
+    # Use cache if available and no custom path/preset
+    if _STYLE_CACHE is not None and path is None and preset is None:
+        return _STYLE_CACHE
+
+    # Load from file
+    style_path = Path(path) if path else _DEFAULT_STYLE_PATH
+    if not style_path.exists():
+        raise FileNotFoundError(f"Style file not found: {style_path}")
+
+    style_dict = _load_yaml(style_path)
+
+    # Apply preset if specified
+    if preset:
+        presets = style_dict.get("presets", {})
+        if preset not in presets:
+            available = list(presets.keys())
+            raise ValueError(f"Unknown preset '{preset}'. Available: {available}")
+
+        # Deep merge preset over base style
+        preset_overrides = presets[preset]
+        for section, values in preset_overrides.items():
+            if section in style_dict and isinstance(style_dict[section], dict):
+                style_dict[section] = _deep_merge(style_dict[section], values)
+            else:
+                style_dict[section] = values
+
+    # Remove presets section from final style
+    style_dict.pop("presets", None)
+
+    # Convert to DotDict for convenient access
+    style = DotDict(style_dict)
+
+    # Cache if using default
+    if path is None and preset is None:
+        _STYLE_CACHE = style
+
+    return style
+
+
+def get_style() -> DotDict:
+    """
+    Get the current loaded style (loads default if not yet loaded).
+
+    Returns
+    -------
+    DotDict
+        Current style configuration
+    """
+    global _STYLE_CACHE
+    if _STYLE_CACHE is None:
+        return load_style()
+    return _STYLE_CACHE
+
+
+def to_subplots_kwargs(style: Optional[DotDict] = None) -> Dict[str, Any]:
+    """
+    Convert style DotDict to kwargs for stx.plt.subplots().
+
+    Parameters
+    ----------
+    style : DotDict, optional
+        Style configuration. If None, uses current loaded style.
+
+    Returns
+    -------
+    dict
+        Keyword arguments for stx.plt.subplots()
+
+    Examples
+    --------
+    >>> style = load_style(preset="nature")
+    >>> kwargs = to_subplots_kwargs(style)
+    >>> fig, ax = stx.plt.subplots(**kwargs)
+    """
+    if style is None:
+        style = get_style()
+
+    return {
+        # Axes dimensions
+        "ax_width_mm": style.axes.width_mm,
+        "ax_height_mm": style.axes.height_mm,
+        "ax_thickness_mm": style.axes.thickness_mm,
+        # Margins
+        "margin_left_mm": style.margins.left_mm,
+        "margin_right_mm": style.margins.right_mm,
+        "margin_bottom_mm": style.margins.bottom_mm,
+        "margin_top_mm": style.margins.top_mm,
+        # Spacing
+        "space_w_mm": style.spacing.horizontal_mm,
+        "space_h_mm": style.spacing.vertical_mm,
+        # Ticks
+        "tick_length_mm": style.ticks.length_mm,
+        "tick_thickness_mm": style.ticks.thickness_mm,
+        "n_ticks": style.ticks.n_ticks,
+        # Lines
+        "trace_thickness_mm": style.lines.trace_mm,
+        # Markers
+        "marker_size_mm": style.markers.size_mm,
+        # Fonts
+        "axis_font_size_pt": style.fonts.axis_label_pt,
+        "tick_font_size_pt": style.fonts.tick_label_pt,
+        "title_font_size_pt": style.fonts.title_pt,
+        "suptitle_font_size_pt": style.fonts.suptitle_pt,
+        "legend_font_size_pt": style.fonts.legend_pt,
+        # Padding
+        "label_pad_pt": style.padding.label_pt,
+        "tick_pad_pt": style.padding.tick_pt,
+        "title_pad_pt": style.padding.title_pt,
+        # Output
+        "dpi": style.output.dpi,
+        "transparent": style.output.transparent,
+        # Mode
+        "mode": "publication",
+    }
+
+
+# Lazy-loaded global STYLE object
+class _StyleProxy:
+    """Proxy object that loads style on first access."""
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(get_style(), name)
+
+    def __repr__(self) -> str:
+        return repr(get_style())
+
+
+STYLE = _StyleProxy()
+
+
+if __name__ == "__main__":
+    # Test loading
+    print("Loading default style...")
+    style = load_style()
+    print(f"  axes.width_mm: {style.axes.width_mm}")
+    print(f"  fonts.axis_label_pt: {style.fonts.axis_label_pt}")
+    print(f"  lines.trace_mm: {style.lines.trace_mm}")
+
+    print("\nLoading Nature preset...")
+    nature_style = load_style(preset="nature")
+    print(f"  axes.width_mm: {nature_style.axes.width_mm}")
+
+    print("\nConverting to subplots kwargs...")
+    kwargs = to_subplots_kwargs()
+    for k, v in list(kwargs.items())[:5]:
+        print(f"  {k}: {v}")
+
+    print("\nUsing STYLE proxy...")
+    print(f"  STYLE.fonts.family: {STYLE.fonts.family}")
+
+# EOF

scitex/plt/styles/presets.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-01 21:30:00 (ywatanabe)"
+# File: ./src/scitex/plt/styles/presets.py
+
+"""
+SciTeX style configuration.
+
+Style Control Levels:
+    1. Global level (subplots): axes dimensions, fonts, default line thickness
+    2. Plot level (per-call): override for individual ax.plot(), ax.scatter(), etc.
+
+Priority cascade: direct → env → yaml → default
+
+Style Management:
+    - load_style(path): Load style from YAML/JSON file
+    - save_style(path): Export current style to file
+    - set_style(style_dict): Change active style globally
+    - get_style(): Get current active style
+
+Usage:
+    from scitex.plt.styles import load_style, save_style, set_style
+
+    # Load and use custom style
+    style = load_style("my_style.yaml")
+    fig, ax = stx.plt.subplots(**style)
+
+    # Export current style
+    save_style("exported_style.yaml")
+
+    # Change global style
+    set_style({"axes_width_mm": 60, "trace_thickness_mm": 0.3})
+"""
+
+__all__ = [
+    "SCITEX_STYLE", "STYLE",
+    "load_style", "save_style", "set_style", "get_style",
+    "resolve_style_value",
+]
+
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+import scitex.io
+from scitex.config import PriorityConfig
+
+_STYLE_FILE = Path(__file__).parent / "SCITEX_STYLE.yaml"
+_config: Optional[PriorityConfig] = None
+_active_style: Optional[Dict[str, Any]] = None  # User-set style override
+
+
+def _get_config(yaml_path: Optional[Path] = None) -> PriorityConfig:
+    """Get or create PriorityConfig from YAML."""
+    global _config
+    if _config is None or yaml_path:
+        yaml = scitex.io.load(yaml_path or _STYLE_FILE)
+        flat = {f"{k}.{k2}": v2 for k, v in yaml.items() if isinstance(v, dict) and k != "presets" for k2, v2 in v.items()}
+        _config = PriorityConfig(flat, env_prefix="SCITEX_PLT_", auto_uppercase=True)
+    return _config
+
+
+def resolve_style_value(key: str, direct_val: Any = None, default: Any = None, type: type = float) -> Any:
+    """Resolve value with priority: direct → env → yaml → default.
+
+    Key format: 'axes.width_mm' - dots for YAML hierarchy, underscores for env vars.
+    Env var: SCITEX_PLT_AXES_WIDTH_MM (prefix + key with dots→underscores, uppercased)
+    """
+    return _get_config().resolve(key, direct_val, default, type)
+
+
+def load_style(path: Optional[Union[str, Path]] = None) -> Dict[str, Any]:
+    """Load style from YAML as subplots kwargs."""
+    cfg = _get_config(Path(path) if path else None)
+    g = lambda k, d, t=float: cfg.resolve(k, None, d, t)
+    return {
+        "axes_width_mm": g("axes.width_mm", 40), "axes_height_mm": g("axes.height_mm", 28),
+        "axes_thickness_mm": g("axes.thickness_mm", 0.2),
+        "margin_left_mm": g("margins.left_mm", 20), "margin_right_mm": g("margins.right_mm", 20),
+        "margin_bottom_mm": g("margins.bottom_mm", 20), "margin_top_mm": g("margins.top_mm", 20),
+        "space_w_mm": g("spacing.horizontal_mm", 8), "space_h_mm": g("spacing.vertical_mm", 10),
+        "tick_length_mm": g("ticks.length_mm", 0.8), "tick_thickness_mm": g("ticks.thickness_mm", 0.2),
+        "n_ticks": g("ticks.n_ticks", 4, int),
+        "trace_thickness_mm": g("lines.trace_mm", 0.2), "errorbar_thickness_mm": g("lines.errorbar_mm", 0.2),
+        "errorbar_cap_width_mm": g("lines.errorbar_cap_mm", 0.8), "bar_edge_thickness_mm": g("lines.bar_edge_mm", 0.2),
+        "kde_line_thickness_mm": g("lines.kde_mm", 0.2),
+        "scatter_size_mm": g("markers.scatter_mm", 0.8), "marker_size_mm": g("markers.size_mm", 0.8),
+        "font_family": g("fonts.family", "Arial", str),
+        "axis_font_size_pt": g("fonts.axis_label_pt", 7), "tick_font_size_pt": g("fonts.tick_label_pt", 7),
+        "title_font_size_pt": g("fonts.title_pt", 8), "suptitle_font_size_pt": g("fonts.suptitle_pt", 8),
+        "legend_font_size_pt": g("fonts.legend_pt", 6), "annotation_font_size_pt": g("fonts.annotation_pt", 6),
+        "label_pad_pt": g("padding.label_pt", 0.5), "tick_pad_pt": g("padding.tick_pt", 2.0),
+        "title_pad_pt": g("padding.title_pt", 1.0),
+        "dpi": g("output.dpi", 300, int), "transparent": g("output.transparent", True, bool),
+        "auto_scale_axes": g("behavior.auto_scale_axes", True, bool), "mode": "publication",
+    }
+
+
+def get_style() -> Dict[str, Any]:
+    """Get current active style configuration.
+
+    Returns style with priority: active_style → env → yaml → default
+    """
+    global _active_style
+    base = load_style()
+    if _active_style:
+        base.update(_active_style)
+    return base
+
+
+def set_style(style_dict: Optional[Dict[str, Any]] = None) -> None:
+    """Set active style globally.
+
+    Args:
+        style_dict: Style values to override. Pass None to reset to defaults.
+
+    Example:
+        set_style({"axes_width_mm": 60, "trace_thickness_mm": 0.3})
+        set_style(None)  # Reset to defaults
+    """
+    global _active_style, SCITEX_STYLE, STYLE
+    _active_style = style_dict
+    SCITEX_STYLE = get_style()
+    STYLE = SCITEX_STYLE
+
+
+def save_style(path: Union[str, Path], style: Optional[Dict[str, Any]] = None) -> Path:
+    """Export style to YAML or JSON file.
+
+    Args:
+        path: Output file path (.yaml, .yml, or .json)
+        style: Style dict to export. If None, exports current active style.
+
+    Returns:
+        Path to saved file.
+
+    Example:
+        save_style("my_style.yaml")
+        save_style("custom.json", {"axes_width_mm": 60})
+    """
+    path = Path(path)
+    style = style or get_style()
+
+    # Convert flat style dict to hierarchical YAML structure
+    hierarchical = _flat_to_hierarchical(style)
+
+    scitex.io.save(hierarchical, path)
+    return path
+
+
+def _flat_to_hierarchical(style: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert flat style dict to hierarchical YAML structure.
+
+    Example:
+        {"axes_width_mm": 40} -> {"axes": {"width_mm": 40}}
+    """
+    # Mapping from flat keys to hierarchical paths
+    mapping = {
+        "axes_width_mm": ("axes", "width_mm"),
+        "axes_height_mm": ("axes", "height_mm"),
+        "axes_thickness_mm": ("axes", "thickness_mm"),
+        "margin_left_mm": ("margins", "left_mm"),
+        "margin_right_mm": ("margins", "right_mm"),
+        "margin_bottom_mm": ("margins", "bottom_mm"),
+        "margin_top_mm": ("margins", "top_mm"),
+        "space_w_mm": ("spacing", "horizontal_mm"),
+        "space_h_mm": ("spacing", "vertical_mm"),
+        "tick_length_mm": ("ticks", "length_mm"),
+        "tick_thickness_mm": ("ticks", "thickness_mm"),
+        "n_ticks": ("ticks", "n_ticks"),
+        "trace_thickness_mm": ("lines", "trace_mm"),
+        "errorbar_thickness_mm": ("lines", "errorbar_mm"),
+        "errorbar_cap_width_mm": ("lines", "errorbar_cap_mm"),
+        "bar_edge_thickness_mm": ("lines", "bar_edge_mm"),
+        "kde_line_thickness_mm": ("lines", "kde_mm"),
+        "scatter_size_mm": ("markers", "scatter_mm"),
+        "marker_size_mm": ("markers", "size_mm"),
+        "font_family": ("fonts", "family"),
+        "axis_font_size_pt": ("fonts", "axis_label_pt"),
+        "tick_font_size_pt": ("fonts", "tick_label_pt"),
+        "title_font_size_pt": ("fonts", "title_pt"),
+        "suptitle_font_size_pt": ("fonts", "suptitle_pt"),
+        "legend_font_size_pt": ("fonts", "legend_pt"),
+        "annotation_font_size_pt": ("fonts", "annotation_pt"),
+        "label_pad_pt": ("padding", "label_pt"),
+        "tick_pad_pt": ("padding", "tick_pt"),
+        "title_pad_pt": ("padding", "title_pt"),
+        "dpi": ("output", "dpi"),
+        "transparent": ("output", "transparent"),
+        "auto_scale_axes": ("behavior", "auto_scale_axes"),
+    }
+
+    result: Dict[str, Any] = {}
+    for flat_key, value in style.items():
+        if flat_key in mapping:
+            section, key = mapping[flat_key]
+            if section not in result:
+                result[section] = {}
+            result[section][key] = value
+        # Skip keys not in mapping (like 'mode')
+
+    return result
+
+
+SCITEX_STYLE = load_style()
+STYLE = SCITEX_STYLE
+
+
+# EOF