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

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

scitex/stats/_mcp/_handlers/_posthoc.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/stats/_mcp/_handlers/_posthoc.py
+
+"""Post-hoc test handler."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+
+import numpy as np
+
+__all__ = ["posthoc_test_handler"]
+
+
+async def posthoc_test_handler(
+    groups: list[list[float]],
+    group_names: list[str] | None = None,
+    method: str = "tukey",
+    control_group: int = 0,
+) -> dict:
+    """Run post-hoc pairwise comparisons."""
+    try:
+        loop = asyncio.get_event_loop()
+
+        def do_posthoc():
+            group_arrays = [np.array(g, dtype=float) for g in groups]
+            names = group_names or [f"Group_{i + 1}" for i in range(len(groups))]
+
+            if method == "tukey":
+                comparisons = _tukey_hsd(group_arrays, names)
+            elif method == "dunnett":
+                comparisons = _dunnett(group_arrays, names, control_group)
+            elif method == "games_howell":
+                comparisons = _games_howell(group_arrays, names)
+            elif method == "dunn":
+                comparisons = _dunn(group_arrays, names)
+            else:
+                raise ValueError(f"Unknown method: {method}")
+
+            return comparisons
+
+        comparisons = await loop.run_in_executor(None, do_posthoc)
+
+        return {
+            "success": True,
+            "method": method,
+            "n_groups": len(groups),
+            "n_comparisons": len(comparisons),
+            "comparisons": comparisons,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def _tukey_hsd(group_arrays, names):
+    """Tukey HSD test."""
+    from scipy import stats as scipy_stats
+
+    all_data = np.concatenate(group_arrays)
+    group_labels = np.concatenate(
+        [[names[i]] * len(g) for i, g in enumerate(group_arrays)]
+    )
+
+    comparisons = []
+
+    try:
+        from statsmodels.stats.multicomp import pairwise_tukeyhsd
+
+        tukey = pairwise_tukeyhsd(all_data, group_labels)
+
+        for i in range(len(tukey.summary().data) - 1):
+            row = tukey.summary().data[i + 1]
+            comparisons.append(
+                {
+                    "group1": str(row[0]),
+                    "group2": str(row[1]),
+                    "mean_diff": float(row[2]),
+                    "p_adj": float(row[3]),
+                    "ci_lower": float(row[4]),
+                    "ci_upper": float(row[5]),
+                    "reject": bool(row[6]),
+                }
+            )
+    except ImportError:
+        # Fallback: Bonferroni-corrected t-tests
+        n_comparisons = len(group_arrays) * (len(group_arrays) - 1) // 2
+        for i in range(len(group_arrays)):
+            for j in range(i + 1, len(group_arrays)):
+                stat, p = scipy_stats.ttest_ind(group_arrays[i], group_arrays[j])
+                p_adj = min(p * n_comparisons, 1.0)
+                comparisons.append(
+                    {
+                        "group1": names[i],
+                        "group2": names[j],
+                        "mean_diff": float(
+                            np.mean(group_arrays[i]) - np.mean(group_arrays[j])
+                        ),
+                        "t_statistic": float(stat),
+                        "p_value": float(p),
+                        "p_adj": float(p_adj),
+                        "reject": p_adj < 0.05,
+                    }
+                )
+
+    return comparisons
+
+
+def _dunnett(group_arrays, names, control_group):
+    """Dunnett's test (compare all to control)."""
+    from scipy import stats as scipy_stats
+
+    control = group_arrays[control_group]
+    n_comparisons = len(group_arrays) - 1
+
+    comparisons = []
+    for i, (name, group) in enumerate(zip(names, group_arrays)):
+        if i == control_group:
+            continue
+        stat, p = scipy_stats.ttest_ind(group, control)
+        p_adj = min(p * n_comparisons, 1.0)
+        comparisons.append(
+            {
+                "group": name,
+                "vs_control": names[control_group],
+                "mean_diff": float(np.mean(group) - np.mean(control)),
+                "t_statistic": float(stat),
+                "p_value": float(p),
+                "p_adj": float(p_adj),
+                "reject": p_adj < 0.05,
+            }
+        )
+
+    return comparisons
+
+
+def _games_howell(group_arrays, names):
+    """Games-Howell test (doesn't assume equal variances)."""
+    from scipy import stats as scipy_stats
+
+    comparisons = []
+    n_comparisons = len(group_arrays) * (len(group_arrays) - 1) // 2
+
+    for i in range(len(group_arrays)):
+        for j in range(i + 1, len(group_arrays)):
+            g1, g2 = group_arrays[i], group_arrays[j]
+            n1, n2 = len(g1), len(g2)
+            m1, m2 = np.mean(g1), np.mean(g2)
+            v1, v2 = np.var(g1, ddof=1), np.var(g2, ddof=1)
+
+            se = np.sqrt(v1 / n1 + v2 / n2)
+            t_stat = (m1 - m2) / se
+
+            # Welch-Satterthwaite df
+            df = (v1 / n1 + v2 / n2) ** 2 / (
+                (v1 / n1) ** 2 / (n1 - 1) + (v2 / n2) ** 2 / (n2 - 1)
+            )
+
+            p = 2 * (1 - scipy_stats.t.cdf(abs(t_stat), df))
+            p_adj = min(p * n_comparisons, 1.0)
+
+            comparisons.append(
+                {
+                    "group1": names[i],
+                    "group2": names[j],
+                    "mean_diff": float(m1 - m2),
+                    "t_statistic": float(t_stat),
+                    "df": float(df),
+                    "p_value": float(p),
+                    "p_adj": float(p_adj),
+                    "reject": p_adj < 0.05,
+                }
+            )
+
+    return comparisons
+
+
+def _dunn(group_arrays, names):
+    """Dunn's test for Kruskal-Wallis post-hoc."""
+    from scipy import stats as scipy_stats
+
+    all_data = np.concatenate(group_arrays)
+    ranks = scipy_stats.rankdata(all_data)
+
+    # Assign ranks to groups
+    idx = 0
+    group_ranks = []
+    for g in group_arrays:
+        group_ranks.append(ranks[idx : idx + len(g)])
+        idx += len(g)
+
+    n_total = len(all_data)
+    n_comparisons = len(group_arrays) * (len(group_arrays) - 1) // 2
+
+    comparisons = []
+    for i in range(len(group_arrays)):
+        for j in range(i + 1, len(group_arrays)):
+            n_i, n_j = len(group_arrays[i]), len(group_arrays[j])
+            r_i, r_j = np.mean(group_ranks[i]), np.mean(group_ranks[j])
+
+            se = np.sqrt(n_total * (n_total + 1) / 12 * (1 / n_i + 1 / n_j))
+            z = (r_i - r_j) / se
+            p = 2 * (1 - scipy_stats.norm.cdf(abs(z)))
+            p_adj = min(p * n_comparisons, 1.0)
+
+            comparisons.append(
+                {
+                    "group1": names[i],
+                    "group2": names[j],
+                    "mean_rank_diff": float(r_i - r_j),
+                    "z_statistic": float(z),
+                    "p_value": float(p),
+                    "p_adj": float(p_adj),
+                    "reject": p_adj < 0.05,
+                }
+            )
+
+    return comparisons
+
+
+# EOF

scitex/stats/_mcp/_handlers/_power.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/stats/_mcp/_handlers/_power.py
+
+"""Power analysis handler."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+
+import numpy as np
+
+__all__ = ["power_analysis_handler"]
+
+
+async def power_analysis_handler(
+    test_type: str = "ttest",
+    effect_size: float | None = None,
+    alpha: float = 0.05,
+    power: float = 0.8,
+    n: int | None = None,
+    n_groups: int = 2,
+    ratio: float = 1.0,
+) -> dict:
+    """Calculate statistical power or required sample size."""
+    try:
+        loop = asyncio.get_event_loop()
+
+        def do_power():
+            from scitex.stats.power._power import power_ttest, sample_size_ttest
+
+            result = {}
+
+            if test_type == "ttest":
+                if n is not None and effect_size is not None:
+                    # Calculate power given n and effect size
+                    calculated_power = power_ttest(
+                        effect_size=effect_size,
+                        n1=n,
+                        n2=int(n * ratio),
+                        alpha=alpha,
+                        test_type="two-sample",
+                    )
+                    result = {
+                        "mode": "power_calculation",
+                        "power": calculated_power,
+                        "n1": n,
+                        "n2": int(n * ratio),
+                        "effect_size": effect_size,
+                        "alpha": alpha,
+                    }
+                elif effect_size is not None:
+                    # Calculate required sample size
+                    n1, n2 = sample_size_ttest(
+                        effect_size=effect_size,
+                        power=power,
+                        alpha=alpha,
+                        ratio=ratio,
+                    )
+                    result = {
+                        "mode": "sample_size_calculation",
+                        "required_n1": n1,
+                        "required_n2": n2,
+                        "total_n": n1 + n2,
+                        "effect_size": effect_size,
+                        "target_power": power,
+                        "alpha": alpha,
+                    }
+                else:
+                    raise ValueError("Either n or effect_size must be provided")
+
+            elif test_type == "anova":
+                result = _power_anova(effect_size, alpha, power, n, n_groups)
+
+            elif test_type == "correlation":
+                result = _power_correlation(effect_size, alpha, power, n)
+
+            elif test_type == "chi2":
+                result = _power_chi2(effect_size, alpha, power, n, n_groups)
+
+            else:
+                raise ValueError(f"Unknown test_type: {test_type}")
+
+            return result
+
+        result = await loop.run_in_executor(None, do_power)
+
+        return {
+            "success": True,
+            "test_type": test_type,
+            **result,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def _power_anova(
+    effect_size: float | None,
+    alpha: float,
+    power: float,
+    n: int | None,
+    n_groups: int,
+) -> dict:
+    """ANOVA power calculation."""
+    from scipy import stats as scipy_stats
+
+    if effect_size is None:
+        raise ValueError("effect_size required for ANOVA power")
+
+    if n is not None:
+        df1 = n_groups - 1
+        df2 = n_groups * n - n_groups
+        nc = effect_size**2 * n * n_groups
+        f_crit = scipy_stats.f.ppf(1 - alpha, df1, df2)
+        power_val = 1 - scipy_stats.ncf.cdf(f_crit, df1, df2, nc)
+        return {
+            "mode": "power_calculation",
+            "power": power_val,
+            "n_per_group": n,
+            "n_groups": n_groups,
+            "effect_size_f": effect_size,
+            "alpha": alpha,
+        }
+    else:
+        # Binary search for n
+        n_min, n_max = 2, 1000
+        while n_max - n_min > 1:
+            n_mid = (n_min + n_max) // 2
+            df1 = n_groups - 1
+            df2 = n_groups * n_mid - n_groups
+            nc = effect_size**2 * n_mid * n_groups
+            f_crit = scipy_stats.f.ppf(1 - alpha, df1, df2)
+            power_val = 1 - scipy_stats.ncf.cdf(f_crit, df1, df2, nc)
+            if power_val < power:
+                n_min = n_mid
+            else:
+                n_max = n_mid
+
+        return {
+            "mode": "sample_size_calculation",
+            "required_n_per_group": n_max,
+            "total_n": n_max * n_groups,
+            "n_groups": n_groups,
+            "effect_size_f": effect_size,
+            "target_power": power,
+            "alpha": alpha,
+        }
+
+
+def _power_correlation(
+    effect_size: float | None,
+    alpha: float,
+    power: float,
+    n: int | None,
+) -> dict:
+    """Correlation power calculation."""
+    from scipy import stats as scipy_stats
+
+    if effect_size is None:
+        raise ValueError("effect_size (r) required for correlation power")
+
+    if n is not None:
+        # Calculate power
+        z = 0.5 * np.log((1 + effect_size) / (1 - effect_size))
+        se = 1 / np.sqrt(n - 3)
+        z_crit = scipy_stats.norm.ppf(1 - alpha / 2)
+        power_val = (
+            1
+            - scipy_stats.norm.cdf(z_crit - z / se)
+            + scipy_stats.norm.cdf(-z_crit - z / se)
+        )
+        return {
+            "mode": "power_calculation",
+            "power": power_val,
+            "n": n,
+            "effect_size_r": effect_size,
+            "alpha": alpha,
+        }
+    else:
+        # Calculate required n
+        z = 0.5 * np.log((1 + effect_size) / (1 - effect_size))
+        z_crit = scipy_stats.norm.ppf(1 - alpha / 2)
+        z_power = scipy_stats.norm.ppf(power)
+        required_n = int(np.ceil(((z_crit + z_power) / z) ** 2 + 3))
+        return {
+            "mode": "sample_size_calculation",
+            "required_n": required_n,
+            "effect_size_r": effect_size,
+            "target_power": power,
+            "alpha": alpha,
+        }
+
+
+def _power_chi2(
+    effect_size: float | None,
+    alpha: float,
+    power: float,
+    n: int | None,
+    n_groups: int,
+) -> dict:
+    """Chi-square power calculation."""
+    from scipy import stats as scipy_stats
+
+    if effect_size is None:
+        raise ValueError("effect_size (w) required for chi2 power")
+
+    df = n_groups - 1  # Simplified: using n_groups as number of cells
+
+    if n is not None:
+        nc = effect_size**2 * n
+        chi2_crit = scipy_stats.chi2.ppf(1 - alpha, df)
+        power_val = 1 - scipy_stats.ncx2.cdf(chi2_crit, df, nc)
+        return {
+            "mode": "power_calculation",
+            "power": power_val,
+            "n": n,
+            "df": df,
+            "effect_size_w": effect_size,
+            "alpha": alpha,
+        }
+    else:
+        # Binary search for n
+        n_min, n_max = 10, 10000
+        while n_max - n_min > 1:
+            n_mid = (n_min + n_max) // 2
+            nc = effect_size**2 * n_mid
+            chi2_crit = scipy_stats.chi2.ppf(1 - alpha, df)
+            power_val = 1 - scipy_stats.ncx2.cdf(chi2_crit, df, nc)
+            if power_val < power:
+                n_min = n_mid
+            else:
+                n_max = n_mid
+
+        return {
+            "mode": "sample_size_calculation",
+            "required_n": n_max,
+            "df": df,
+            "effect_size_w": effect_size,
+            "target_power": power,
+            "alpha": alpha,
+        }
+
+
+# EOF