scitex 2.7.0__py3-none-any.whl → 2.8.1__py3-none-any.whl

scitex/schema/_stats.py

@@ -10,7 +10,7 @@ Statistical Result Schema - Central Source of Truth.
 This module defines the canonical schema for statistical test results
 that integrates with:
 - scitex.plt (TrackingMixin, metadata embedding)
-- scitex.vis (JSON serialization, FigureModel)
+- scitex.fig (JSON serialization, FigureModel)
 - scitex-cloud GUI (Fabric.js canvas, properties panel, positioning)
 - scitex.bridge (cross-module adapters)
 
@@ -272,7 +272,7 @@ class StatResult:
 
     This is the central schema for statistical results that integrates with:
     - scitex.plt: Automatic annotation via TrackingMixin
-    - scitex.vis: JSON serialization for FigureModel
+    - scitex.fig: JSON serialization for FigureModel
     - scitex-cloud GUI: Fabric.js canvas positioning and properties panel
     - scitex.bridge: Cross-module adapters
 

scitex/stats/__init__.py

@@ -66,6 +66,120 @@ from .auto import (
     p_to_stars,
 )
 
+# =============================================================================
+# .statsz Bundle Support
+# =============================================================================
+
+def save_statsz(
+    comparisons,
+    path,
+    metadata=None,
+    as_zip=False,
+):
+    """
+    Save statistical results as a .statsz bundle.
+
+    Parameters
+    ----------
+    comparisons : list of dict or list of StatResult
+        List of comparison results. Each should have:
+        - name: Comparison name (e.g., "Control vs Treatment")
+        - method: Test method (e.g., "t-test")
+        - p_value: P-value
+        - effect_size: Effect size (optional)
+        - ci95: 95% confidence interval (optional)
+        - formatted: Star notation (optional)
+    path : str or Path
+        Output path (e.g., "comparison.statsz.d" or "comparison.statsz").
+    metadata : dict, optional
+        Additional metadata (n, seed, bootstrap_iters, etc.).
+    as_zip : bool, optional
+        If True, save as ZIP archive (default: False).
+
+    Returns
+    -------
+    Path
+        Path to saved bundle.
+
+    Examples
+    --------
+    >>> import scitex.stats as sstats
+    >>> comparisons = [
+    ...     {
+    ...         "name": "Control vs Treatment",
+    ...         "method": "t-test",
+    ...         "p_value": 0.003,
+    ...         "effect_size": 1.21,
+    ...         "ci95": [0.5, 1.8],
+    ...         "formatted": "**"
+    ...     }
+    ... ]
+    >>> sstats.save_statsz(comparisons, "results.statsz.d")
+    """
+    from pathlib import Path
+    from scitex.io._bundle import save_bundle, BundleType
+
+    p = Path(path)
+
+    # Convert StatResult objects to dicts if needed
+    comp_dicts = []
+    for comp in comparisons:
+        if hasattr(comp, 'to_dict'):
+            comp_dicts.append(comp.to_dict())
+        elif hasattr(comp, '__dict__'):
+            comp_dicts.append(vars(comp))
+        else:
+            comp_dicts.append(comp)
+
+    # Build spec
+    spec = {
+        'schema': {'name': 'scitex.stats.stats', 'version': '1.0.0'},
+        'comparisons': comp_dicts,
+        'metadata': metadata or {},
+    }
+
+    bundle_data = {'spec': spec}
+
+    return save_bundle(bundle_data, p, bundle_type=BundleType.STATSZ, as_zip=as_zip)
+
+
+def load_statsz(path):
+    """
+    Load a .statsz bundle.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .statsz bundle (directory or ZIP).
+
+    Returns
+    -------
+    dict
+        Stats data with:
+        - 'comparisons': List of comparison dicts
+        - 'metadata': Metadata dict
+
+    Examples
+    --------
+    >>> stats = scitex.stats.load_statsz("results.statsz.d")
+    >>> for comp in stats['comparisons']:
+    ...     print(f"{comp['name']}: p={comp['p_value']}")
+    """
+    from scitex.io._bundle import load_bundle
+
+    bundle = load_bundle(path)
+
+    if bundle['type'] != 'statsz':
+        raise ValueError(f"Not a .statsz bundle: {path}")
+
+    spec = bundle.get('spec', {})
+
+    return {
+        'comparisons': spec.get('comparisons', []),
+        'metadata': spec.get('metadata', {}),
+    }
+
+
 __all__ = [
     # Main submodules
     "auto",
@@ -95,6 +209,9 @@ __all__ = [
     "get_stat_style",
     "format_test_line",
     "p_to_stars",
+    # .statsz bundle
+    "save_statsz",
+    "load_statsz",
 ]
 
 __version__ = "2.1.0"

scitex/stats/io/__init__.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-13 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/stats/io/__init__.py
+
+"""
+I/O operations for scitex.stats - Statistical results bundles (.statsz).
+
+This module handles:
+    - .statsz bundle load/save operations
+    - Statistical comparison metadata
+    - P-value and effect size validation
+"""
+
+from ._bundle import (
+    validate_statsz_spec,
+    load_statsz_bundle,
+    save_statsz_bundle,
+    STATSZ_SCHEMA_SPEC,
+)
+
+__all__ = [
+    "validate_statsz_spec",
+    "load_statsz_bundle",
+    "save_statsz_bundle",
+    "STATSZ_SCHEMA_SPEC",
+]
+
+# EOF

scitex/stats/io/_bundle.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-13 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/stats/io/_bundle.py
+
+"""
+SciTeX .statsz Bundle I/O - Statistics-specific bundle operations.
+
+Handles:
+    - Statistical results specification validation
+    - Comparison metadata management
+    - P-value and effect size validation
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+__all__ = [
+    "validate_statsz_spec",
+    "load_statsz_bundle",
+    "save_statsz_bundle",
+    "STATSZ_SCHEMA_SPEC",
+]
+
+# Schema specification for .statsz bundles
+STATSZ_SCHEMA_SPEC = {
+    "name": "scitex.stats.stats",
+    "version": "1.0.0",
+    "required_fields": ["schema"],
+    "optional_fields": ["comparisons", "metadata", "descriptive", "test_results"],
+}
+
+
+def validate_statsz_spec(spec: Dict[str, Any]) -> List[str]:
+    """Validate .statsz-specific fields.
+
+    Args:
+        spec: The specification dictionary to validate.
+
+    Returns:
+        List of validation error messages (empty if valid).
+    """
+    errors = []
+
+    if "comparisons" in spec:
+        comparisons = spec["comparisons"]
+        if not isinstance(comparisons, list):
+            errors.append("'comparisons' must be a list")
+        else:
+            for i, comp in enumerate(comparisons):
+                if not isinstance(comp, dict):
+                    errors.append(f"comparisons[{i}] must be a dictionary")
+                    continue
+
+                # Validate p_value if present
+                if "p_value" in comp:
+                    p = comp["p_value"]
+                    if not isinstance(p, (int, float)):
+                        errors.append(f"comparisons[{i}].p_value must be numeric")
+                    elif not (0 <= p <= 1):
+                        errors.append(
+                            f"comparisons[{i}].p_value must be between 0 and 1"
+                        )
+
+                # Validate effect_size if present
+                if "effect_size" in comp:
+                    es = comp["effect_size"]
+                    if isinstance(es, dict):
+                        if "value" in es and not isinstance(es["value"], (int, float)):
+                            errors.append(
+                                f"comparisons[{i}].effect_size.value must be numeric"
+                            )
+                    elif not isinstance(es, (int, float)):
+                        errors.append(
+                            f"comparisons[{i}].effect_size must be numeric or dict"
+                        )
+
+    # Validate test_results if present
+    if "test_results" in spec:
+        test_results = spec["test_results"]
+        if not isinstance(test_results, (dict, list)):
+            errors.append("'test_results' must be a dictionary or list")
+
+    # Validate descriptive if present
+    if "descriptive" in spec:
+        descriptive = spec["descriptive"]
+        if not isinstance(descriptive, dict):
+            errors.append("'descriptive' must be a dictionary")
+
+    return errors
+
+
+def load_statsz_bundle(bundle_dir: Path) -> Dict[str, Any]:
+    """Load .statsz bundle contents from directory.
+
+    Args:
+        bundle_dir: Path to the bundle directory.
+
+    Returns:
+        Dictionary with loaded bundle contents.
+    """
+    result = {}
+
+    # Load specification
+    spec_file = bundle_dir / "stats.json"
+    if spec_file.exists():
+        with open(spec_file, "r") as f:
+            result["spec"] = json.load(f)
+    else:
+        result["spec"] = None
+
+    # Load supplementary data files if present
+    data_file = bundle_dir / "data.csv"
+    if data_file.exists():
+        try:
+            import pandas as pd
+            result["data"] = pd.read_csv(data_file)
+        except ImportError:
+            with open(data_file, "r") as f:
+                result["data"] = f.read()
+
+    return result
+
+
+def save_statsz_bundle(data: Dict[str, Any], dir_path: Path) -> None:
+    """Save .statsz bundle contents to directory.
+
+    Args:
+        data: Bundle data dictionary.
+        dir_path: Path to the bundle directory.
+    """
+    # Save specification
+    spec = data.get("spec", {})
+    spec_file = dir_path / "stats.json"
+    with open(spec_file, "w") as f:
+        json.dump(spec, f, indent=2)
+
+    # Save supplementary data if present
+    if "data" in data:
+        data_file = dir_path / "data.csv"
+        df = data["data"]
+        if hasattr(df, "to_csv"):
+            df.to_csv(data_file, index=False)
+        else:
+            with open(data_file, "w") as f:
+                f.write(str(df))
+
+    # Save summary report if present
+    if "report" in data:
+        report_file = dir_path / "report.md"
+        with open(report_file, "w") as f:
+            f.write(data["report"])
+
+
+# EOF

scitex/tex/__init__.py

@@ -1,10 +1,14 @@
 #!/usr/bin/env python3
 """LaTeX utilities module for scitex."""
 
+from ._export import export_tex, compile_tex, CompileResult
 from ._preview import preview
 from ._to_vec import to_vec
 
 __all__ = [
+    "export_tex",
+    "compile_tex",
+    "CompileResult",
     "preview",
     "to_vec",
 ]