scitex 2.13.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/plt/_figrecipe_integration.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-12 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/plt/_figrecipe_integration.py
+"""Figrecipe integration for scitex.plt (graph visualization, editor)."""
+
+from typing import Any, Callable, Dict, Optional, Union
+
+try:
+    import figrecipe as fr
+    from figrecipe._graph import draw_graph as _fr_draw_graph
+
+    _AVAILABLE = True
+except ImportError:
+    _AVAILABLE = False
+
+
+def draw_graph(
+    ax,
+    G,
+    *,
+    layout: str = "spring",
+    pos: Optional[Dict] = None,
+    seed: int = 42,
+    node_size: Union[str, Callable, float] = 100,
+    node_color: Union[str, Callable, Any] = "#3498db",
+    node_alpha: float = 0.8,
+    edge_width: Union[str, Callable, float] = 1.0,
+    edge_color: Union[str, Callable, Any] = "gray",
+    edge_alpha: float = 0.4,
+    arrows: Optional[bool] = None,
+    labels: Union[bool, Dict, str] = False,
+    font_size: float = 6,
+    colormap: str = "viridis",
+    **kwargs,
+) -> Dict[str, Any]:
+    """Draw a NetworkX graph on axes.
+
+    Parameters
+    ----------
+    ax : Axes or AxisWrapper
+        The axes to draw on.
+    G : networkx.Graph
+        The graph to draw.
+    layout : str
+        Layout: 'spring', 'circular', 'kamada_kawai', 'shell', 'hierarchical'.
+    pos : dict, optional
+        Pre-computed positions {node: (x, y)}.
+    seed : int
+        Random seed for layout.
+    node_size, node_color, node_alpha : styling
+        Node appearance settings.
+    edge_width, edge_color, edge_alpha : styling
+        Edge appearance settings.
+    arrows : bool, optional
+        Draw arrows (auto-detect if None).
+    labels : bool, dict, or str
+        Node labels.
+    font_size : float
+        Label font size (6pt default for publication).
+    colormap : str
+        Colormap for numeric node colors.
+
+    Returns
+    -------
+    dict
+        {'pos': positions, 'node_collection': ..., 'edge_collection': ...}
+    """
+    if not _AVAILABLE:
+        raise ImportError("figrecipe >= 0.13.0 required: pip install figrecipe")
+
+    # Unwrap scitex AxisWrapper
+    ax_mpl = getattr(ax, "_axis_mpl", getattr(ax, "_ax", ax))
+
+    return _fr_draw_graph(
+        ax_mpl,
+        G,
+        layout=layout,
+        pos=pos,
+        seed=seed,
+        node_size=node_size,
+        node_color=node_color,
+        node_alpha=node_alpha,
+        edge_width=edge_width,
+        edge_color=edge_color,
+        edge_alpha=edge_alpha,
+        arrows=arrows,
+        labels=labels,
+        font_size=font_size,
+        colormap=colormap,
+        **kwargs,
+    )
+
+
+def edit(source=None, style=None, port: int = 5050, **kwargs):
+    """Launch interactive GUI editor for figure styling.
+
+    Parameters
+    ----------
+    source : RecordingFigure, str, Path, or None
+        Figure object or path to .yaml recipe.
+    style : str or dict, optional
+        Style preset or dict.
+    port : int
+        Server port (default: 5050).
+    **kwargs
+        Additional args (host, open_browser, desktop, etc.)
+
+    Returns
+    -------
+    dict
+        Style overrides after editing session.
+    """
+    if not _AVAILABLE:
+        raise ImportError("figrecipe >= 0.13.0 required: pip install figrecipe")
+
+    return fr.edit(source, style=style, port=port, **kwargs)
+
+
+__all__ = ["draw_graph", "edit"]
+
+# EOF

scitex/plt/_subplots/_AxisWrapperMixins/_SeabornMixin/_wrappers.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: "2025-12-13 (ywatanabe)"
 # File: _wrappers.py - Seaborn plot wrappers
 
@@ -113,20 +112,16 @@ class SeabornWrappersMixin:
             "sns_boxplot", data=data, x=x, y=y, track=track, id=id, **kwargs
         )
 
-        # Post-processing: Style boxplot with black medians
+        # Post-processing: Style boxplot elements (0.2mm black lines)
         from scitex.plt.utils import mm_to_pt
 
         lw_pt = mm_to_pt(0.2)
-
         for line in self._axis_mpl.get_lines():
             line.set_linewidth(lw_pt)
-            xdata = line.get_xdata()
-            ydata = line.get_ydata()
-            if len(xdata) == 2 and len(ydata) == 2:
-                if ydata[0] == ydata[1]:
-                    x_span = abs(xdata[1] - xdata[0])
-                    if x_span < 0.4:
-                        line.set_color("black")
+            line.set_color("black")
+        for patch in self._axis_mpl.patches:
+            patch.set_linewidth(lw_pt)
+            patch.set_edgecolor("black")
 
         if strip:
             strip_kwargs = kwargs.copy()

scitex/plt/_subplots/_FigWrapper.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: "2025-05-19 02:53:28 (ywatanabe)"
 # File: /data/gpfs/projects/punim2354/ywatanabe/scitex_repo/src/scitex/plt/_subplots/_FigWrapper.py.new
 # ----------------------------------------
@@ -9,9 +8,9 @@ __FILE__ = "./src/scitex/plt/_subplots/_FigWrapper.py"
 __DIR__ = os.path.dirname(__FILE__)
 # ----------------------------------------
 
-from functools import wraps
 import warnings
-import numpy as np
+from functools import wraps
+
 import pandas as pd
 
 from scitex import logging
@@ -99,6 +98,10 @@ class FigWrapper:
 
         For other formats (SVG, etc.), delegates to matplotlib's savefig.
 
+        When facecolor is specified (and is not 'none'), axes with transparent
+        patches will temporarily have their alpha set to 1.0 to ensure the
+        facecolor is visible.
+
         Examples
         --------
         >>> fig, ax = splt.subplots(fig_mm={'width': 35, 'height': 24.5})
@@ -110,86 +113,135 @@ class FigWrapper:
 
         >>> # Disable metadata embedding
         >>> fig.savefig('result.png', embed_metadata=False)
-        """
-        # Check if this is a format that can have metadata (PNG/JPEG/TIFF/PDF)
-        # Handle both string paths and file-like objects (e.g., BytesIO)
-        if isinstance(fname, str):
-            is_image_format = fname.lower().endswith(
-                (".png", ".jpg", ".jpeg", ".tiff", ".tif", ".pdf")
-            )
-        else:
-            # For file-like objects, check the 'format' kwarg if provided
-            # Otherwise default to False (no metadata embedding for BytesIO etc.)
-            fmt = kwargs.get('format', '').lower() if kwargs.get('format') else ''
-            is_image_format = fmt in ('png', 'jpg', 'jpeg', 'tiff', 'tif', 'pdf')
-
-        if is_image_format and embed_metadata:
-            # Collect automatic metadata
-            auto_metadata = None
-
-            # Get first axes if available
-            # Keep the scitex AxisWrapper (for history tracking) separate from matplotlib axes
-            ax = None
-            ax_scitex = None  # scitex AxisWrapper with history
-            if hasattr(self, "axes"):
-                try:
-                    # Try to get first axes from various wrapper types
-                    if hasattr(self.axes, "_ax"):  # AxisWrapper
-                        ax = self.axes._ax
-                        ax_scitex = self.axes  # Keep the wrapper for history
-                    elif hasattr(self.axes, "_axis_mpl"):  # Alternative
-                        ax = self.axes._axis_mpl
-                        ax_scitex = self.axes
-                    elif hasattr(self.axes, "flatten"):  # AxesWrapper
-                        flat = list(self.axes.flatten())
-                        if flat and hasattr(flat[0], "_ax"):
-                            ax = flat[0]._ax
-                            ax_scitex = flat[0]  # Keep the wrapper for history
-                        elif flat and hasattr(flat[0], "_axis_mpl"):
-                            ax = flat[0]._axis_mpl
-                            ax_scitex = flat[0]
-                except Exception:
-                    pass
-
-            # If still no axes, try from figure
-            if (
-                ax is None
-                and hasattr(self._fig_mpl, "axes")
-                and len(self._fig_mpl.axes) > 0
-            ):
-                ax = self._fig_mpl.axes[0]
-
-            # Collect metadata
-            # Pass ax_scitex if available (has history for plot type detection)
-            try:
-                from scitex.plt.utils import collect_figure_metadata
-
-                auto_metadata = collect_figure_metadata(self._fig_mpl, ax_scitex if ax_scitex else ax)
-
-                # Merge with custom metadata
-                if metadata:
-                    if "custom" not in auto_metadata:
-                        auto_metadata["custom"] = {}
-                    auto_metadata["custom"].update(metadata)
-            except Exception as e:
-                # If metadata collection fails, warn but continue
-                logger.warning(f"Could not collect metadata: {e}")
-                auto_metadata = metadata
-
-            # Use scitex.io.save_image for metadata embedding
-            try:
-                from scitex.io._save_modules import save_image
 
-                save_image(
-                    self._fig_mpl, fname, metadata=auto_metadata, *args, **kwargs
+        >>> # Override transparent background with white
+        >>> fig.savefig('result.png', facecolor='white')
+        """
+        # Handle facecolor override for transparent figures
+        # When facecolor is specified (not 'none'), temporarily make axes and figure opaque
+        facecolor = kwargs.get("facecolor", None)
+        patches_backup = []  # List of (patch, original_alpha, original_facecolor)
+
+        if facecolor is not None:
+            # Check if facecolor indicates a non-transparent background
+            is_opaque_facecolor = True
+            if isinstance(facecolor, str):
+                if facecolor.lower() in ("none", "transparent"):
+                    is_opaque_facecolor = False
+
+            if is_opaque_facecolor:
+                # Backup and set figure patch to opaque
+                fig_patch = self._fig_mpl.patch
+                fig_alpha = fig_patch.get_alpha()
+                fig_fc = fig_patch.get_facecolor()
+                patches_backup.append((fig_patch, fig_alpha, fig_fc))
+                fig_patch.set_alpha(1.0)
+                fig_patch.set_facecolor(facecolor)
+
+                # Backup and set axes patches to opaque
+                for ax_mpl in self._fig_mpl.axes:
+                    ax_patch = ax_mpl.patch
+                    original_alpha = ax_patch.get_alpha()
+                    original_fc = ax_patch.get_facecolor()
+                    patches_backup.append((ax_patch, original_alpha, original_fc))
+                    ax_patch.set_alpha(1.0)
+                    # Set axes facecolor to match figure facecolor if it was transparent
+                    if original_alpha == 0.0 or original_alpha is None:
+                        ax_patch.set_facecolor(facecolor)
+
+                # Ensure transparent=False so matplotlib respects the facecolor
+                if "transparent" not in kwargs:
+                    kwargs["transparent"] = False
+        # Wrap save logic in try/finally to restore axes alpha
+        try:
+            # Check if this is a format that can have metadata (PNG/JPEG/TIFF/PDF)
+            # Handle both string paths and file-like objects (e.g., BytesIO)
+            if isinstance(fname, str):
+                is_image_format = fname.lower().endswith(
+                    (".png", ".jpg", ".jpeg", ".tiff", ".tif", ".pdf")
                 )
-            except Exception as e:
-                # Fallback to regular matplotlib savefig
-                logger.warning(f"Metadata embedding failed, using regular savefig: {e}")
+            else:
+                # For file-like objects, check the 'format' kwarg if provided
+                # Otherwise default to False (no metadata embedding for BytesIO etc.)
+                fmt = kwargs.get("format", "").lower() if kwargs.get("format") else ""
+                is_image_format = fmt in ("png", "jpg", "jpeg", "tiff", "tif", "pdf")
+
+            if is_image_format and embed_metadata:
+                # Collect automatic metadata
+                auto_metadata = None
+
+                # Get first axes if available
+                # Keep the scitex AxisWrapper (for history tracking) separate from matplotlib axes
+                ax = None
+                ax_scitex = None  # scitex AxisWrapper with history
+                if hasattr(self, "axes"):
+                    try:
+                        # Try to get first axes from various wrapper types
+                        if hasattr(self.axes, "_ax"):  # AxisWrapper
+                            ax = self.axes._ax
+                            ax_scitex = self.axes  # Keep the wrapper for history
+                        elif hasattr(self.axes, "_axis_mpl"):  # Alternative
+                            ax = self.axes._axis_mpl
+                            ax_scitex = self.axes
+                        elif hasattr(self.axes, "flatten"):  # AxesWrapper
+                            flat = list(self.axes.flatten())
+                            if flat and hasattr(flat[0], "_ax"):
+                                ax = flat[0]._ax
+                                ax_scitex = flat[0]  # Keep the wrapper for history
+                            elif flat and hasattr(flat[0], "_axis_mpl"):
+                                ax = flat[0]._axis_mpl
+                                ax_scitex = flat[0]
+                    except Exception:
+                        pass
+
+                # If still no axes, try from figure
+                if (
+                    ax is None
+                    and hasattr(self._fig_mpl, "axes")
+                    and len(self._fig_mpl.axes) > 0
+                ):
+                    ax = self._fig_mpl.axes[0]
+
+                # Collect metadata
+                # Pass ax_scitex if available (has history for plot type detection)
+                try:
+                    from scitex.plt.utils import collect_figure_metadata
+
+                    auto_metadata = collect_figure_metadata(
+                        self._fig_mpl, ax_scitex if ax_scitex else ax
+                    )
+
+                    # Merge with custom metadata
+                    if metadata:
+                        if "custom" not in auto_metadata:
+                            auto_metadata["custom"] = {}
+                        auto_metadata["custom"].update(metadata)
+                except Exception as e:
+                    # If metadata collection fails, warn but continue
+                    logger.warning(f"Could not collect metadata: {e}")
+                    auto_metadata = metadata
+
+                # Use scitex.io.save_image for metadata embedding
+                try:
+                    from scitex.io._save_modules import save_image
+
+                    save_image(
+                        self._fig_mpl, fname, metadata=auto_metadata, *args, **kwargs
+                    )
+                except Exception as e:
+                    # Fallback to regular matplotlib savefig
+                    logger.warning(
+                        f"Metadata embedding failed, using regular savefig: {e}"
+                    )
+                    self._fig_mpl.savefig(fname, *args, **kwargs)
+            else:
+                # For non-image formats or when metadata disabled, use regular savefig
                 self._fig_mpl.savefig(fname, *args, **kwargs)
-        else:
-            # For non-image formats or when metadata disabled, use regular savefig
-            self._fig_mpl.savefig(fname, *args, **kwargs)
+        finally:
+            # Restore patch alpha and facecolor values if they were modified
+            for patch, original_alpha, original_fc in patches_backup:
+                patch.set_alpha(original_alpha)
+                patch.set_facecolor(original_fc)
 
     def export_as_csv(self):
         """Export plotted data from all axes.
@@ -198,7 +250,8 @@ class FigWrapper:
         them into a single DataFrame with appropriate axis identifiers in
         the column names.
 
-        Returns:
+        Returns
+        -------
             pd.DataFrame: Combined DataFrame with data from all axes,
                           with axis ID prefixes for each column.
         """
@@ -253,8 +306,8 @@ class FigWrapper:
         This method properly handles both regular matplotlib axes and SciTeX
         AxisWrapper objects when creating colorbars.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         mappable : ScalarMappable
             The image, contour set, etc. to which the colorbar applies
         ax : Axes or AxisWrapper, optional
@@ -262,8 +315,8 @@ class FigWrapper:
         **kwargs : dict
             Additional keyword arguments passed to matplotlib's colorbar
 
-        Returns:
-        --------
+        Returns
+        -------
         Colorbar
             The created colorbar object
         """
@@ -324,7 +377,7 @@ class FigWrapper:
         for ax in self._traverse_axes():
             try:
                 ax.legend(*args, loc=loc, **kwargs)
-            except Exception as e:
+            except Exception:
                 pass
 
     def supxyt(self, x=False, y=False, t=False):
@@ -344,8 +397,6 @@ class FigWrapper:
         with tight_layout. If the figure is using constrained_layout, this
         method does nothing as constrained_layout handles spacing automatically.
         """
-        import warnings
-
         # Check if figure is already using constrained_layout
         if (
             hasattr(self._fig_mpl, "get_constrained_layout")

scitex/plt/docs/EXTERNAL_PACKAGE_BRANDING.md

@@ -0,0 +1,149 @@
+# External Package Branding Guide
+
+When scitex wraps external packages (like `figrecipe` for `scitex.plt` or `crossref-local` for `scitex.scholar`), those packages should support configurable branding so documentation and error messages show the scitex namespace.
+
+## When to Use Branding
+
+- **Use branding**: External packages that scitex wraps (figrecipe, crossref-local, etc.)
+- **Don't use branding**: Internal scitex modules (scitex.audio, scitex.stats, etc.) - just hardcode `SCITEX_*` prefix
+
+## Pattern Overview
+
+The external package provides a `_branding.py` module that:
+1. Reads brand name from environment variable
+2. Derives environment variable prefix from brand name
+3. Provides helper functions for rebranding text/docstrings
+
+## Implementation Template
+
+```python
+# external_package/_branding.py
+
+import os
+import re
+from typing import Optional
+
+# Environment variables for branding
+# Parent package sets these before importing
+BRAND_NAME = os.environ.get("{PACKAGE}_BRAND", "{package}")
+BRAND_ALIAS = os.environ.get("{PACKAGE}_ALIAS", "{alias}")
+
+# Original values for replacement
+_ORIGINAL_NAME = "{package}"
+_ORIGINAL_ALIAS = "{alias}"
+
+
+def _brand_to_env_prefix(brand: str) -> str:
+    """Convert brand name to environment variable prefix.
+
+    Examples:
+        "figrecipe" -> "FIGRECIPE"
+        "scitex.plt" -> "SCITEX_PLT"
+        "crossref-local" -> "CROSSREF_LOCAL"
+    """
+    return brand.upper().replace(".", "_").replace("-", "_")
+
+
+# Environment variable prefix based on brand
+ENV_PREFIX = _brand_to_env_prefix(BRAND_NAME)
+
+
+def get_env(key: str, default: Optional[str] = None) -> Optional[str]:
+    """Get environment variable with brand-aware prefix.
+
+    Checks {ENV_PREFIX}_{key} first, then falls back to original prefix.
+    """
+    value = os.environ.get(f"{ENV_PREFIX}_{key}")
+    if value is not None:
+        return value
+
+    # Fall back to original prefix if different
+    original_prefix = _brand_to_env_prefix(_ORIGINAL_NAME)
+    if ENV_PREFIX != original_prefix:
+        value = os.environ.get(f"{original_prefix}_{key}")
+        if value is not None:
+            return value
+
+    return default
+
+
+def rebrand_text(text: Optional[str]) -> Optional[str]:
+    """Apply branding to a text string (docstrings, error messages)."""
+    if text is None:
+        return None
+
+    if BRAND_NAME == _ORIGINAL_NAME and BRAND_ALIAS == _ORIGINAL_ALIAS:
+        return text
+
+    result = text
+
+    # Replace import statements
+    result = re.sub(
+        rf"import\s+{_ORIGINAL_NAME}\s+as\s+{_ORIGINAL_ALIAS}",
+        f"import {BRAND_NAME} as {BRAND_ALIAS}",
+        result,
+    )
+
+    # Replace "from package" statements
+    result = re.sub(
+        rf"from\s+{_ORIGINAL_NAME}(\s+import|\s*\.)",
+        lambda m: f"from {BRAND_NAME}{m.group(1)}",
+        result,
+    )
+
+    return result
+
+
+def get_mcp_server_name() -> str:
+    """Get the MCP server name based on branding."""
+    return BRAND_NAME.replace(".", "-")
+```
+
+## Usage in Parent Package (scitex)
+
+```python
+# scitex/plt/__init__.py
+import os
+
+# Set branding BEFORE importing the external package
+os.environ["FIGRECIPE_BRAND"] = "scitex.plt"
+os.environ["FIGRECIPE_ALIAS"] = "plt"
+
+# Now import - docstrings will show scitex.plt instead of figrecipe
+from figrecipe import *
+```
+
+## Port Scheme
+
+SciTeX uses port scheme 3129X (sa-i-te-ku-su → 3-1-2-9 in Japanese):
+
+| Port  | Service          |
+|-------|------------------|
+| 31290 | scitex-cloud     |
+| 31291 | crossref-local   |
+| 31292 | openalex         |
+| 31293 | scitex-audio     |
+
+## Environment Variable Pattern
+
+External packages should use `{ENV_PREFIX}_{SETTING}`:
+
+```
+SCITEX_PLT_MODE=local
+CROSSREF_LOCAL_API_URL=http://localhost:31291
+SCITEX_AUDIO_RELAY_URL=http://localhost:31293
+```
+
+## Example: crossref-local
+
+See GitHub Issue: https://github.com/ywatanabe1989/crossref-local/issues/11
+
+The crossref-local package should implement:
+- `CROSSREF_LOCAL_BRAND` / `CROSSREF_LOCAL_ALIAS` env vars
+- Dynamic `ENV_PREFIX` derived from brand name
+- When used via scitex.scholar, shows `scitex.scholar` in docs
+
+## References
+
+- figrecipe/_branding.py - Reference implementation
+- scitex/audio/_branding.py - Simple internal module (no rebranding needed)

scitex/plt/gallery/README.md

@@ -1,7 +1,7 @@
 <!-- ---
 !-- Timestamp: 2025-12-08 23:59:46
 !-- Author: ywatanabe
-!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/plt/gallery/README.md
+!-- File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/gallery/README.md
 !-- --- -->
 
 # SciTeX Plot Gallery