scitex 2.14.0__py3-none-any.whl → 2.15.2__py3-none-any.whl

scitex/social/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/stats/_mcp/_handlers/__init__.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/stats/_mcp/_handlers/__init__.py
+
+"""Stats MCP handler implementations split into modules."""
+
+from ._corrections import correct_pvalues_handler
+from ._descriptive import describe_handler
+from ._effect_size import effect_size_handler
+from ._format import format_results_handler
+from ._normality import normality_test_handler
+from ._posthoc import posthoc_test_handler
+from ._power import power_analysis_handler
+from ._recommend import recommend_tests_handler
+from ._run_test import run_test_handler
+from ._stars import p_to_stars_handler
+
+__all__ = [
+    "recommend_tests_handler",
+    "run_test_handler",
+    "format_results_handler",
+    "power_analysis_handler",
+    "correct_pvalues_handler",
+    "describe_handler",
+    "effect_size_handler",
+    "normality_test_handler",
+    "posthoc_test_handler",
+    "p_to_stars_handler",
+]
+
+# EOF

scitex/stats/_mcp/_handlers/_corrections.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/stats/_mcp/_handlers/_corrections.py
+
+"""P-value correction handler for multiple comparisons."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+
+import numpy as np
+
+__all__ = ["correct_pvalues_handler"]
+
+
+async def correct_pvalues_handler(
+    pvalues: list[float],
+    method: str = "fdr_bh",
+    alpha: float = 0.05,
+) -> dict:
+    """Apply multiple comparison correction to p-values."""
+    try:
+        loop = asyncio.get_event_loop()
+
+        def do_correct():
+            from statsmodels.stats.multitest import multipletests
+
+            # Map method names
+            method_map = {
+                "bonferroni": "bonferroni",
+                "fdr_bh": "fdr_bh",
+                "fdr_by": "fdr_by",
+                "holm": "holm",
+                "sidak": "sidak",
+            }
+            sm_method = method_map.get(method, "fdr_bh")
+
+            pvals = np.array(pvalues)
+            reject, pvals_corrected, _, _ = multipletests(
+                pvals, alpha=alpha, method=sm_method
+            )
+
+            return {
+                "original_pvalues": pvalues,
+                "corrected_pvalues": pvals_corrected.tolist(),
+                "reject_null": reject.tolist(),
+                "n_significant": int(reject.sum()),
+                "n_tests": len(pvalues),
+            }
+
+        result = await loop.run_in_executor(None, do_correct)
+
+        return {
+            "success": True,
+            "method": method,
+            "alpha": alpha,
+            **result,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    except ImportError:
+        # Fallback implementation without statsmodels
+        try:
+            n = len(pvalues)
+            pvals = np.array(pvalues)
+
+            if method == "bonferroni":
+                corrected = np.minimum(pvals * n, 1.0)
+            elif method == "holm":
+                sorted_idx = np.argsort(pvals)
+                corrected = np.empty(n)
+                cummax = 0.0
+                for rank, idx in enumerate(sorted_idx, start=1):
+                    adj = min((n - rank + 1) * pvals[idx], 1.0)
+                    adj = max(adj, cummax)
+                    corrected[idx] = adj
+                    cummax = adj
+            elif method == "fdr_bh":
+                sorted_idx = np.argsort(pvals)
+                corrected = np.empty(n)
+                prev = 1.0
+                for rank in range(n, 0, -1):
+                    idx = sorted_idx[rank - 1]
+                    bh = pvals[idx] * n / rank
+                    val = min(bh, prev, 1.0)
+                    corrected[idx] = val
+                    prev = val
+            elif method == "sidak":
+                corrected = 1 - (1 - pvals) ** n
+            else:
+                corrected = pvals
+
+            return {
+                "success": True,
+                "method": method,
+                "alpha": alpha,
+                "original_pvalues": pvalues,
+                "corrected_pvalues": corrected.tolist(),
+                "reject_null": (corrected < alpha).tolist(),
+                "n_significant": int((corrected < alpha).sum()),
+                "n_tests": n,
+                "timestamp": datetime.now().isoformat(),
+            }
+
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# EOF

scitex/stats/_mcp/_handlers/_descriptive.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/stats/_mcp/_handlers/_descriptive.py
+
+"""Descriptive statistics handler."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+
+import numpy as np
+
+__all__ = ["describe_handler"]
+
+
+async def describe_handler(
+    data: list[float],
+    percentiles: list[float] | None = None,
+) -> dict:
+    """Calculate descriptive statistics for data."""
+    try:
+        loop = asyncio.get_event_loop()
+
+        def do_describe():
+            arr = np.array(data, dtype=float)
+            arr = arr[~np.isnan(arr)]  # Remove NaN
+
+            if len(arr) == 0:
+                return {"error": "No valid data points"}
+
+            percs = percentiles or [25, 50, 75]
+            percentile_values = np.percentile(arr, percs)
+
+            result = {
+                "n": int(len(arr)),
+                "mean": float(np.mean(arr)),
+                "std": float(np.std(arr, ddof=1)) if len(arr) > 1 else 0.0,
+                "var": float(np.var(arr, ddof=1)) if len(arr) > 1 else 0.0,
+                "sem": (
+                    float(np.std(arr, ddof=1) / np.sqrt(len(arr)))
+                    if len(arr) > 1
+                    else 0.0
+                ),
+                "min": float(np.min(arr)),
+                "max": float(np.max(arr)),
+                "range": float(np.max(arr) - np.min(arr)),
+                "median": float(np.median(arr)),
+                "percentiles": {
+                    str(int(p)): float(v) for p, v in zip(percs, percentile_values)
+                },
+                "iqr": float(np.percentile(arr, 75) - np.percentile(arr, 25)),
+            }
+
+            # Add skewness and kurtosis if scipy available
+            try:
+                from scipy import stats as scipy_stats
+
+                result["skewness"] = float(scipy_stats.skew(arr))
+                result["kurtosis"] = float(scipy_stats.kurtosis(arr))
+            except ImportError:
+                pass
+
+            return result
+
+        result = await loop.run_in_executor(None, do_describe)
+
+        return {
+            "success": True,
+            **result,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# EOF

scitex/stats/_mcp/_handlers/_effect_size.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/stats/_mcp/_handlers/_effect_size.py
+
+"""Effect size calculation handler."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+
+import numpy as np
+
+__all__ = ["effect_size_handler"]
+
+
+async def effect_size_handler(
+    group1: list[float],
+    group2: list[float],
+    measure: str = "cohens_d",
+    pooled: bool = True,
+) -> dict:
+    """Calculate effect size between groups."""
+    try:
+        from scitex.stats.effect_sizes import (
+            cliffs_delta,
+            cohens_d,
+            interpret_cliffs_delta,
+            interpret_cohens_d,
+        )
+
+        loop = asyncio.get_event_loop()
+
+        def do_effect_size():
+            g1 = np.array(group1, dtype=float)
+            g2 = np.array(group2, dtype=float)
+
+            result = {}
+
+            if measure == "cohens_d":
+                d = cohens_d(g1, g2)
+                result = {
+                    "measure": "Cohen's d",
+                    "value": float(d),
+                    "interpretation": interpret_cohens_d(d),
+                }
+
+            elif measure == "hedges_g":
+                # Hedges' g is Cohen's d with bias correction
+                d = cohens_d(g1, g2)
+                n1, n2 = len(g1), len(g2)
+                correction = 1 - (3 / (4 * (n1 + n2) - 9))
+                g = d * correction
+                result = {
+                    "measure": "Hedges' g",
+                    "value": float(g),
+                    "interpretation": interpret_cohens_d(g),  # Same thresholds
+                }
+
+            elif measure == "glass_delta":
+                # Glass's delta uses only control group std
+                mean_diff = np.mean(g1) - np.mean(g2)
+                delta = mean_diff / np.std(g2, ddof=1)
+                result = {
+                    "measure": "Glass's delta",
+                    "value": float(delta),
+                    "interpretation": interpret_cohens_d(delta),
+                }
+
+            elif measure == "cliffs_delta":
+                delta = cliffs_delta(g1, g2)
+                result = {
+                    "measure": "Cliff's delta",
+                    "value": float(delta),
+                    "interpretation": interpret_cliffs_delta(delta),
+                }
+
+            else:
+                raise ValueError(f"Unknown measure: {measure}")
+
+            # Add confidence interval approximation for Cohen's d
+            if measure in ["cohens_d", "hedges_g", "glass_delta"]:
+                n1, n2 = len(g1), len(g2)
+                se = np.sqrt(
+                    (n1 + n2) / (n1 * n2) + result["value"] ** 2 / (2 * (n1 + n2))
+                )
+                result["ci_lower"] = float(result["value"] - 1.96 * se)
+                result["ci_upper"] = float(result["value"] + 1.96 * se)
+
+            return result
+
+        result = await loop.run_in_executor(None, do_effect_size)
+
+        return {
+            "success": True,
+            "group1_n": len(group1),
+            "group2_n": len(group2),
+            **result,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# EOF

scitex/stats/_mcp/_handlers/_format.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/stats/_mcp/_handlers/_format.py
+
+"""Results formatting handler."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+
+__all__ = ["format_results_handler"]
+
+
+async def format_results_handler(
+    test_name: str,
+    statistic: float,
+    p_value: float,
+    df: float | None = None,
+    effect_size: float | None = None,
+    effect_size_name: str | None = None,
+    style: str = "apa",
+    ci_lower: float | None = None,
+    ci_upper: float | None = None,
+) -> dict:
+    """Format statistical results in journal style."""
+    try:
+        loop = asyncio.get_event_loop()
+
+        def do_format():
+            from scitex.stats.auto import format_test_line, p_to_stars
+            from scitex.stats.auto._formatting import EffectResultDict, TestResultDict
+
+            # Build test result dict
+            test_result: TestResultDict = {
+                "test_name": test_name,
+                "stat": statistic,
+                "p_raw": p_value,
+            }
+            if df is not None:
+                test_result["df"] = df
+
+            # Build effect result if provided
+            effects = None
+            if effect_size is not None:
+                effects = [
+                    EffectResultDict(
+                        name=effect_size_name or "d",
+                        label=effect_size_name or "Cohen's d",
+                        value=effect_size,
+                        ci_lower=ci_lower,
+                        ci_upper=ci_upper,
+                    )
+                ]
+
+            # Map style names
+            style_map = {
+                "apa": "apa_latex",
+                "nature": "nature",
+                "science": "science",
+                "brief": "brief",
+            }
+            style_id = style_map.get(style, "apa_latex")
+
+            # Format the line
+            formatted = format_test_line(
+                test_result,
+                effects=effects,
+                style=style_id,
+                include_n=False,
+            )
+
+            # Get stars representation
+            stars = p_to_stars(p_value)
+
+            return {
+                "formatted": formatted,
+                "stars": stars,
+            }
+
+        result = await loop.run_in_executor(None, do_format)
+
+        return {
+            "success": True,
+            "style": style,
+            **result,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# EOF

scitex/stats/_mcp/_handlers/_normality.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/stats/_mcp/_handlers/_normality.py
+
+"""Normality test handler."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+
+import numpy as np
+
+__all__ = ["normality_test_handler"]
+
+
+async def normality_test_handler(
+    data: list[float],
+    method: str = "shapiro",
+) -> dict:
+    """Test whether data follows a normal distribution."""
+    try:
+        from scipy import stats as scipy_stats
+
+        loop = asyncio.get_event_loop()
+
+        def do_normality():
+            arr = np.array(data, dtype=float)
+            arr = arr[~np.isnan(arr)]
+
+            if len(arr) < 3:
+                return {"error": "Need at least 3 data points"}
+
+            result = {}
+
+            if method == "shapiro":
+                stat, p_value = scipy_stats.shapiro(arr)
+                result = {
+                    "test": "Shapiro-Wilk",
+                    "statistic": float(stat),
+                    "statistic_name": "W",
+                    "p_value": float(p_value),
+                }
+
+            elif method == "dagostino":
+                if len(arr) < 8:
+                    return {"error": "D'Agostino test requires at least 8 samples"}
+                stat, p_value = scipy_stats.normaltest(arr)
+                result = {
+                    "test": "D'Agostino-Pearson",
+                    "statistic": float(stat),
+                    "statistic_name": "K2",
+                    "p_value": float(p_value),
+                }
+
+            elif method == "anderson":
+                res = scipy_stats.anderson(arr, dist="norm")
+                # Use 5% significance level
+                idx = 2  # Index for 5% level
+                result = {
+                    "test": "Anderson-Darling",
+                    "statistic": float(res.statistic),
+                    "statistic_name": "A2",
+                    "critical_value_5pct": float(res.critical_values[idx]),
+                    "normal": bool(res.statistic < res.critical_values[idx]),
+                }
+
+            elif method == "lilliefors":
+                try:
+                    from statsmodels.stats.diagnostic import lilliefors
+
+                    stat, p_value = lilliefors(arr, dist="norm")
+                    result = {
+                        "test": "Lilliefors",
+                        "statistic": float(stat),
+                        "statistic_name": "D",
+                        "p_value": float(p_value),
+                    }
+                except ImportError:
+                    return {"error": "statsmodels required for Lilliefors test"}
+
+            else:
+                raise ValueError(f"Unknown method: {method}")
+
+            # Add interpretation
+            if "p_value" in result:
+                result["is_normal"] = result["p_value"] >= 0.05
+                result["interpretation"] = (
+                    "Data appears normally distributed (p >= 0.05)"
+                    if result["is_normal"]
+                    else "Data deviates from normal distribution (p < 0.05)"
+                )
+
+            return result
+
+        result = await loop.run_in_executor(None, do_normality)
+
+        return {
+            "success": True,
+            "method": method,
+            "n": len(data),
+            **result,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+# EOF