oscura 0.8.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

oscura/visualization/styles.py

@@ -1,381 +1,247 @@
-"""Plot style presets for different output contexts.
-
-This module provides comprehensive style presets for publication-quality,
-presentation, screen viewing, and print output.
+"""Plot styling presets and colorblind-safe palettes.
 
+Provides IEEE styling and accessibility-focused color schemes.
 
 Example:
-    >>> from oscura.visualization.styles import apply_style_preset
-    >>> with apply_style_preset("publication"):
-    ...     plot_waveform(signal)
-
-References:
-    matplotlib rcParams customization
-    Publication and presentation best practices
+    >>> from oscura.visualization.styles import apply_ieee_style
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([1, 2, 3])
+    >>> apply_ieee_style(ax)
 """
 
 from __future__ import annotations
 
-from contextlib import contextmanager
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from collections.abc import Iterator
+from typing import Literal
 
 try:
-    import matplotlib.pyplot as plt
+    from matplotlib.axes import Axes
 
     HAS_MATPLOTLIB = True
 except ImportError:
     HAS_MATPLOTLIB = False
 
 
-@dataclass
-class StylePreset:
-    """Style preset configuration for plots.
-
-    Attributes:
-        name: Preset name
-        dpi: Target DPI (dots per inch)
-        font_family: Font family (serif, sans-serif, monospace)
-        font_size: Base font size in points
-        line_width: Default line width in points
-        marker_size: Default marker size
-        figure_facecolor: Figure background color
-        axes_facecolor: Axes background color
-        axes_edgecolor: Axes edge color
-        grid_color: Grid line color
-        grid_alpha: Grid line transparency
-        grid_linestyle: Grid line style
-        use_latex: Use LaTeX for text rendering
-        tight_layout: Use tight layout
-        rcparams: Additional matplotlib rcParams
-    """
+# Colorblind-safe palettes (Tol Bright)
+COLORBLIND_PALETTE: list[str] = [
+    "#4477AA",  # Blue
+    "#EE6677",  # Red
+    "#228833",  # Green
+    "#CCBB44",  # Yellow
+    "#66CCEE",  # Cyan
+    "#AA3377",  # Purple
+    "#BBBBBB",  # Gray
+]
 
-    name: str
-    dpi: int = 96
-    font_family: str = "sans-serif"
-    font_size: int = 10
-    line_width: float = 1.0
-    marker_size: float = 6.0
-    figure_facecolor: str = "white"
-    axes_facecolor: str = "white"
-    axes_edgecolor: str = "black"
-    grid_color: str = "#B0B0B0"
-    grid_alpha: float = 0.3
-    grid_linestyle: str = "-"
-    use_latex: bool = False
-    tight_layout: bool = True
-    rcparams: dict[str, Any] = field(default_factory=dict)
-
-
-# Predefined style presets
-
-PUBLICATION_PRESET = StylePreset(
-    name="publication",
-    dpi=600,
-    font_family="serif",
-    font_size=10,
-    line_width=0.8,
-    marker_size=4.0,
-    figure_facecolor="white",
-    axes_facecolor="white",
-    axes_edgecolor="black",
-    grid_color="#808080",
-    grid_alpha=0.3,
-    grid_linestyle=":",
-    use_latex=False,  # LaTeX optional - requires system install
-    tight_layout=True,
-    rcparams={
-        "axes.linewidth": 0.8,
-        "xtick.major.width": 0.8,
-        "ytick.major.width": 0.8,
-        "xtick.minor.width": 0.6,
-        "ytick.minor.width": 0.6,
-        "lines.antialiased": True,
-        "patch.antialiased": True,
-        "savefig.dpi": 600,
-        "savefig.format": "pdf",
-        "savefig.bbox": "tight",
-    },
-)
-
-PRESENTATION_PRESET = StylePreset(
-    name="presentation",
-    dpi=96,
-    font_family="sans-serif",
-    font_size=18,
-    line_width=2.5,
-    marker_size=10.0,
-    figure_facecolor="white",
-    axes_facecolor="white",
-    axes_edgecolor="black",
-    grid_color="#CCCCCC",
-    grid_alpha=0.5,
-    grid_linestyle="-",
-    use_latex=False,
-    tight_layout=True,
-    rcparams={
-        "axes.linewidth": 2.0,
-        "xtick.major.width": 2.0,
-        "ytick.major.width": 2.0,
-        "xtick.major.size": 8,
-        "ytick.major.size": 8,
-        "lines.antialiased": True,
-        "savefig.dpi": 150,
-    },
-)
-
-SCREEN_PRESET = StylePreset(
-    name="screen",
-    dpi=96,
-    font_family="sans-serif",
-    font_size=10,
-    line_width=1.2,
-    marker_size=6.0,
-    figure_facecolor="white",
-    axes_facecolor="white",
-    axes_edgecolor="#333333",
-    grid_color="#B0B0B0",
-    grid_alpha=0.3,
-    grid_linestyle="-",
-    use_latex=False,
-    tight_layout=True,
-    rcparams={
-        "axes.linewidth": 1.0,
-        "lines.antialiased": True,
-        "patch.antialiased": True,
-    },
-)
-
-PRINT_PRESET = StylePreset(
-    name="print",
-    dpi=300,
-    font_family="serif",
-    font_size=11,
-    line_width=1.2,
-    marker_size=5.0,
-    figure_facecolor="white",
-    axes_facecolor="white",
-    axes_edgecolor="black",
-    grid_color="#707070",
-    grid_alpha=0.3,
-    grid_linestyle=":",
-    use_latex=False,
-    tight_layout=True,
-    rcparams={
-        "axes.linewidth": 1.0,
-        "xtick.major.width": 1.0,
-        "ytick.major.width": 1.0,
-        "lines.antialiased": False,  # Sharper lines for print
-        "patch.antialiased": False,
-        "savefig.dpi": 300,
-        "savefig.format": "pdf",
-    },
-)
-
-# Registry of available presets
-PRESETS: dict[str, StylePreset] = {
-    "publication": PUBLICATION_PRESET,
-    "presentation": PRESENTATION_PRESET,
-    "screen": SCREEN_PRESET,
-    "print": PRINT_PRESET,
+# IEEE publication styling defaults
+IEEE_STYLE: dict[str, str | float] = {
+    "font.family": "serif",
+    "font.size": 10,
+    "axes.linewidth": 0.8,
+    "grid.alpha": 0.3,
+    "grid.linestyle": ":",
+    "lines.linewidth": 1.0,
+    "lines.markersize": 4.0,
+    "figure.dpi": 600,
+    "savefig.dpi": 600,
+    "savefig.bbox": "tight",
 }
 
+# Line styles for accessibility (when color alone isn't sufficient)
+LINE_STYLES: list[str] = ["solid", "dashed", "dotted", "dashdot"]
 
-@contextmanager
-def apply_style_preset(
-    preset: str | StylePreset,
-    *,
-    overrides: dict[str, Any] | None = None,
-) -> Iterator[None]:
-    """Apply style preset as context manager.
+# Pass/fail symbols for reports
+PASS_SYMBOL = "✓"
+FAIL_SYMBOL = "✗"
 
-    : Provide comprehensive style presets for common use cases
-    with support for custom overrides.
 
-    Args:
-        preset: Preset name or StylePreset object
-        overrides: Dictionary of rcParams to override
+def apply_ieee_style(ax: Axes) -> None:
+    """Apply IEEE publication styling to axes.
 
-    Yields:
-        None (use as context manager)
+    Configures fonts, line widths, and grid for publication-quality plots.
 
-    Raises:
-        ValueError: If preset name is unknown
-        ImportError: If matplotlib is not available
+    Args:
+        ax: Matplotlib axes to style.
 
     Example:
-        >>> with apply_style_preset("publication"):
-        ...     fig, ax = plt.subplots()
-        ...     ax.plot(x, y)
-        ...     plt.savefig("figure.pdf")
-
-        >>> # With overrides
-        >>> with apply_style_preset("screen", overrides={"font.size": 14}):
-        ...     plot_waveform(signal)
-
-    References:
-        VIS-024: Plot Style Presets
-        matplotlib style sheets and rcParams
+        >>> fig, ax = plt.subplots()
+        >>> ax.plot(x, y)
+        >>> apply_ieee_style(ax)
+        >>> fig.savefig("publication.pdf")
     """
     if not HAS_MATPLOTLIB:
-        raise ImportError("matplotlib is required for style presets")
+        raise ImportError("matplotlib required for styling")
 
-    # Get preset object
-    if isinstance(preset, str):
-        if preset not in PRESETS:
-            raise ValueError(f"Unknown preset: {preset}. Available: {list(PRESETS.keys())}")
-        preset_obj = PRESETS[preset]
-    else:
-        preset_obj = preset
+    # Apply IEEE styling
+    for spine in ax.spines.values():
+        spine.set_linewidth(0.8)
 
-    # Build rcParams dictionary
-    rc_dict = _preset_to_rcparams(preset_obj)
+    ax.grid(True, alpha=0.3, linestyle=":")
 
-    # Apply overrides
-    if overrides:
-        rc_dict.update(overrides)
+    # Update tick parameters
+    ax.tick_params(width=0.8, labelsize=9)
 
-    # Apply as context
-    with plt.rc_context(rc_dict):
-        yield
+    # Set font properties
+    ax.xaxis.label.set_fontsize(10)
+    ax.yaxis.label.set_fontsize(10)
 
 
-def _preset_to_rcparams(preset: StylePreset) -> dict[str, Any]:
-    """Convert StylePreset to matplotlib rcParams dictionary.
+def get_colorblind_palette(n_colors: int | None = None) -> list[str]:
+    """Get colorblind-safe color palette.
+
+    Returns perceptually distinct colors that work for colorblind viewers.
 
     Args:
-        preset: StylePreset object
+        n_colors: Number of colors to return (default: all 7).
 
     Returns:
-        Dictionary of rcParams
+        List of hex color codes.
+
+    Example:
+        >>> colors = get_colorblind_palette(3)
+        >>> for i, color in enumerate(colors):
+        ...     ax.plot(x, y[i], color=color)
     """
-    rc = {
-        "figure.dpi": preset.dpi,
-        "font.family": preset.font_family,
-        "font.size": preset.font_size,
-        "lines.linewidth": preset.line_width,
-        "lines.markersize": preset.marker_size,
-        "figure.facecolor": preset.figure_facecolor,
-        "axes.facecolor": preset.axes_facecolor,
-        "axes.edgecolor": preset.axes_edgecolor,
-        "grid.color": preset.grid_color,
-        "grid.alpha": preset.grid_alpha,
-        "grid.linestyle": preset.grid_linestyle,
-        "figure.autolayout": preset.tight_layout,
-    }
-
-    # LaTeX rendering
-    if preset.use_latex:
-        rc["text.usetex"] = True
-
-    # Merge with additional rcparams
-    rc.update(preset.rcparams)
-
-    return rc
-
-
-def create_custom_preset(
-    name: str,
-    base_preset: str = "screen",
-    **kwargs: Any,
-) -> StylePreset:
-    """Create custom preset by inheriting from base preset.
-
-    : Support custom presets with inheritance and override.
+    if n_colors is None:
+        return COLORBLIND_PALETTE.copy()
+    return COLORBLIND_PALETTE[:n_colors]
+
+
+def get_colorblind_cmap(name: Literal["viridis", "cividis", "plasma"] = "viridis") -> str:
+    """Get colorblind-safe colormap name.
 
     Args:
-        name: Name for custom preset
-        base_preset: Base preset to inherit from
-        **kwargs: Attributes to override
+        name: Colormap name (viridis, cividis, plasma).
 
     Returns:
-        Custom StylePreset object
+        Matplotlib colormap name.
+
+    Example:
+        >>> cmap = get_colorblind_cmap("viridis")
+        >>> ax.imshow(data, cmap=cmap)
+    """
+    valid = {"viridis", "cividis", "plasma"}
+    if name not in valid:
+        raise ValueError(f"Unknown colormap: {name}. Valid: {valid}")
+    return name
+
 
-    Raises:
-        ValueError: If base_preset is unknown
+def get_line_styles(n_lines: int) -> list[str]:
+    """Get distinct line styles for multi-line plots.
+
+    Useful when color alone isn't sufficient (grayscale printing, accessibility).
+
+    Args:
+        n_lines: Number of line styles needed.
+
+    Returns:
+        List of line style strings.
 
     Example:
-        >>> custom = create_custom_preset(
-        ...     "my_style",
-        ...     base_preset="publication",
-        ...     font_size=12,
-        ...     line_width=1.5
-        ... )
-        >>> with apply_style_preset(custom):
-        ...     plot_data()
+        >>> styles = get_line_styles(4)
+        >>> for i, style in enumerate(styles):
+        ...     ax.plot(x, y[i], linestyle=style)
+    """
+    # Cycle through available styles if needed
+    return [LINE_STYLES[i % len(LINE_STYLES)] for i in range(n_lines)]
 
-    References:
-        VIS-024: Plot Style Presets with inheritance
+
+def format_pass_fail(passed: bool) -> str:
+    """Format pass/fail status with symbol.
+
+    Args:
+        passed: Test result.
+
+    Returns:
+        Formatted string with symbol.
+
+    Example:
+        >>> status = format_pass_fail(True)
+        >>> print(status)  # "✓ PASS"
     """
-    if base_preset not in PRESETS:
-        raise ValueError(f"Unknown base_preset: {base_preset}")
-
-    # Get base preset
-    base = PRESETS[base_preset]
-
-    # Create copy with overrides
-    preset_dict = {
-        "name": name,
-        "dpi": kwargs.get("dpi", base.dpi),
-        "font_family": kwargs.get("font_family", base.font_family),
-        "font_size": kwargs.get("font_size", base.font_size),
-        "line_width": kwargs.get("line_width", base.line_width),
-        "marker_size": kwargs.get("marker_size", base.marker_size),
-        "figure_facecolor": kwargs.get("figure_facecolor", base.figure_facecolor),
-        "axes_facecolor": kwargs.get("axes_facecolor", base.axes_facecolor),
-        "axes_edgecolor": kwargs.get("axes_edgecolor", base.axes_edgecolor),
-        "grid_color": kwargs.get("grid_color", base.grid_color),
-        "grid_alpha": kwargs.get("grid_alpha", base.grid_alpha),
-        "grid_linestyle": kwargs.get("grid_linestyle", base.grid_linestyle),
-        "use_latex": kwargs.get("use_latex", base.use_latex),
-        "tight_layout": kwargs.get("tight_layout", base.tight_layout),
-        "rcparams": kwargs.get("rcparams", base.rcparams.copy()),
-    }
-
-    return StylePreset(**preset_dict)
-
-
-def register_preset(preset: StylePreset) -> None:
-    """Register custom preset in global registry.
+    return f"{PASS_SYMBOL} PASS" if passed else f"{FAIL_SYMBOL} FAIL"
+
+
+def apply_presentation_style(ax: Axes) -> None:
+    """Apply presentation styling (larger fonts, thicker lines).
+
+    Optimized for slides and projection.
 
     Args:
-        preset: StylePreset to register
+        ax: Matplotlib axes to style.
 
     Example:
-        >>> custom = create_custom_preset("my_style", base_preset="publication")
-        >>> register_preset(custom)
-        >>> with apply_style_preset("my_style"):
-        ...     plot_data()
+        >>> fig, ax = plt.subplots()
+        >>> ax.plot(x, y)
+        >>> apply_presentation_style(ax)
     """
-    PRESETS[preset.name] = preset
+    if not HAS_MATPLOTLIB:
+        raise ImportError("matplotlib required for styling")
 
+    # Thicker lines and larger fonts
+    for line in ax.get_lines():
+        line.set_linewidth(2.5)
 
-def list_presets() -> list[str]:
-    """Get list of available preset names.
+    for spine in ax.spines.values():
+        spine.set_linewidth(2.0)
+
+    ax.grid(True, alpha=0.5, linestyle="-", linewidth=1.0)
+    ax.tick_params(width=2.0, labelsize=14)
+    ax.xaxis.label.set_fontsize(16)
+    ax.yaxis.label.set_fontsize(16)
+    if ax.get_title():
+        ax.title.set_fontsize(18)
+
+
+def get_multi_line_styles(num_lines: int) -> list[dict[str, str | float]]:
+    """Get distinct line styles for multiple traces on one plot.
+
+    Generates unique combinations of colors and line styles to ensure
+    visual differentiation, even for colorblind users.
+
+    Args:
+        num_lines: Number of distinct line styles needed.
 
     Returns:
-        List of preset names
+        List of style dictionaries with 'color', 'linestyle', and 'linewidth' keys.
 
     Example:
-        >>> presets = list_presets()
-        >>> print(presets)
-        ['publication', 'presentation', 'screen', 'print']
+        >>> styles = get_multi_line_styles(3)
+        >>> for i, style in enumerate(styles):
+        ...     ax.plot(x, data[i], **style, label=f"Trace {i}")
+
+    References:
+        Tol, P. (2021). Color Schemes. Technical Note SRON/EPS/TN/09-002.
     """
-    return list(PRESETS.keys())
+    if not HAS_MATPLOTLIB:
+        raise ImportError("matplotlib required for line styles")
+
+    styles: list[dict[str, str | float]] = []
+    for i in range(num_lines):
+        color_idx = i % len(COLORBLIND_PALETTE)
+        linestyle_idx = (i // len(COLORBLIND_PALETTE)) % len(LINE_STYLES)
+
+        style_dict: dict[str, str | float] = {
+            "color": COLORBLIND_PALETTE[color_idx],
+            "linestyle": LINE_STYLES[linestyle_idx],
+            "linewidth": 1.5,
+        }
+        styles.append(style_dict)
+
+    return styles
 
 
 __all__ = [
-    "PRESENTATION_PRESET",
-    "PRESETS",
-    "PRINT_PRESET",
-    "PUBLICATION_PRESET",
-    "SCREEN_PRESET",
-    "StylePreset",
-    "apply_style_preset",
-    "create_custom_preset",
-    "list_presets",
-    "register_preset",
+    "COLORBLIND_PALETTE",
+    "FAIL_SYMBOL",
+    "IEEE_STYLE",
+    "LINE_STYLES",
+    "PASS_SYMBOL",
+    "apply_ieee_style",
+    "apply_presentation_style",
+    "format_pass_fail",
+    "get_colorblind_cmap",
+    "get_colorblind_palette",
+    "get_line_styles",
+    "get_multi_line_styles",
 ]

oscura/workflows/batch/advanced.py

@@ -22,7 +22,7 @@ try:
 
     _HAS_PANDAS = True
 except ImportError:
-    pd = None  # type: ignore[assignment]
+    pd = None
     _HAS_PANDAS = False
 
 if TYPE_CHECKING:

oscura/workflows/batch/aggregate.py

@@ -296,16 +296,15 @@ def _generate_metric_plots(
     """
     try:
         import matplotlib.pyplot as plt
+    except ImportError:
+        return  # Skip if matplotlib unavailable
 
-        for metric in metrics:
-            if metric not in aggregated:
-                continue
-
-            _create_metric_plot(results, aggregated, metric, output_file)
-            plt.close()
+    for metric in metrics:
+        if metric not in aggregated:
+            continue
 
-    except ImportError:
-        pass  # Skip if matplotlib unavailable
+        _create_metric_plot(results, aggregated, metric, output_file)
+        plt.close()
 
 
 def _create_metric_plot(
@@ -340,7 +339,11 @@ def _create_metric_plot(
         plot_file.parent.mkdir(parents=True, exist_ok=True)
         plt.savefig(plot_file)
     else:
-        plt.show()
+        # Try to show, but gracefully handle non-interactive backends
+        try:
+            plt.show()
+        except Exception:
+            pass  # Silently skip if backend doesn't support interactive display
 
 
 def _plot_histogram(