scitex 2.5.0__py3-none-any.whl → 2.7.3__py3-none-any.whl

scitex/stats/_schema.py

@@ -1,578 +1,51 @@
 #!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: ./src/scitex/stats/_schema.py
+# Time-stamp: "2024-12-09 09:20:00 (ywatanabe)"
 """
-SciTeX Stats Result Schema - GUI-Ready Statistical Result Container
+Statistical Result Schema - Re-exports from central schema module.
 
-Standardized statistical test result format that integrates with:
-- scitex.plt (TrackingMixin, metadata embedding)
-- scitex.vis (JSON serialization, FigureModel)
-- scitex-cloud GUI (Fabric.js canvas, properties panel, positioning)
+This module re-exports all schema classes from scitex.schema._stats
+for backward compatibility. The canonical definitions now live in
+scitex.schema._stats as the single source of truth.
 
-This schema supports multiple coordinate systems, units, and position modes
-to enable GUI-based adjustment while maintaining publication-ready output.
-"""
-
-from dataclasses import dataclass, field, asdict
-from typing import Optional, Dict, Any, List, Literal, Union
-from datetime import datetime
-import json
-import numpy as np
-
-
-# Type aliases for clarity
-PositionMode = Literal["absolute", "relative_to_plot", "above_whisker", "auto"]
-UnitType = Literal["mm", "px", "inch", "data"]
-SymbolStyle = Literal["asterisk", "text", "bracket", "compact", "detailed", "publication"]
-
-
-@dataclass
-class Position:
-    """Position specification with unit support for GUI integration."""
-
-    x: float
-    y: float
-    unit: UnitType = "mm"
-
-    # For relative positioning (GUI anchoring)
-    relative_to: Optional[str] = None  # Plot ID or "axes"
-    offset: Optional[Dict[str, float]] = None  # {"dx": 0, "dy": 0}
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary."""
-        return {
-            "x": self.x,
-            "y": self.y,
-            "unit": self.unit,
-            "relative_to": self.relative_to,
-            "offset": self.offset,
-        }
-
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> 'Position':
-        """Create from dictionary."""
-        return cls(**data)
-
-    def to_mm(self, dpi: float = 300.0) -> 'Position':
-        """Convert position to mm (for matplotlib)."""
-        if self.unit == "mm":
-            return self
-        elif self.unit == "px":
-            # Convert px to mm using DPI
-            mm_per_px = 25.4 / dpi
-            return Position(
-                x=self.x * mm_per_px,
-                y=self.y * mm_per_px,
-                unit="mm",
-                relative_to=self.relative_to,
-                offset=self.offset
-            )
-        elif self.unit == "inch":
-            # Convert inch to mm
-            return Position(
-                x=self.x * 25.4,
-                y=self.y * 25.4,
-                unit="mm",
-                relative_to=self.relative_to,
-                offset=self.offset
-            )
-        return self
-
-    def to_px(self, dpi: float = 300.0) -> 'Position':
-        """Convert position to px (for Fabric.js canvas)."""
-        mm_pos = self.to_mm(dpi)
-        px_per_mm = dpi / 25.4
-        return Position(
-            x=mm_pos.x * px_per_mm,
-            y=mm_pos.y * px_per_mm,
-            unit="px",
-            relative_to=self.relative_to,
-            offset=self.offset
-        )
-
-
-@dataclass
-class StatStyling:
-    """Styling configuration for statistical annotation display."""
-
-    # Typography
-    font_size_pt: float = 7.0
-    font_family: str = "Arial"
-    color: str = "#000000"  # Supports theme colors
-
-    # Symbol representation
-    symbol_style: SymbolStyle = "asterisk"
-
-    # For bracket-style comparisons
-    line_width_mm: Optional[float] = None
-    bracket_height_mm: Optional[float] = None
-
-    # Theme support
-    theme: Literal["light", "dark", "auto"] = "auto"
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary."""
-        return asdict(self)
-
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> 'StatStyling':
-        """Create from dictionary."""
-        return cls(**data)
-
-    def get_theme_color(self, is_dark: bool = False) -> str:
-        """Get appropriate color for theme."""
-        if self.theme == "auto":
-            return "#ffffff" if is_dark else "#000000"
-        elif self.theme == "dark":
-            return "#ffffff"
-        elif self.theme == "light":
-            return "#000000"
-        return self.color
-
-
-@dataclass
-class StatPositioning:
-    """Position configuration for GUI-ready annotation placement."""
-
-    mode: PositionMode = "auto"
-    position: Optional[Position] = None
-
-    # GUI hints for smart positioning
-    preferred_corner: Optional[str] = None  # "top-right", "bottom-left", etc.
-    avoid_overlap: bool = True
-    min_distance_mm: float = 2.0  # Minimum distance from plot elements
-
-    # Anchoring (for relative positioning)
-    anchor_to: Optional[str] = None  # "plot_center", "whisker_top", etc.
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary."""
-        return {
-            "mode": self.mode,
-            "position": self.position.to_dict() if self.position else None,
-            "preferred_corner": self.preferred_corner,
-            "avoid_overlap": self.avoid_overlap,
-            "min_distance_mm": self.min_distance_mm,
-            "anchor_to": self.anchor_to,
-        }
-
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> 'StatPositioning':
-        """Create from dictionary."""
-        data_copy = data.copy()
-        if data_copy.get("position"):
-            data_copy["position"] = Position.from_dict(data_copy["position"])
-        return cls(**data_copy)
-
-
-@dataclass
-class StatResult:
-    """
-    Standardized statistical test result with GUI-ready metadata.
-
-    This schema integrates with:
-    - scitex.plt: Automatic annotation via TrackingMixin
-    - scitex.vis: JSON serialization for FigureModel
-    - scitex-cloud GUI: Fabric.js canvas positioning and properties panel
-
-    Examples
-    --------
-    >>> # Create from test result
-    >>> result = StatResult(
-    ...     test_type="pearson",
-    ...     test_category="correlation",
-    ...     statistic={"name": "r", "value": 0.85},
-    ...     p_value=0.001,
-    ...     stars="***"
-    ... )
-
-    >>> # Add positioning for GUI
-    >>> result.positioning = StatPositioning(
-    ...     mode="relative_to_plot",
-    ...     position=Position(x=5, y=10, unit="mm", relative_to="plot_0")
-    ... )
-
-    >>> # Export to JSON
-    >>> json_str = result.to_json()
-
-    >>> # Format for display
-    >>> text = result.format_text(style="compact")
-    >>> # "r = 0.850***"
-    """
-
-    # Core test information
-    test_type: str  # "t-test", "pearson", "anova", etc.
-    test_category: str  # "parametric", "non-parametric", "correlation"
-
-    # Primary results
-    statistic: Dict[str, Union[float, str]]  # {"name": "t", "value": 3.45}
-    p_value: float
-    stars: str  # "***", "**", "*", "ns", ""
-
-    # Effect size (optional)
-    effect_size: Optional[Dict[str, Any]] = None
-    # Example: {"name": "cohens_d", "value": 0.85,
-    #           "interpretation": "large", "ci_95": [0.42, 1.28]}
-
-    # Multiple comparison correction (optional)
-    correction: Optional[Dict[str, Any]] = None
-    # Example: {"method": "bonferroni", "n_comparisons": 10,
-    #           "corrected_p": 0.010, "alpha": 0.05}
-
-    # Sample information
-    samples: Optional[Dict[str, Any]] = None
-    # Example: {"group1": {"n": 30, "mean": 5.2, "std": 1.1},
-    #           "group2": {"n": 32, "mean": 6.8, "std": 1.3}}
-
-    # Statistical assumptions testing
-    assumptions: Optional[Dict[str, Dict]] = None
-    # Example: {"normality": {"test": "shapiro", "passed": True, "p": 0.23},
-    #           "homogeneity": {"test": "levene", "passed": True, "p": 0.45}}
-
-    # Confidence intervals
-    ci_95: Optional[List[float]] = None
-    # Example: [0.42, 1.28] for effect size or correlation
-
-    # GUI-ready positioning
-    positioning: Optional[StatPositioning] = None
-
-    # Display styling
-    styling: Optional[StatStyling] = None
-
-    # Additional test-specific data
-    extra: Optional[Dict[str, Any]] = None
-    # For test-specific outputs (degrees of freedom, test alternatives, etc.)
-
-    # Metadata
-    created_at: Optional[str] = None
-    software_version: Optional[str] = None
-    plot_id: Optional[str] = None  # Associated plot in TrackingMixin
-
-    def __post_init__(self):
-        """Initialize default values."""
-        if self.created_at is None:
-            self.created_at = datetime.now().isoformat()
-
-        if self.styling is None:
-            self.styling = StatStyling()
-
-        if self.positioning is None:
-            self.positioning = StatPositioning()
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary for JSON serialization.
-
-        Returns
-        -------
-        dict
-            Dictionary representation with nested objects converted
-        """
-        data = asdict(self)
+Note: New code should import directly from scitex.schema:
+    from scitex.schema import StatResult, Position, StatStyling
 
-        # Convert numpy types to native Python types
-        def convert_numpy(obj):
-            if isinstance(obj, np.integer):
-                return int(obj)
-            elif isinstance(obj, np.floating):
-                return float(obj)
-            elif isinstance(obj, np.ndarray):
-                return obj.tolist()
-            elif isinstance(obj, dict):
-                return {k: convert_numpy(v) for k, v in obj.items()}
-            elif isinstance(obj, list):
-                return [convert_numpy(item) for item in obj]
-            return obj
-
-        return convert_numpy(data)
-
-    def to_json(self, indent: int = 2) -> str:
-        """
-        Convert to JSON string.
-
-        Parameters
-        ----------
-        indent : int
-            Number of spaces for indentation (default: 2)
-
-        Returns
-        -------
-        str
-            JSON string representation
-        """
-        return json.dumps(self.to_dict(), indent=indent)
-
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> 'StatResult':
-        """
-        Create from dictionary.
-
-        Parameters
-        ----------
-        data : dict
-            Dictionary representation
-
-        Returns
-        -------
-        StatResult
-            StatResult instance
-        """
-        data_copy = data.copy()
-
-        # Convert nested objects
-        if "positioning" in data_copy and data_copy["positioning"]:
-            data_copy["positioning"] = StatPositioning.from_dict(
-                data_copy["positioning"]
-            )
-
-        if "styling" in data_copy and data_copy["styling"]:
-            data_copy["styling"] = StatStyling.from_dict(data_copy["styling"])
-
-        return cls(**data_copy)
-
-    @classmethod
-    def from_json(cls, json_str: str) -> 'StatResult':
-        """
-        Create from JSON string.
-
-        Parameters
-        ----------
-        json_str : str
-            JSON string representation
-
-        Returns
-        -------
-        StatResult
-            StatResult instance
-        """
-        return cls.from_dict(json.loads(json_str))
-
-    def format_text(self, style: str = "compact") -> str:
-        """
-        Format statistical result as text for display.
-
-        Parameters
-        ----------
-        style : str
-            Formatting style. Options:
-            - "compact": "r = 0.850***"
-            - "asterisk": "***" (stars only)
-            - "text": "p = 0.001"
-            - "detailed": "r = 0.850, p = 1.000e-03, d = 1.23"
-            - "publication": "(r = 0.85, p < 0.001)"
-            - "bracket": For bracket-style display (returns empty string)
-
-        Returns
-        -------
-        str
-            Formatted text
-
-        Examples
-        --------
-        >>> result.format_text("compact")
-        'r = 0.850***'
-
-        >>> result.format_text("publication")
-        '(r = 0.85, p < 0.001)'
-        """
-        stat_name = self.statistic.get("name", "stat")
-        stat_value = self.statistic.get("value", 0.0)
-
-        if style == "compact":
-            return f"{stat_name} = {stat_value:.3f}{self.stars}"
-
-        elif style == "asterisk":
-            return self.stars if self.stars != "ns" else "ns"
-
-        elif style == "text":
-            return f"p = {self.p_value:.3f}"
-
-        elif style == "detailed":
-            parts = [f"{stat_name} = {stat_value:.3f}"]
-            parts.append(f"p = {self.p_value:.3e}")
-
-            if self.effect_size:
-                es_name = self.effect_size.get("name", "d")
-                es_value = self.effect_size.get("value", 0.0)
-                parts.append(f"{es_name} = {es_value:.2f}")
-
-            return ", ".join(parts)
-
-        elif style == "publication":
-            p_text = self._format_p_publication()
-            return f"({stat_name} = {stat_value:.2f}, {p_text})"
-
-        elif style == "bracket":
-            # For bracket display, return stars only
-            return self.stars if self.stars != "ns" else ""
-
-        return f"{stat_name} = {stat_value:.3f}{self.stars}"
-
-    def _format_p_publication(self) -> str:
-        """
-        Format p-value for publication style.
-
-        Returns
-        -------
-        str
-            Formatted p-value like "p < 0.001" or "p = 0.023"
-        """
-        if self.p_value < 0.001:
-            return "p < 0.001"
-        elif self.p_value < 0.01:
-            return "p < 0.01"
-        elif self.p_value < 0.05:
-            return "p < 0.05"
-        else:
-            return f"p = {self.p_value:.3f}"
-
-    def get_interpretation(self) -> str:
-        """
-        Get human-readable interpretation of results.
-
-        Returns
-        -------
-        str
-            Interpretation text
-
-        Examples
-        --------
-        >>> result.get_interpretation()
-        'Strong positive correlation (r=0.85, p<0.001)'
-        """
-        if self.test_category == "correlation":
-            r = self.statistic.get("value", 0)
-            direction = "positive" if r > 0 else "negative"
-
-            if abs(r) > 0.7:
-                strength = "Strong"
-            elif abs(r) > 0.5:
-                strength = "Moderate"
-            elif abs(r) > 0.3:
-                strength = "Weak"
-            else:
-                strength = "Very weak"
-
-            sig = "significant" if self.stars and self.stars != "ns" else "non-significant"
-
-            return (
-                f"{strength} {direction} correlation "
-                f"({self.statistic['name']}={r:.2f}, {self._format_p_publication()}, {sig})"
-            )
-
-        elif "test" in self.test_type.lower():
-            sig = "Significant" if self.stars and self.stars != "ns" else "Non-significant"
-            return (
-                f"{sig} difference "
-                f"({self.statistic['name']}={self.statistic['value']:.2f}, "
-                f"{self._format_p_publication()})"
-            )
-
-        return f"Test result: {self.format_text('publication')}"
-
-    def to_annotation_dict(self) -> Dict[str, Any]:
-        """
-        Convert to annotation dictionary for GUI integration.
-
-        This format matches the scitex-cloud GUI Annotation interface.
-
-        Returns
-        -------
-        dict
-            Annotation dictionary compatible with TypeScript Annotation interface
-
-        Examples
-        --------
-        >>> ann = result.to_annotation_dict()
-        >>> ann["type"]
-        'stat'
-        >>> ann["statResult"]["p_value"]
-        0.001
-        """
-        return {
-            "id": self.plot_id or f"stat_{id(self)}",
-            "type": "stat",
-            "label": f"{self.test_type} result",
-            "content": self.format_text(style=self.styling.symbol_style if self.styling else "compact"),
-            "position": self.positioning.position.to_dict() if self.positioning and self.positioning.position else None,
-            "statResult": {
-                "id": self.plot_id or f"stat_{id(self)}",
-                "test_name": self.test_type,
-                "p_value": self.p_value,
-                "effect_size": self.effect_size.get("value") if self.effect_size else None,
-                "group1": self.samples.get("group1", {}).get("name") if self.samples else None,
-                "group2": self.samples.get("group2", {}).get("name") if self.samples else None,
-                "statistic": self.statistic.get("value"),
-                "method": self.test_type,
-                "formatted_output": self.format_text(style=self.styling.symbol_style if self.styling else "compact"),
-            },
-            "positioning": self.positioning.to_dict() if self.positioning else None,
-            "styling": self.styling.to_dict() if self.styling else None,
-        }
-
-
-# Convenience function for backward compatibility
-def create_stat_result(
-    test_type: str,
-    statistic_name: str,
-    statistic_value: float,
-    p_value: float,
-    **kwargs
-) -> StatResult:
-    """
-    Create a StatResult with minimal required fields.
-
-    Parameters
-    ----------
-    test_type : str
-        Type of statistical test
-    statistic_name : str
-        Name of the test statistic (e.g., "t", "r", "F")
-    statistic_value : float
-        Value of the test statistic
-    p_value : float
-        P-value from the test
-    **kwargs
-        Additional fields for StatResult
-
-    Returns
-    -------
-    StatResult
-        Configured StatResult instance
-
-    Examples
-    --------
-    >>> result = create_stat_result(
-    ...     test_type="pearson",
-    ...     statistic_name="r",
-    ...     statistic_value=0.85,
-    ...     p_value=0.001
-    ... )
-    """
-    from scitex.stats.utils import p2stars
-
-    # Determine category from test type
-    category_map = {
-        "pearson": "correlation",
-        "spearman": "correlation",
-        "kendall": "correlation",
-        "t-test": "parametric",
-        "anova": "parametric",
-        "mannwhitney": "non-parametric",
-        "kruskal": "non-parametric",
-    }
-
-    test_category = category_map.get(test_type.lower(), "other")
-
-    # Get stars
-    stars = p2stars(p_value, ns_symbol=False)
+This module exists for backward compatibility with existing code that
+imports from scitex.stats._schema.
+"""
 
-    return StatResult(
-        test_type=test_type,
-        test_category=test_category,
-        statistic={"name": statistic_name, "value": statistic_value},
-        p_value=p_value,
-        stars=stars,
-        **kwargs
-    )
+# Re-export everything from the central schema module
+from scitex.schema._stats import (
+    # Type aliases
+    PositionMode,
+    UnitType,
+    SymbolStyle,
+    # Position and styling
+    Position,
+    StatStyling,
+    StatPositioning,
+    # Main result class
+    StatResult,
+    # Convenience function
+    create_stat_result,
+)
+
+__all__ = [
+    # Type aliases
+    "PositionMode",
+    "UnitType",
+    "SymbolStyle",
+    # Position and styling
+    "Position",
+    "StatStyling",
+    "StatPositioning",
+    # Main result class
+    "StatResult",
+    # Convenience function
+    "create_stat_result",
+]
 
 
 # EOF