ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/evaluation/trade_dashboard/normalize.py

@@ -0,0 +1,304 @@
+"""Dashboard data normalization.
+
+Converts various input formats (dict, TradeShapResult) into the unified
+DashboardBundle for consumption by all dashboard tabs.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import pandas as pd
+
+from ml4t.diagnostic.evaluation.trade_dashboard.io import coerce_result_to_dict
+from ml4t.diagnostic.evaluation.trade_dashboard.types import DashboardBundle, DashboardConfig
+
+if TYPE_CHECKING:
+    from ml4t.diagnostic.evaluation.trade_shap.models import TradeShapResult
+
+
+def normalize_result(
+    result: TradeShapResult | dict[str, Any],
+    config: DashboardConfig | None = None,
+) -> DashboardBundle:
+    """Normalize result into a DashboardBundle.
+
+    This is the single point of schema adaptation. All tabs receive the
+    normalized DashboardBundle and don't need to handle dict/object branching.
+
+    Parameters
+    ----------
+    result : TradeShapResult or dict
+        Analysis result in either format.
+    config : DashboardConfig, optional
+        Dashboard configuration.
+
+    Returns
+    -------
+    DashboardBundle
+        Normalized data container with:
+        - trades_df sorted chronologically
+        - returns array (prefers return_pct, falls back to pnl)
+        - normalized explanations and patterns
+    """
+    if config is None:
+        config = DashboardConfig()
+
+    # Convert to dict if needed
+    result_dict = coerce_result_to_dict(result)
+
+    # Extract and normalize explanations
+    explanations = result_dict.get("explanations", [])
+    normalized_explanations = [_normalize_explanation(exp) for exp in explanations]
+
+    # Build trades DataFrame
+    trades_df = _build_trades_df(normalized_explanations)
+
+    # Sort chronologically for time-series tests
+    if "entry_time" in trades_df.columns and not trades_df["entry_time"].isna().all():
+        trades_df = trades_df.sort_values("entry_time", ascending=True).reset_index(drop=True)
+
+    # Extract returns (prefer return_pct, fall back to pnl)
+    returns, returns_label = _extract_returns(trades_df)
+
+    # Build patterns DataFrame
+    patterns = result_dict.get("error_patterns", [])
+    patterns_df = _build_patterns_df(patterns)
+
+    # Extract metadata
+    n_analyzed = result_dict.get("n_trades_analyzed", len(explanations))
+    n_explained = result_dict.get("n_trades_explained", len(explanations))
+    n_failed = result_dict.get("n_trades_failed", 0)
+    failed_trades = result_dict.get("failed_trades", [])
+
+    return DashboardBundle(
+        trades_df=trades_df,
+        returns=returns,
+        returns_label=returns_label,
+        explanations=normalized_explanations,
+        patterns_df=patterns_df,
+        n_trades_analyzed=n_analyzed,
+        n_trades_explained=n_explained,
+        n_trades_failed=n_failed,
+        failed_trades=failed_trades,
+        config=config,
+    )
+
+
+def _normalize_explanation(exp: dict[str, Any]) -> dict[str, Any]:
+    """Normalize a single explanation to stable format.
+
+    Returns dict with stable keys:
+    - trade_id: str
+    - timestamp: datetime | None
+    - shap_vector: list[float]
+    - top_features: list[tuple[str, float]]
+    - trade_metrics: dict | None
+    """
+    result: dict[str, Any] = {
+        "trade_id": str(exp.get("trade_id", "")),
+        "timestamp": _parse_timestamp(exp.get("timestamp")),
+        "shap_vector": list(exp.get("shap_vector", [])),
+        "top_features": list(exp.get("top_features", [])),
+        "trade_metrics": None,
+    }
+
+    # Normalize trade_metrics if present
+    if exp.get("trade_metrics"):
+        tm = exp["trade_metrics"]
+        result["trade_metrics"] = {
+            "pnl": _safe_float(tm.get("pnl")),
+            "return_pct": _safe_float(tm.get("return_pct")),
+            "entry_time": _parse_timestamp(tm.get("entry_time")),
+            "exit_time": _parse_timestamp(tm.get("exit_time")),
+            "duration_days": _safe_float(tm.get("duration_days")),
+            "entry_price": _safe_float(tm.get("entry_price")),
+            "exit_price": _safe_float(tm.get("exit_price")),
+            "symbol": tm.get("symbol"),
+        }
+
+    return result
+
+
+def _build_trades_df(explanations: list[dict[str, Any]]) -> pd.DataFrame:
+    """Build trades DataFrame from normalized explanations.
+
+    Returns DataFrame with columns:
+    - trade_id: str
+    - entry_time: datetime
+    - exit_time: datetime (optional)
+    - pnl: float
+    - return_pct: float (optional)
+    - symbol: str (optional)
+    - top_feature: str
+    - top_shap_value: float
+    """
+    records = []
+
+    for exp in explanations:
+        tm = exp.get("trade_metrics") or {}
+        top_features = exp.get("top_features", [])
+
+        record = {
+            "trade_id": exp.get("trade_id", ""),
+            "entry_time": tm.get("entry_time") or exp.get("timestamp"),
+            "exit_time": tm.get("exit_time"),
+            "pnl": tm.get("pnl"),
+            "return_pct": tm.get("return_pct"),
+            "duration_days": tm.get("duration_days"),
+            "entry_price": tm.get("entry_price"),
+            "exit_price": tm.get("exit_price"),
+            "symbol": tm.get("symbol"),
+            "top_feature": top_features[0][0] if top_features else None,
+            "top_shap_value": top_features[0][1] if top_features else None,
+        }
+        records.append(record)
+
+    if not records:
+        # Return empty DataFrame with expected columns
+        return pd.DataFrame(
+            columns=[
+                "trade_id",
+                "entry_time",
+                "exit_time",
+                "pnl",
+                "return_pct",
+                "duration_days",
+                "entry_price",
+                "exit_price",
+                "symbol",
+                "top_feature",
+                "top_shap_value",
+            ]
+        )
+
+    return pd.DataFrame(records)
+
+
+def _extract_returns(trades_df: pd.DataFrame) -> tuple[np.ndarray | None, str]:
+    """Extract returns array from trades DataFrame.
+
+    Prefers return_pct if available, falls back to pnl.
+
+    Returns
+    -------
+    tuple[np.ndarray | None, str]
+        Returns array and label ("return_pct", "pnl", or "none").
+    """
+    if trades_df.empty:
+        return None, "none"
+
+    # Prefer return_pct (normalized returns)
+    if "return_pct" in trades_df.columns:
+        return_pct = trades_df["return_pct"].dropna()
+        if len(return_pct) > 0:
+            return return_pct.to_numpy(dtype=float), "return_pct"
+
+    # Fall back to pnl (dollar amounts)
+    if "pnl" in trades_df.columns:
+        pnl = trades_df["pnl"].dropna()
+        if len(pnl) > 0:
+            return pnl.to_numpy(dtype=float), "pnl"
+
+    return None, "none"
+
+
+def _build_patterns_df(patterns: list[dict[str, Any] | Any]) -> pd.DataFrame:
+    """Build patterns DataFrame from pattern list.
+
+    Returns DataFrame with columns:
+    - cluster_id: int
+    - n_trades: int
+    - description: str
+    - top_features: list[tuple]
+    - hypothesis: str (optional)
+    - actions: list[str] (optional)
+    - confidence: float (optional)
+    - separation_score: float (optional)
+    - distinctiveness: float (optional)
+    """
+    records = []
+
+    for pattern in patterns:
+        if isinstance(pattern, dict):
+            record = {
+                "cluster_id": pattern.get("cluster_id", 0),
+                "n_trades": pattern.get("n_trades", 0),
+                "description": pattern.get("description", ""),
+                "top_features": pattern.get("top_features", []),
+                "separation_score": pattern.get("separation_score"),
+                "distinctiveness": pattern.get("distinctiveness"),
+                "hypothesis": pattern.get("hypothesis"),
+                "actions": pattern.get("actions", []),
+                "confidence": pattern.get("confidence"),
+            }
+        else:
+            record = {
+                "cluster_id": getattr(pattern, "cluster_id", 0),
+                "n_trades": getattr(pattern, "n_trades", 0),
+                "description": getattr(pattern, "description", ""),
+                "top_features": list(getattr(pattern, "top_features", [])),
+                "separation_score": getattr(pattern, "separation_score", None),
+                "distinctiveness": getattr(pattern, "distinctiveness", None),
+                "hypothesis": getattr(pattern, "hypothesis", None),
+                "actions": list(getattr(pattern, "actions", []) or []),
+                "confidence": getattr(pattern, "confidence", None),
+            }
+        records.append(record)
+
+    if not records:
+        return pd.DataFrame(
+            columns=[
+                "cluster_id",
+                "n_trades",
+                "description",
+                "top_features",
+                "separation_score",
+                "distinctiveness",
+                "hypothesis",
+                "actions",
+                "confidence",
+            ]
+        )
+
+    return pd.DataFrame(records)
+
+
+def _parse_timestamp(value: Any) -> datetime | None:
+    """Parse a value into datetime or None."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str):
+        if not value or value == "N/A" or value == "None":
+            return None
+        try:
+            # Try ISO format first
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            try:
+                # Try common datetime formats
+                for fmt in ["%Y-%m-%d %H:%M:%S", "%Y-%m-%d", "%Y/%m/%d"]:
+                    try:
+                        return datetime.strptime(value, fmt)
+                    except ValueError:
+                        continue
+            except Exception:
+                pass
+    return None
+
+
+def _safe_float(value: Any) -> float | None:
+    """Safely convert value to float or None.
+
+    Fixes the float(None) bug in the original dashboard.
+    """
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return None

ml4t/diagnostic/evaluation/trade_dashboard/stats.py

@@ -0,0 +1,386 @@
+"""Dashboard statistical computations.
+
+Pure statistical functions for the dashboard, including PSR (Probabilistic
+Sharpe Ratio) which replaces the incorrectly-used DSR for single-strategy analysis.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, overload
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+from scipy.stats import norm
+
+from ml4t.diagnostic.evaluation.trade_dashboard.types import ReturnSummary
+
+
+def compute_return_summary(returns: np.ndarray) -> ReturnSummary:
+    """Compute summary statistics for a returns series.
+
+    Parameters
+    ----------
+    returns : np.ndarray
+        Array of returns (can be return_pct or pnl).
+
+    Returns
+    -------
+    ReturnSummary
+        Summary statistics including mean, std, Sharpe, skewness, kurtosis.
+    """
+    n = len(returns)
+    if n == 0:
+        return ReturnSummary(
+            n_samples=0,
+            mean=np.nan,
+            std=np.nan,
+            sharpe=np.nan,
+            skewness=np.nan,
+            kurtosis=np.nan,
+            min_val=np.nan,
+            max_val=np.nan,
+            win_rate=np.nan,
+        )
+
+    mean = float(np.mean(returns))
+    std = float(np.std(returns, ddof=1)) if n > 1 else 0.0
+    sharpe = mean / std if std > 0 else np.nan
+
+    # Skewness and kurtosis require minimum samples
+    skewness = float(stats.skew(returns)) if n > 2 else 0.0
+    # Use Fisher=False to get actual kurtosis (3.0 for normal), not excess
+    kurtosis = float(stats.kurtosis(returns, fisher=False)) if n > 3 else 3.0
+
+    win_rate = float(np.mean(returns > 0))
+
+    return ReturnSummary(
+        n_samples=n,
+        mean=mean,
+        std=std,
+        sharpe=sharpe,
+        skewness=skewness,
+        kurtosis=kurtosis,
+        min_val=float(np.min(returns)),
+        max_val=float(np.max(returns)),
+        win_rate=win_rate,
+    )
+
+
+@overload
+def probabilistic_sharpe_ratio(
+    observed_sharpe: float,
+    benchmark_sharpe: float = ...,
+    n_samples: int = ...,
+    skewness: float = ...,
+    kurtosis: float = ...,
+    return_components: Literal[False] = ...,
+) -> float: ...
+
+
+@overload
+def probabilistic_sharpe_ratio(
+    observed_sharpe: float,
+    benchmark_sharpe: float = ...,
+    n_samples: int = ...,
+    skewness: float = ...,
+    kurtosis: float = ...,
+    return_components: Literal[True] = ...,
+) -> dict[str, float]: ...
+
+
+def probabilistic_sharpe_ratio(
+    observed_sharpe: float,
+    benchmark_sharpe: float = 0.0,
+    n_samples: int = 1,
+    skewness: float = 0.0,
+    kurtosis: float = 3.0,
+    return_components: bool = False,
+) -> float | dict[str, float]:
+    """Calculate Probabilistic Sharpe Ratio (PSR).
+
+    PSR gives the probability that the true Sharpe ratio exceeds a benchmark,
+    accounting for sample size and return distribution characteristics.
+
+    Unlike DSR (which corrects for multiple testing across K strategies),
+    PSR is applicable to a SINGLE strategy's performance evaluation.
+
+    Parameters
+    ----------
+    observed_sharpe : float
+        Observed Sharpe ratio of the strategy.
+    benchmark_sharpe : float, default 0.0
+        Benchmark Sharpe ratio (typically 0 for testing significance).
+    n_samples : int, default 1
+        Number of return observations (T).
+    skewness : float, default 0.0
+        Skewness of returns distribution.
+    kurtosis : float, default 3.0
+        Kurtosis of returns (3.0 for normal, NOT excess kurtosis).
+    return_components : bool, default False
+        If True, return dict with intermediate calculations.
+
+    Returns
+    -------
+    float or dict
+        PSR probability in [0, 1], or dict with 'psr', 'z_score', 'std_sr'.
+
+    Notes
+    -----
+    Formula (Bailey & Lopez de Prado 2012):
+
+        PSR = Phi[(SR - SR_0) * sqrt(T-1) / sqrt(1 - gamma_3*SR + (gamma_4-1)/4*SR^2)]
+
+    where:
+        - SR = observed Sharpe ratio
+        - SR_0 = benchmark Sharpe ratio
+        - T = number of samples
+        - gamma_3 = skewness
+        - gamma_4 = kurtosis (not excess)
+        - Phi = standard normal CDF
+
+    Interpretation:
+        - PSR > 0.95: 95% confidence true SR > benchmark (significant at alpha=0.05)
+        - PSR < 0.50: More likely true SR < benchmark
+        - PSR = 0.50: No evidence either way
+
+    Examples
+    --------
+    >>> psr = probabilistic_sharpe_ratio(
+    ...     observed_sharpe=1.5,
+    ...     benchmark_sharpe=0.0,
+    ...     n_samples=252,
+    ...     skewness=-0.5,
+    ...     kurtosis=4.0,
+    ... )
+    >>> print(f"PSR: {psr:.3f}")
+    PSR: 0.987
+
+    References
+    ----------
+    Bailey, D. H., & Lopez de Prado, M. (2012).
+    "The Sharpe Ratio Efficient Frontier."
+    Journal of Risk, 15(2), 3-44.
+    """
+    if n_samples < 2:
+        # Need at least 2 samples for meaningful calculation
+        if return_components:
+            return {"psr": 0.5, "z_score": 0.0, "std_sr": np.inf}
+        return 0.5
+
+    # Calculate denominator of z-score
+    # V[SR] = 1 - gamma_3*SR + (gamma_4-1)/4*SR^2
+    sr_squared = observed_sharpe**2
+    variance_component = 1 - skewness * observed_sharpe + (kurtosis - 1) / 4 * sr_squared
+
+    # Guard against negative variance (can happen with extreme skewness)
+    if variance_component <= 0:
+        variance_component = 0.01  # Small positive value
+
+    std_sr = np.sqrt(variance_component / (n_samples - 1))
+
+    # Calculate z-score
+    if std_sr > 0:
+        z_score = (observed_sharpe - benchmark_sharpe) / std_sr
+    else:
+        z_score = np.inf if observed_sharpe > benchmark_sharpe else -np.inf
+
+    # Convert to probability
+    psr = float(norm.cdf(z_score))
+
+    if return_components:
+        return {
+            "psr": psr,
+            "z_score": float(z_score) if np.isfinite(z_score) else 0.0,
+            "std_sr": float(std_sr),
+        }
+
+    return psr
+
+
+def compute_distribution_tests(
+    returns: np.ndarray,
+) -> pd.DataFrame:
+    """Compute distribution tests for returns.
+
+    Parameters
+    ----------
+    returns : np.ndarray
+        Array of returns.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with test results:
+        - test: Test name
+        - statistic: Test statistic
+        - p_value: P-value
+        - interpretation: Human-readable interpretation
+    """
+    results = []
+
+    n = len(returns)
+
+    # Shapiro-Wilk test (for n <= 5000)
+    if 3 <= n <= 5000:
+        try:
+            from scipy.stats import shapiro
+
+            stat, p = shapiro(returns)
+            results.append(
+                {
+                    "test": "Shapiro-Wilk",
+                    "statistic": stat,
+                    "p_value": p,
+                    "interpretation": "Normal" if p > 0.05 else "Non-normal",
+                }
+            )
+        except Exception:
+            pass
+
+    # Anderson-Darling test
+    if n >= 4:
+        try:
+            from scipy.stats import anderson
+
+            result = anderson(returns, dist="norm")
+            # Use 5% significance level
+            critical_idx = 2  # Index for 5% level
+            stat = result.statistic
+            critical = result.critical_values[critical_idx]
+            is_normal = stat < critical
+            results.append(
+                {
+                    "test": "Anderson-Darling",
+                    "statistic": stat,
+                    "p_value": None,  # Anderson doesn't provide p-value directly
+                    "interpretation": "Normal" if is_normal else "Non-normal",
+                }
+            )
+        except Exception:
+            pass
+
+    # Jarque-Bera test
+    if n >= 20:
+        try:
+            from scipy.stats import jarque_bera
+
+            stat, p = jarque_bera(returns)
+            results.append(
+                {
+                    "test": "Jarque-Bera",
+                    "statistic": stat,
+                    "p_value": p,
+                    "interpretation": "Normal" if p > 0.05 else "Non-normal",
+                }
+            )
+        except Exception:
+            pass
+
+    if not results:
+        return pd.DataFrame(columns=["test", "statistic", "p_value", "interpretation"])
+
+    return pd.DataFrame(results)
+
+
+def compute_time_series_tests(
+    returns: np.ndarray,
+    max_lags: int = 10,
+) -> pd.DataFrame:
+    """Compute time-series tests (requires chronologically sorted data).
+
+    Parameters
+    ----------
+    returns : np.ndarray
+        Array of returns (MUST be in chronological order).
+    max_lags : int, default 10
+        Maximum lags for Ljung-Box test.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with test results.
+
+    Notes
+    -----
+    These tests are only meaningful on chronologically ordered data.
+    The dashboard normalizes data by sorting trades by entry_time.
+    """
+    results = []
+
+    n = len(returns)
+
+    # Ljung-Box test for autocorrelation
+    if n > max_lags + 5:
+        try:
+            from statsmodels.stats.diagnostic import acorr_ljungbox
+
+            lb_result = acorr_ljungbox(returns, lags=[max_lags], return_df=True)
+            stat = lb_result["lb_stat"].iloc[0]
+            p = lb_result["lb_pvalue"].iloc[0]
+            results.append(
+                {
+                    "test": f"Ljung-Box (lag={max_lags})",
+                    "statistic": stat,
+                    "p_value": p,
+                    "interpretation": "No autocorrelation"
+                    if p > 0.05
+                    else "Autocorrelation detected",
+                }
+            )
+        except Exception:
+            pass
+
+    # ADF test for stationarity
+    if n >= 20:
+        try:
+            from statsmodels.tsa.stattools import adfuller
+
+            adf_result = adfuller(returns, autolag="AIC")
+            stat = adf_result[0]
+            p = adf_result[1]
+            results.append(
+                {
+                    "test": "ADF (stationarity)",
+                    "statistic": stat,
+                    "p_value": p,
+                    "interpretation": "Stationary" if p < 0.05 else "Non-stationary",
+                }
+            )
+        except Exception:
+            pass
+
+    if not results:
+        return pd.DataFrame(columns=["test", "statistic", "p_value", "interpretation"])
+
+    return pd.DataFrame(results)
+
+
+def benjamini_hochberg_fdr(
+    p_values: list[float] | np.ndarray,
+    alpha: float = 0.05,
+) -> dict[str, Any]:
+    """Apply Benjamini-Hochberg FDR correction.
+
+    Parameters
+    ----------
+    p_values : list or ndarray
+        Raw p-values.
+    alpha : float, default 0.05
+        Target FDR level.
+
+    Returns
+    -------
+    dict
+        - rejected: boolean array of rejected hypotheses
+        - adjusted_p_values: BH-adjusted p-values
+        - n_rejected: number of rejections
+    """
+    from ml4t.diagnostic.evaluation.stats import benjamini_hochberg_fdr as bh_fdr
+
+    result = bh_fdr(p_values, alpha=alpha, return_details=True)
+    return {
+        "rejected": result["rejected"],
+        "adjusted_p_values": result["adjusted_p_values"],
+        "n_rejected": result["n_rejected"],
+    }