ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/evaluation/trade_dashboard/tabs/shap_analysis.py

@@ -0,0 +1,280 @@
+"""SHAP Analysis tab.
+
+Displays individual trade SHAP explanations and global feature importance.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    from ml4t.diagnostic.evaluation.trade_dashboard.types import DashboardBundle
+
+
+def render_tab(st: Any, bundle: DashboardBundle) -> None:
+    """Render the SHAP Analysis tab.
+
+    Parameters
+    ----------
+    st : streamlit
+        Streamlit module instance.
+    bundle : DashboardBundle
+        Normalized dashboard data.
+    """
+    st.header("SHAP Analysis")
+
+    st.info(
+        "Explore SHAP (SHapley Additive exPlanations) values for individual trades "
+        "to understand which features drove model predictions."
+    )
+
+    explanations = bundle.explanations
+
+    if not explanations:
+        st.warning("No trade explanations available.")
+        return
+
+    # Check for trade selected from worst trades tab
+    selected_from_tab2 = st.session_state.get("selected_trade_for_shap")
+    selected_trade_idx = 0
+
+    if selected_from_tab2:
+        for i, exp in enumerate(explanations):
+            if exp.get("trade_id") == selected_from_tab2:
+                selected_trade_idx = i
+                break
+
+    # Trade selector
+    st.subheader("Trade Selection")
+
+    if selected_from_tab2:
+        st.success(f"Currently viewing: **{selected_from_tab2}** (selected in Worst Trades tab)")
+
+    trade_options = [exp.get("trade_id", f"Trade_{i}") for i, exp in enumerate(explanations)]
+
+    selected_trade_idx = st.selectbox(
+        "Select trade to view SHAP explanation:",
+        range(len(trade_options)),
+        index=selected_trade_idx,
+        format_func=lambda x: trade_options[x],
+    )
+
+    if selected_trade_idx is not None:
+        _render_trade_shap(st, explanations[selected_trade_idx])
+
+    # Global feature importance
+    st.divider()
+    _render_global_importance(st, explanations)
+
+
+def _render_trade_shap(st: Any, explanation: dict[str, Any]) -> None:
+    """Render SHAP explanation for a single trade."""
+    trade_id = explanation.get("trade_id", "Unknown")
+    timestamp = explanation.get("timestamp")
+    top_features = explanation.get("top_features", [])
+
+    st.divider()
+    st.subheader(f"Trade: {trade_id}")
+    if timestamp:
+        st.caption(f"Timestamp: {timestamp}")
+
+    # Note: Renamed from "Waterfall" - this is actually a bar chart
+    st.subheader("Top SHAP Contributions")
+
+    if not top_features:
+        st.warning("No SHAP features available for this trade.")
+        return
+
+    # Prepare data for visualization
+    features_data = []
+    cumulative = 0.0
+
+    for item in top_features[:15]:
+        if len(item) >= 2:
+            feature, shap_val = item[0], item[1]
+            cumulative += shap_val
+            features_data.append(
+                {
+                    "Feature": feature,
+                    "SHAP Value": shap_val,
+                    "Cumulative": cumulative,
+                    "Impact": "Positive" if shap_val > 0 else "Negative",
+                }
+            )
+
+    if not features_data:
+        st.warning("Could not parse SHAP features.")
+        return
+
+    df_shap = pd.DataFrame(features_data)
+
+    # Create bar chart
+    import plotly.graph_objects as go
+
+    colors = ["#FF6B6B" if val < 0 else "#51CF66" for val in df_shap["SHAP Value"]]
+
+    fig = go.Figure()
+
+    fig.add_trace(
+        go.Bar(
+            x=df_shap["SHAP Value"],
+            y=df_shap["Feature"],
+            orientation="h",
+            marker={"color": colors},
+            text=[f"{val:.4f}" for val in df_shap["SHAP Value"]],
+            textposition="auto",
+            hovertemplate="<b>%{y}</b><br>SHAP: %{x:.4f}<extra></extra>",
+        )
+    )
+
+    fig.update_layout(
+        title="SHAP Feature Contributions (Top 15 Features)",
+        xaxis_title="SHAP Value",
+        yaxis_title="Feature",
+        height=max(400, len(df_shap) * 30),
+        yaxis={"autorange": "reversed"},
+        showlegend=False,
+    )
+
+    st.plotly_chart(fig, use_container_width=True)
+
+    # Feature values table
+    st.subheader("Feature Values")
+
+    display_df = df_shap[["Feature", "SHAP Value", "Impact"]].copy()
+    display_df["SHAP Value"] = display_df["SHAP Value"].apply(lambda x: f"{x:.4f}")
+
+    st.dataframe(
+        display_df,
+        hide_index=True,
+        use_container_width=True,
+        column_config={
+            "Feature": st.column_config.TextColumn("Feature Name", width="medium"),
+            "SHAP Value": st.column_config.TextColumn("SHAP Value", width="small"),
+            "Impact": st.column_config.TextColumn("Impact", width="small"),
+        },
+    )
+
+    # Interpretation guide
+    with st.expander("How to Interpret SHAP Values"):
+        st.markdown(
+            """
+            **SHAP Value Interpretation:**
+
+            - **Positive SHAP value (green)**: Feature pushed prediction higher
+            - **Negative SHAP value (red)**: Feature pushed prediction lower
+            - **Magnitude**: Larger absolute values indicate stronger influence
+
+            **For a losing trade:**
+            - Large positive values contributed to an incorrect bullish prediction
+            - Large negative values contributed to an incorrect bearish prediction
+
+            **Actionable insights:**
+            - Identify which features consistently mislead the model
+            - Look for patterns across multiple losing trades (see Patterns tab)
+            """
+        )
+
+    # Summary statistics
+    st.divider()
+    st.subheader("SHAP Summary Statistics")
+
+    shap_values = [item[1] for item in top_features if len(item) >= 2]
+
+    col1, col2, col3, col4 = st.columns(4)
+
+    with col1:
+        total_shap = sum(shap_values)
+        st.metric("Total SHAP", f"{total_shap:.4f}")
+
+    with col2:
+        positive_shap = sum(v for v in shap_values if v > 0)
+        st.metric("Positive Contrib.", f"{positive_shap:.4f}")
+
+    with col3:
+        negative_shap = sum(v for v in shap_values if v < 0)
+        st.metric("Negative Contrib.", f"{negative_shap:.4f}")
+
+    with col4:
+        mean_abs_shap = float(np.mean([abs(v) for v in shap_values])) if shap_values else 0.0
+        st.metric("Mean Abs. SHAP", f"{mean_abs_shap:.4f}")
+
+
+def _render_global_importance(st: Any, explanations: list[dict[str, Any]]) -> None:
+    """Render global feature importance across all trades."""
+    st.subheader("Global Feature Importance")
+
+    st.markdown(
+        "Aggregate SHAP importance across all analyzed trades to identify "
+        "which features are most influential overall."
+    )
+
+    # Calculate global importance
+    all_features: dict[str, list[float]] = {}
+
+    for exp in explanations:
+        top_features = exp.get("top_features", [])
+
+        for item in top_features:
+            if len(item) >= 2:
+                feature, shap_val = item[0], item[1]
+                if feature not in all_features:
+                    all_features[feature] = []
+                all_features[feature].append(abs(shap_val))
+
+    if not all_features:
+        st.warning("No feature importance data available.")
+        return
+
+    # Calculate mean absolute SHAP for each feature
+    feature_importance = [
+        {
+            "Feature": feature,
+            "Mean Abs SHAP": float(np.mean(values)),
+            "Frequency": len(values),
+            "Total Impact": sum(values),
+        }
+        for feature, values in all_features.items()
+    ]
+
+    # Sort by mean absolute SHAP
+    feature_importance.sort(key=lambda x: cast(float, x["Mean Abs SHAP"]), reverse=True)
+
+    # Display top 20
+    df_importance = pd.DataFrame(feature_importance[:20])
+
+    # Create bar chart
+    import plotly.express as px
+
+    fig = px.bar(
+        df_importance,
+        x="Mean Abs SHAP",
+        y="Feature",
+        orientation="h",
+        title="Top 20 Most Important Features (Mean Absolute SHAP)",
+        color="Mean Abs SHAP",
+        color_continuous_scale="Blues",
+    )
+
+    fig.update_layout(
+        yaxis={"autorange": "reversed"},
+        height=600,
+    )
+
+    st.plotly_chart(fig, use_container_width=True)
+
+    # Display table
+    st.subheader("Feature Importance Table")
+
+    display_importance = df_importance.copy()
+    display_importance["Mean Abs SHAP"] = display_importance["Mean Abs SHAP"].apply(
+        lambda x: f"{x:.4f}"
+    )
+    display_importance["Total Impact"] = display_importance["Total Impact"].apply(
+        lambda x: f"{x:.4f}"
+    )
+
+    st.dataframe(display_importance, hide_index=True, use_container_width=True)

ml4t/diagnostic/evaluation/trade_dashboard/tabs/stat_validation.py

@@ -0,0 +1,186 @@
+"""Statistical Validation tab.
+
+Displays PSR (Probabilistic Sharpe Ratio), distribution tests, and time-series tests.
+Uses PSR instead of DSR because this dashboard analyzes a single strategy.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ml4t.diagnostic.evaluation.trade_dashboard.types import DashboardBundle
+
+
+def render_tab(st: Any, bundle: DashboardBundle) -> None:
+    """Render the Statistical Validation tab.
+
+    Parameters
+    ----------
+    st : streamlit
+        Streamlit module instance.
+    bundle : DashboardBundle
+        Normalized dashboard data.
+    """
+    from ml4t.diagnostic.evaluation.trade_dashboard.stats import (
+        compute_distribution_tests,
+        compute_return_summary,
+        compute_time_series_tests,
+        probabilistic_sharpe_ratio,
+    )
+
+    st.header("Statistical Validation")
+
+    st.info(
+        "Statistical validation ensures that identified patterns are "
+        "statistically significant and not due to random chance."
+    )
+
+    # Check if we have returns data
+    if bundle.returns is None or len(bundle.returns) == 0:
+        st.warning(
+            "No trade returns available for statistical analysis. "
+            "Ensure trade_metrics are attached to explanations."
+        )
+        return
+
+    returns = bundle.returns
+    summary = compute_return_summary(returns)
+
+    # Show warning if using PnL instead of return_pct
+    if bundle.returns_label == "pnl":
+        st.caption(
+            "Using PnL (dollar amounts) instead of normalized returns. "
+            "Sharpe ratio interpretation is limited."
+        )
+
+    # PSR section (replaces incorrect DSR usage)
+    st.subheader("Probabilistic Sharpe Ratio (PSR)")
+
+    st.markdown(
+        """
+        **What is PSR?**
+        The Probabilistic Sharpe Ratio (PSR) gives the probability that the true
+        Sharpe ratio exceeds a benchmark (typically 0), accounting for sample size
+        and return distribution characteristics.
+
+        *Note: DSR (Deflated Sharpe Ratio) was previously shown here but is not
+        applicable to single-strategy analysis. DSR requires K independent strategies
+        to compute the variance across trials.*
+
+        **Reference:** Bailey & Lopez de Prado (2012). "The Sharpe Ratio Efficient Frontier"
+        """
+    )
+
+    # Calculate PSR
+    psr_result = probabilistic_sharpe_ratio(
+        observed_sharpe=summary.sharpe,
+        benchmark_sharpe=0.0,
+        n_samples=summary.n_samples,
+        skewness=summary.skewness,
+        kurtosis=summary.kurtosis,
+        return_components=True,
+    )
+
+    # Display metrics
+    col1, col2, col3, col4 = st.columns(4)
+
+    with col1:
+        st.metric(
+            "Sharpe Ratio",
+            f"{summary.sharpe:.3f}",
+            help="Observed Sharpe ratio (mean / std)",
+        )
+
+    with col2:
+        st.metric(
+            "PSR (vs SR=0)",
+            f"{psr_result['psr']:.3f}",
+            help="Probability that true SR > 0",
+        )
+
+    with col3:
+        p_value = 1 - psr_result["psr"]
+        st.metric(
+            "P-Value",
+            f"{p_value:.4f}",
+            help="1 - PSR: probability true SR <= 0",
+        )
+
+    with col4:
+        st.metric("N Trades", summary.n_samples, help="Number of trades analyzed")
+
+    # Interpretation
+    psr = psr_result["psr"]
+    if psr >= 0.99:
+        st.success(f"Strong evidence SR > 0 (PSR = {psr:.3f} >= 0.99)")
+    elif psr >= 0.95:
+        st.success(f"Significant performance (PSR = {psr:.3f} >= 0.95)")
+    elif psr >= 0.90:
+        st.warning(f"Marginally significant (PSR = {psr:.3f} >= 0.90)")
+    elif psr >= 0.50:
+        st.warning(f"Weak evidence SR > 0 (PSR = {psr:.3f})")
+    else:
+        st.error(f"Evidence suggests SR <= 0 (PSR = {psr:.3f} < 0.50)")
+
+    # Return statistics
+    st.divider()
+    st.subheader("Return Statistics")
+
+    col1, col2, col3, col4 = st.columns(4)
+
+    with col1:
+        st.metric("Mean", f"{summary.mean:.4f}")
+
+    with col2:
+        st.metric("Std Dev", f"{summary.std:.4f}")
+
+    with col3:
+        st.metric("Win Rate", f"{summary.win_rate:.1%}")
+
+    with col4:
+        st.metric("Skewness", f"{summary.skewness:.3f}")
+
+    col1, col2, col3, col4 = st.columns(4)
+
+    with col1:
+        st.metric("Kurtosis", f"{summary.kurtosis:.3f}")
+
+    with col2:
+        st.metric("Min", f"{summary.min_val:.4f}")
+
+    with col3:
+        st.metric("Max", f"{summary.max_val:.4f}")
+
+    with col4:
+        pass  # Empty column for alignment
+
+    # Distribution tests
+    st.divider()
+    st.subheader("Distribution Tests")
+
+    dist_tests = compute_distribution_tests(returns)
+    if not dist_tests.empty:
+        st.dataframe(
+            dist_tests,
+            hide_index=True,
+            use_container_width=True,
+        )
+    else:
+        st.caption("Insufficient data for distribution tests.")
+
+    # Time-series tests
+    st.divider()
+    st.subheader("Time-Series Tests")
+
+    st.caption("These tests require chronologically ordered data. Trades are sorted by entry_time.")
+
+    ts_tests = compute_time_series_tests(returns)
+    if not ts_tests.empty:
+        st.dataframe(
+            ts_tests,
+            hide_index=True,
+            use_container_width=True,
+        )
+    else:
+        st.caption("Insufficient data for time-series tests (need 20+ observations).")

ml4t/diagnostic/evaluation/trade_dashboard/tabs/worst_trades.py

@@ -0,0 +1,236 @@
+"""Worst Trades tab.
+
+Displays a table of trades with sorting/filtering and detailed view.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from ml4t.diagnostic.evaluation.trade_dashboard.types import DashboardBundle
+
+
+def render_tab(st: Any, bundle: DashboardBundle) -> None:
+    """Render the Worst Trades tab.
+
+    Parameters
+    ----------
+    st : streamlit
+        Streamlit module instance.
+    bundle : DashboardBundle
+        Normalized dashboard data.
+    """
+    st.header("Worst Trades Analysis")
+
+    st.info(
+        "This tab shows the trades analyzed for error patterns. "
+        "Select a trade to see detailed SHAP explanations."
+    )
+
+    trades_df = bundle.trades_df
+
+    if trades_df.empty:
+        st.warning("No trade data available.")
+        return
+
+    # Sidebar filters
+    with st.sidebar:
+        st.divider()
+        st.subheader("Trade Filters")
+
+        # Sort options
+        sort_options = ["PnL (Low to High)", "PnL (High to Low)", "Entry Time", "Return %"]
+        sort_by = st.selectbox("Sort by", options=sort_options, index=0)
+
+        # Max trades slider
+        max_trades = st.slider("Max trades to display", min_value=5, max_value=100, value=20)
+
+    # Apply sorting
+    sorted_df = trades_df.copy()
+
+    if sort_by == "PnL (Low to High)" and "pnl" in sorted_df.columns:
+        sorted_df = sorted_df.sort_values("pnl", ascending=True, na_position="last")
+    elif sort_by == "PnL (High to Low)" and "pnl" in sorted_df.columns:
+        sorted_df = sorted_df.sort_values("pnl", ascending=False, na_position="last")
+    elif sort_by == "Entry Time" and "entry_time" in sorted_df.columns:
+        sorted_df = sorted_df.sort_values("entry_time", ascending=True, na_position="last")
+    elif sort_by == "Return %" and "return_pct" in sorted_df.columns:
+        sorted_df = sorted_df.sort_values("return_pct", ascending=True, na_position="last")
+
+    # Limit display
+    sorted_df = sorted_df.head(max_trades)
+
+    # Build display DataFrame
+    display_columns = {
+        "trade_id": "Trade ID",
+        "symbol": "Symbol",
+        "entry_time": "Entry Time",
+        "pnl": "PnL",
+        "return_pct": "Return %",
+        "duration_days": "Duration (days)",
+        "top_feature": "Top Feature",
+        "top_shap_value": "Top SHAP",
+    }
+
+    display_df = sorted_df[[c for c in display_columns if c in sorted_df.columns]].copy()
+    display_df = display_df.rename(
+        columns={k: v for k, v in display_columns.items() if k in display_df.columns}
+    )
+
+    # Format timestamp for display
+    if "Entry Time" in display_df.columns:
+        display_df["Entry Time"] = display_df["Entry Time"].apply(
+            lambda x: x.strftime("%Y-%m-%d %H:%M") if pd.notna(x) else "N/A"
+        )
+
+    # Configure column formatting
+    column_config = {
+        "Trade ID": st.column_config.TextColumn("Trade ID", width="medium"),
+        "Symbol": st.column_config.TextColumn("Symbol", width="small"),
+        "Entry Time": st.column_config.TextColumn("Entry Time", width="medium"),
+        "PnL": st.column_config.NumberColumn(
+            "PnL",
+            format="%.2f",
+            help="Profit/Loss for this trade",
+        ),
+        "Return %": st.column_config.NumberColumn(
+            "Return %",
+            format="%.2f%%",
+            help="Return as percentage",
+        ),
+        "Duration (days)": st.column_config.NumberColumn(
+            "Duration (days)",
+            format="%.1f",
+            help="Trade duration in days",
+        ),
+        "Top Feature": st.column_config.TextColumn(
+            "Top Feature",
+            help="Feature with highest absolute SHAP value",
+        ),
+        "Top SHAP": st.column_config.NumberColumn(
+            "Top SHAP",
+            format="%.4f",
+            help="SHAP value for top feature",
+        ),
+    }
+
+    # Display table with selection
+    st.subheader("Trade Table")
+
+    # Initialize session state for selected trade
+    if "selected_trade_idx" not in st.session_state:
+        st.session_state.selected_trade_idx = None
+
+    # Use dataframe with on_select callback
+    event = st.dataframe(
+        display_df,
+        hide_index=True,
+        use_container_width=True,
+        column_config={k: v for k, v in column_config.items() if k in display_df.columns},
+        on_select="rerun",
+        selection_mode="single-row",
+    )
+
+    # Handle row selection
+    selection = getattr(event, "selection", None)
+    if selection is not None:
+        rows = getattr(selection, "rows", [])
+        if rows:
+            st.session_state.selected_trade_idx = rows[0]
+
+    # Display trade details if selected
+    if (
+        st.session_state.selected_trade_idx is not None
+        and st.session_state.selected_trade_idx < len(sorted_df)
+    ):
+        _render_trade_details(st, sorted_df, bundle, st.session_state.selected_trade_idx)
+
+
+def _render_trade_details(
+    st: Any,
+    sorted_df: pd.DataFrame,
+    bundle: DashboardBundle,
+    selected_idx: int,
+) -> None:
+    """Render detailed view of selected trade."""
+    st.divider()
+    st.subheader("Trade Details")
+
+    row = sorted_df.iloc[selected_idx]
+    trade_id = row.get("trade_id", "")
+
+    # Find corresponding explanation
+    explanation = next(
+        (exp for exp in bundle.explanations if exp.get("trade_id") == trade_id),
+        None,
+    )
+
+    # Basic metrics
+    col1, col2, col3, col4 = st.columns(4)
+
+    with col1:
+        st.metric("Trade ID", trade_id)
+        if pd.notna(row.get("symbol")):
+            st.metric("Symbol", row["symbol"])
+
+    with col2:
+        pnl = row.get("pnl")
+        if pd.notna(pnl):
+            st.metric("PnL", f"${pnl:.2f}")
+        else:
+            st.metric("PnL", "N/A")
+
+    with col3:
+        return_pct = row.get("return_pct")
+        if pd.notna(return_pct):
+            st.metric("Return", f"{return_pct:.2f}%")
+        else:
+            st.metric("Return", "N/A")
+
+    with col4:
+        duration = row.get("duration_days")
+        if pd.notna(duration):
+            st.metric("Duration", f"{duration:.1f} days")
+        else:
+            st.metric("Duration", "N/A")
+
+    # Entry/Exit prices
+    col1, col2 = st.columns(2)
+
+    with col1:
+        entry_price = row.get("entry_price")
+        if pd.notna(entry_price):
+            st.metric("Entry Price", f"${entry_price:.4f}")
+        else:
+            st.caption("Entry price not available")
+
+    with col2:
+        exit_price = row.get("exit_price")
+        if pd.notna(exit_price):
+            st.metric("Exit Price", f"${exit_price:.4f}")
+        else:
+            st.caption("Exit price not available")
+
+    # Top features from explanation
+    if explanation and explanation.get("top_features"):
+        st.subheader("Top SHAP Contributions")
+
+        top_features = explanation["top_features"]
+        feature_data = [
+            {"Feature": f[0], "SHAP Value": f[1]}
+            for f in top_features[:10]  # Limit to top 10
+        ]
+
+        if feature_data:
+            st.dataframe(
+                pd.DataFrame(feature_data),
+                hide_index=True,
+                use_container_width=True,
+                column_config={
+                    "Feature": st.column_config.TextColumn("Feature"),
+                    "SHAP Value": st.column_config.NumberColumn("SHAP Value", format="%.4f"),
+                },
+            )