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

scitex/stats/tests/correlation/_test_pearson.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-11-29 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/stats/tests/correlation/_test_pearson.py
+
+"""
+Pearson correlation test with publication-ready output.
+
+Functionalities:
+  - Compute Pearson correlation coefficient and p-value
+  - Calculate confidence intervals using Fisher's z-transformation
+  - Optional scatter plot with regression line and statistics
+  - Return standardized result dictionary
+
+Dependencies:
+  - packages: numpy, pandas, scipy
+
+IO:
+  - input: Two continuous variables (arrays or Series)
+  - output: Correlation result dictionary with r, p-value, CI
+"""
+
+import argparse
+from typing import Optional, Union, Tuple
+
+import numpy as np
+import pandas as pd
+from scipy import stats as scipy_stats
+
+import scitex as stx
+from scitex.logging import getLogger
+
+logger = getLogger(__name__)
+
+
+def test_pearson(
+    x: Union[np.ndarray, pd.Series],
+    y: Union[np.ndarray, pd.Series],
+    var_x: Optional[str] = None,
+    var_y: Optional[str] = None,
+    alpha: float = 0.05,
+    plot: bool = False,
+    **plot_kwargs
+) -> Union['StatResult', Tuple['StatResult', 'matplotlib.figure.Figure']]:
+    """
+    Pearson correlation test for linear relationship between two continuous variables.
+
+    Parameters
+    ----------
+    x : array or Series
+        First variable (continuous)
+    y : array or Series
+        Second variable (continuous)
+    var_x : str, optional
+        Name of first variable for display
+    var_y : str, optional
+        Name of second variable for display
+    alpha : float, default 0.05
+        Significance level for confidence intervals
+    plot : bool, default False
+        Whether to create scatter plot with regression line
+    **plot_kwargs
+        Additional arguments passed to plotting function
+
+    Returns
+    -------
+    result : StatResult
+        StatResult instance containing:
+        - statistic: Pearson's r coefficient
+        - p_value: Two-tailed p-value
+        - stars: Significance stars (*, **, ***, ns)
+        - ci_95: Confidence interval [lower, upper]
+        - effect_size: R² and interpretation
+        - samples: Sample information
+        Access as attributes or use .to_dict() for dictionary
+    fig : matplotlib.figure.Figure, optional
+        Figure object if plot=True
+
+    Notes
+    -----
+    Pearson correlation coefficient r is calculated as:
+
+    .. math::
+        r = \\frac{\\sum_{i=1}^{n}(x_i - \\bar{x})(y_i - \\bar{y})}{\\sqrt{\\sum_{i=1}^{n}(x_i - \\bar{x})^2 \\sum_{i=1}^{n}(y_i - \\bar{y})^2}}
+
+    Confidence intervals use Fisher's z-transformation:
+
+    .. math::
+        z = 0.5 \\ln\\left(\\frac{1+r}{1-r}\\right)
+
+    Interpretation guidelines (Cohen, 1988):
+    - |r| < 0.1: Negligible
+    - |r| < 0.3: Small
+    - |r| < 0.5: Medium
+    - |r| ≥ 0.5: Large
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scitex.stats.tests.correlation import test_pearson
+    >>>
+    >>> # Generate correlated data
+    >>> np.random.seed(42)
+    >>> x = np.random.randn(100)
+    >>> y = 2 * x + np.random.randn(100) * 0.5
+    >>>
+    >>> # Basic usage
+    >>> result = test_pearson(x, y)
+    >>> print(f"r = {result.statistic['value']:.3f}, p = {result.p_value:.3e}")
+    >>>
+    >>> # With variable names and plot
+    >>> result, fig = test_pearson(
+    ...     x, y,
+    ...     var_x='Height',
+    ...     var_y='Weight',
+    ...     plot=True
+    ... )
+    >>>
+    >>> # Check significance
+    >>> if result.p_value < 0.05:
+    ...     print(f"Significant correlation: r = {result.statistic['value']:.3f}{result.stars}")
+    >>>
+    >>> # Use as dictionary (backward compatibility)
+    >>> result_dict = result.to_dict()
+    >>> print(result_dict['statistic']['value'])
+    """
+    from scitex.stats.utils._formatters import p2stars
+    from scitex.stats._schema import StatResult
+
+    # Convert to numpy arrays and remove NaN
+    x = np.asarray(x)
+    y = np.asarray(y)
+
+    # Check for matching lengths
+    if len(x) != len(y):
+        raise ValueError(f"x and y must have same length (got {len(x)} and {len(y)})")
+
+    # Remove NaN pairs
+    mask = ~(np.isnan(x) | np.isnan(y))
+    x_clean = x[mask]
+    y_clean = y[mask]
+    n = len(x_clean)
+
+    if n < 3:
+        raise ValueError(f"Need at least 3 valid pairs (got {n})")
+
+    # Compute Pearson correlation
+    r, p_value = scipy_stats.pearsonr(x_clean, y_clean)
+
+    # Calculate confidence interval using Fisher's z-transformation
+    z = np.arctanh(r)  # Fisher's z = 0.5 * ln((1+r)/(1-r))
+    se = 1 / np.sqrt(n - 3)  # Standard error of z
+    z_crit = scipy_stats.norm.ppf(1 - alpha/2)  # Critical value for two-tailed test
+
+    ci_lower_z = z - z_crit * se
+    ci_upper_z = z + z_crit * se
+
+    # Transform back to r scale
+    ci_lower = np.tanh(ci_lower_z)
+    ci_upper = np.tanh(ci_upper_z)
+
+    # Convert p-value to stars
+    stars = p2stars(p_value, ns_symbol=False)
+    if not stars:
+        stars = 'ns'
+
+    # Calculate R²
+    r_squared = r ** 2
+
+    # Interpret effect size
+    r_abs = abs(r)
+    if r_abs < 0.1:
+        interpretation = "negligible"
+    elif r_abs < 0.3:
+        interpretation = "small"
+    elif r_abs < 0.5:
+        interpretation = "medium"
+    else:
+        interpretation = "large"
+
+    # Set variable names
+    if var_x is None:
+        var_x = 'X'
+    if var_y is None:
+        var_y = 'Y'
+
+    # Build StatResult instance
+    result = StatResult(
+        test_type='pearson',
+        test_category='correlation',
+        statistic={'name': 'r', 'value': r},
+        p_value=p_value,
+        stars=stars,
+        effect_size={
+            'name': 'r_squared',
+            'value': r_squared,
+            'interpretation': interpretation,
+            'ci_95': [ci_lower, ci_upper]
+        },
+        samples={
+            'n_total': n,
+            'n_valid': n,
+            'var_x': var_x,
+            'var_y': var_y
+        },
+        ci_95=[ci_lower, ci_upper],
+        extra={
+            'test': 'Pearson correlation',
+            'ci_level': 1 - alpha,
+            'method': 'pearson',
+            'alpha': alpha
+        },
+        software_version=stx.__version__
+    )
+
+    # Create plot if requested
+    if plot:
+        fig = _plot_pearson(x_clean, y_clean, result, **plot_kwargs)
+        return result, fig
+
+    return result
+
+
+def _plot_pearson(
+    x: np.ndarray,
+    y: np.ndarray,
+    result: 'StatResult',
+    **kwargs
+) -> 'matplotlib.figure.Figure':
+    """
+    Create scatter plot with regression line for Pearson correlation.
+
+    Internal function called by test_pearson when plot=True.
+    """
+    # Create figure
+    fig, ax = stx.plt.subplots(**stx.plt.presets.SCITEX_STYLE)
+
+    # Scatter plot
+    scatter = ax.scatter(x, y, alpha=0.6, c="steelblue", label="Data")
+    stx.plt.ax.style_scatter(scatter, size_mm=0.8)
+
+    # Add fitted line with statistics
+    stx.plt.ax.add_fitted_line(
+        ax, x, y,
+        color='black',
+        linestyle='--',
+        label='Fit',
+        show_stats=True
+    )
+
+    # Labels
+    var_x = result.samples.get('var_x', 'X')
+    var_y = result.samples.get('var_y', 'Y')
+    ax.set_xlabel(stx.plt.ax.format_label(var_x, ""))
+    ax.set_ylabel(stx.plt.ax.format_label(var_y, ""))
+    ax.set_title(f"Pearson Correlation (r = {result.statistic['value']:.3f}{result.stars})")
+    ax.legend(frameon=False, fontsize=6)
+
+    return fig
+
+
+# EOF

scitex/vis/__init__.py

@@ -54,6 +54,7 @@ from . import model
 from . import backend
 from . import io
 from . import utils
+from . import editor
 
 # Convenient top-level imports for common use cases
 from .model import FigureModel, AxesModel, PlotModel, GuideModel, AnnotationModel
@@ -79,12 +80,17 @@ from .utils import (
     NATURE_DOUBLE_COLUMN_MM,
 )
 
+from .editor import edit
+
 __all__ = [
     # Submodules
     "model",
     "backend",
     "io",
     "utils",
+    "editor",
+    # Editor
+    "edit",
     # Models
     "FigureModel",
     "AxesModel",

scitex/vis/editor/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: ./src/scitex/vis/editor/__init__.py
+"""
+SciTeX Visual Editor Module
+
+Provides interactive GUI for editing figure styles and annotations.
+Supports multiple backends with graceful degradation:
+  - web: Browser-based (Flask/FastAPI) - modern UI
+  - dearpygui: GPU-accelerated desktop (fast)
+  - qt: Rich desktop (PyQt/PySide)
+  - tkinter: Built-in Python (works everywhere)
+  - mpl: Minimal matplotlib (always works)
+"""
+
+from ._edit import edit, save_manual_overrides
+
+__all__ = [
+    "edit",
+    "save_manual_overrides",
+]
+
+# EOF

scitex/vis/editor/_defaults.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: ./src/scitex/vis/editor/_defaults.py
+"""Default style settings for SciTeX visual editor."""
+
+
+def get_scitex_defaults():
+    """
+    Get default style values based on SciTeX publication standards.
+
+    Returns
+    -------
+    dict
+        Dictionary of default style settings
+    """
+    return {
+        # Font sizes (from _configure_mpl.py)
+        'fontsize': 7,           # Base font size for publication
+        'title_fontsize': 8,     # Title size
+        'axis_fontsize': 7,      # Axis label size
+        'tick_fontsize': 7,      # Tick label size
+        'legend_fontsize': 6,    # Legend font size
+
+        # Line settings (in points, 1mm = 2.83465pt)
+        'linewidth': 0.57,       # Default line width (0.2mm)
+
+        # Tick settings
+        'n_ticks': 4,            # Number of ticks
+        'tick_length': 0.8,      # Tick length in mm
+        'tick_width': 0.2,       # Tick width in mm
+        'tick_direction': 'out', # Tick direction
+
+        # Axes settings
+        'axis_width': 0.2,       # Spine/axes line width in mm
+        'hide_top_spine': True,  # Hide top spine
+        'hide_right_spine': True,  # Hide right spine
+
+        # Grid settings
+        'grid': False,           # Grid off by default
+        'grid_linewidth': 0.6,
+        'grid_alpha': 0.3,
+
+        # Figure settings
+        'dpi': 300,              # Default DPI
+        'fig_size': [3.15, 2.68],  # Default figure size in inches
+
+        # Colors (SciTeX defaults)
+        'facecolor': '#ffffff',  # White background
+        'transparent': True,     # Transparent background
+
+        # Legend
+        'legend_visible': True,
+        'legend_frameon': False,
+        'legend_loc': 'best',
+
+        # Font family
+        'font_family': 'Arial',  # Sans-serif for publication
+
+        # Annotations
+        'annotations': [],
+    }
+
+
+def get_scitex_colors():
+    """
+    Get SciTeX color palette.
+
+    Returns
+    -------
+    dict
+        Dictionary of named colors with hex values
+    """
+    # Based on scitex.plt.color.PARAMS
+    return {
+        'blue': '#1f77b4',
+        'orange': '#ff7f0e',
+        'green': '#2ca02c',
+        'red': '#d62728',
+        'purple': '#9467bd',
+        'brown': '#8c564b',
+        'pink': '#e377c2',
+        'gray': '#7f7f7f',
+        'olive': '#bcbd22',
+        'cyan': '#17becf',
+        # Additional publication colors
+        'black': '#000000',
+        'white': '#ffffff',
+        'dark_gray': '#404040',
+        'light_gray': '#d0d0d0',
+    }
+
+
+def extract_defaults_from_metadata(metadata):
+    """
+    Extract style defaults from loaded figure metadata.
+
+    Parameters
+    ----------
+    metadata : dict
+        Figure metadata loaded from JSON
+
+    Returns
+    -------
+    dict
+        Dictionary of style values extracted from metadata
+    """
+    defaults = get_scitex_defaults()
+
+    if not metadata:
+        return defaults
+
+    # Extract from scitex section (new format)
+    scitex_meta = metadata.get('scitex', {})
+    style_mm = scitex_meta.get('style_mm', {})
+
+    # Font sizes from style_mm
+    if 'axis_font_size_pt' in style_mm:
+        defaults['axis_fontsize'] = style_mm['axis_font_size_pt']
+    if 'tick_font_size_pt' in style_mm:
+        defaults['tick_fontsize'] = style_mm['tick_font_size_pt']
+    if 'title_font_size_pt' in style_mm:
+        defaults['title_fontsize'] = style_mm['title_font_size_pt']
+    if 'legend_font_size_pt' in style_mm:
+        defaults['legend_fontsize'] = style_mm['legend_font_size_pt']
+
+    # Line/axis thickness from metadata (in mm)
+    if 'trace_thickness_mm' in style_mm:
+        defaults['linewidth'] = style_mm['trace_thickness_mm'] * 2.83465  # mm to pt
+    if 'axis_thickness_mm' in style_mm:
+        defaults['axis_width'] = style_mm['axis_thickness_mm']
+    if 'tick_length_mm' in style_mm:
+        defaults['tick_length'] = style_mm['tick_length_mm']
+    if 'tick_thickness_mm' in style_mm:
+        defaults['tick_width'] = style_mm['tick_thickness_mm']
+    if 'n_ticks' in style_mm:
+        defaults['n_ticks'] = style_mm['n_ticks']
+
+    # Dimensions from metadata
+    dimensions = metadata.get('dimensions', {})
+    if 'dpi' in dimensions:
+        defaults['dpi'] = dimensions['dpi']
+    if 'figure_size_inch' in dimensions:
+        defaults['fig_size'] = dimensions['figure_size_inch']
+
+    # Axis labels from metadata
+    if 'xlabel' in metadata:
+        defaults['xlabel'] = metadata['xlabel']
+    if 'ylabel' in metadata:
+        defaults['ylabel'] = metadata['ylabel']
+    if 'title' in metadata:
+        defaults['title'] = metadata['title']
+
+    # Try to extract from axes if present
+    axes = metadata.get('axes', {})
+    if isinstance(axes, dict):
+        # New format: {'x': {'label': ...}, 'y': {'label': ...}}
+        x_axis = axes.get('x', {})
+        y_axis = axes.get('y', {})
+        if 'label' in x_axis:
+            unit = x_axis.get('unit', '')
+            label = x_axis['label']
+            if unit:
+                defaults['xlabel'] = f"{label} [{unit}]"
+            else:
+                defaults['xlabel'] = label
+        if 'label' in y_axis:
+            unit = y_axis.get('unit', '')
+            label = y_axis['label']
+            if unit:
+                defaults['ylabel'] = f"{label} [{unit}]"
+            else:
+                defaults['ylabel'] = label
+        # Extract axis limits
+        if 'lim' in x_axis:
+            defaults['xlim'] = x_axis['lim']
+        if 'lim' in y_axis:
+            defaults['ylim'] = y_axis['lim']
+    elif isinstance(axes, list) and len(axes) > 0:
+        # Legacy format: list of axes
+        ax = axes[0]
+        if 'xlabel' in ax:
+            defaults['xlabel'] = ax['xlabel']
+        if 'ylabel' in ax:
+            defaults['ylabel'] = ax['ylabel']
+        if 'title' in ax:
+            defaults['title'] = ax['title']
+        if 'grid' in ax:
+            defaults['grid'] = ax['grid']
+
+    # Extract traces information
+    traces = metadata.get('traces', [])
+    if traces:
+        defaults['traces'] = traces
+
+    # Extract legend information
+    legend = metadata.get('legend', {})
+    if legend:
+        defaults['legend_visible'] = legend.get('visible', True)
+        defaults['legend_frameon'] = legend.get('frameon', False)
+        defaults['legend_loc'] = legend.get('loc', 'best')
+
+    return defaults
+
+
+# EOF