ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/evaluation/trade_shap/explain.py

@@ -0,0 +1,208 @@
+"""Trade SHAP explanation logic.
+
+This module provides the TradeShapExplainer class that explains individual trades
+using SHAP values, with O(log n) timestamp alignment and efficient feature extraction.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ml4t.diagnostic.evaluation.trade_shap.alignment import TimestampAligner
+from ml4t.diagnostic.evaluation.trade_shap.models import (
+    TradeExplainFailure,
+    TradeShapExplanation,
+)
+
+if TYPE_CHECKING:
+    import polars as pl
+    from numpy.typing import NDArray
+
+    from ml4t.diagnostic.evaluation.trade_analysis import TradeMetrics
+
+
+class TradeShapExplainer:
+    """Explains individual trades using SHAP values.
+
+    Uses TimestampAligner for O(log n) timestamp lookup and extracts
+    feature values in a single row read for efficiency.
+
+    Returns TradeExplainFailure for expected failure cases instead of
+    throwing exceptions, enabling clean batch processing.
+
+    Attributes:
+        features_df: Polars DataFrame with timestamp and feature columns
+        shap_values: 2D numpy array of SHAP values (n_samples x n_features)
+        feature_names: List of feature column names
+        aligner: TimestampAligner for fast timestamp lookup
+        top_n_features: Number of top features to include in explanation
+
+    Example:
+        >>> explainer = TradeShapExplainer(
+        ...     features_df=features,
+        ...     shap_values=shap_values,
+        ...     feature_names=feature_names,
+        ...     tolerance_seconds=60.0,
+        ... )
+        >>> result = explainer.explain(trade)
+        >>> if isinstance(result, TradeShapExplanation):
+        ...     print(result.top_features[:3])
+        ... else:
+        ...     print(f"Failed: {result.reason}")
+    """
+
+    def __init__(
+        self,
+        features_df: pl.DataFrame,
+        shap_values: NDArray[np.floating[Any]],
+        feature_names: list[str],
+        tolerance_seconds: float = 0.0,
+        top_n_features: int | None = None,
+        alignment_mode: str = "entry",
+        missing_value_strategy: str = "skip",
+    ) -> None:
+        """Initialize the explainer.
+
+        Args:
+            features_df: Polars DataFrame with 'timestamp' column and feature columns
+            shap_values: SHAP values array (n_samples x n_features)
+            feature_names: List of feature column names matching shap_values columns
+            tolerance_seconds: Maximum seconds for nearest-match alignment (0 = exact only)
+            top_n_features: Number of top features to include (None = all)
+            alignment_mode: 'entry' for exact match, 'nearest' for closest within tolerance
+            missing_value_strategy: How to handle alignment failures ('error', 'skip', 'zero')
+
+        Raises:
+            ValueError: If shap_values shape doesn't match features_df rows or feature_names
+        """
+        self.features_df = features_df
+        self.shap_values = shap_values
+        self.feature_names = feature_names
+        self.top_n_features = top_n_features
+        self.alignment_mode = alignment_mode
+        self.missing_value_strategy = missing_value_strategy
+
+        # Validate shapes
+        n_rows = len(features_df)
+        n_features = len(feature_names)
+
+        if shap_values.shape[0] != n_rows:
+            raise ValueError(
+                f"SHAP values rows ({shap_values.shape[0]}) != features_df rows ({n_rows})"
+            )
+        if shap_values.shape[1] != n_features:
+            raise ValueError(
+                f"SHAP values columns ({shap_values.shape[1]}) != feature_names ({n_features})"
+            )
+
+        # Build aligner with appropriate tolerance
+        timestamps = features_df["timestamp"].to_list()
+        effective_tolerance = tolerance_seconds if alignment_mode == "nearest" else 0.0
+        self.aligner = TimestampAligner.from_datetime_index(
+            timestamps, tolerance_seconds=effective_tolerance
+        )
+
+        # Cache feature data as numpy for fast row extraction
+        self._feature_matrix = features_df.select(feature_names).to_numpy()
+
+    def explain(
+        self,
+        trade: TradeMetrics,
+    ) -> TradeShapExplanation | TradeExplainFailure:
+        """Explain a single trade.
+
+        Args:
+            trade: Trade to explain (must have timestamp and symbol attributes)
+
+        Returns:
+            TradeShapExplanation on success, TradeExplainFailure on expected failures
+        """
+        trade_id = f"{trade.symbol}_{trade.timestamp.isoformat()}"
+
+        # Align to timestamp
+        result = self.aligner.align(trade.timestamp)
+
+        if result.index is None:
+            # Handle alignment failure based on strategy
+            if self.missing_value_strategy == "error":
+                raise ValueError(
+                    f"Cannot align SHAP values for trade {trade_id}: "
+                    f"no timestamp within {self.aligner.tolerance_seconds}s "
+                    f"(nearest is {result.distance_seconds:.1f}s away)"
+                )
+            elif self.missing_value_strategy == "zero":
+                # Return zero SHAP vector
+                shap_vector = np.zeros(len(self.feature_names))
+                feature_values = dict.fromkeys(self.feature_names, 0.0)
+                top_features = [(name, 0.0) for name in self.feature_names]
+                return TradeShapExplanation(
+                    trade_id=trade_id,
+                    timestamp=trade.timestamp,
+                    top_features=top_features,
+                    feature_values=feature_values,
+                    shap_vector=shap_vector,
+                )
+            else:  # "skip" or default
+                return TradeExplainFailure(
+                    trade_id=trade_id,
+                    timestamp=trade.timestamp,
+                    reason="alignment_missing",
+                    details={
+                        "alignment_mode": self.alignment_mode,
+                        "tolerance_seconds": self.aligner.tolerance_seconds,
+                        "distance_seconds": result.distance_seconds,
+                    },
+                )
+
+        idx = result.index
+
+        # Extract SHAP vector for this row
+        shap_vector = np.asarray(self.shap_values[idx, :], dtype=np.float64)
+
+        # Extract feature values in one row read (not per-feature loop)
+        feature_row = self._feature_matrix[idx, :]
+        feature_values = {
+            name: float(val) for name, val in zip(self.feature_names, feature_row, strict=True)
+        }
+
+        # Get top N contributors by absolute SHAP value
+        top_n = self.top_n_features if self.top_n_features is not None else len(self.feature_names)
+
+        # Create (feature_name, shap_value) pairs and sort by |shap|
+        feature_shap_pairs = list(zip(self.feature_names, shap_vector.tolist(), strict=True))
+        feature_shap_pairs.sort(key=lambda x: abs(x[1]), reverse=True)
+        top_features = [(name, float(val)) for name, val in feature_shap_pairs[:top_n]]
+
+        return TradeShapExplanation(
+            trade_id=trade_id,
+            timestamp=trade.timestamp,
+            top_features=top_features,
+            feature_values=feature_values,
+            shap_vector=shap_vector,
+        )
+
+    def explain_many(
+        self,
+        trades: list[TradeMetrics],
+    ) -> tuple[list[TradeShapExplanation], list[TradeExplainFailure]]:
+        """Explain multiple trades.
+
+        Args:
+            trades: List of trades to explain
+
+        Returns:
+            Tuple of (successful explanations, failures)
+        """
+        explanations: list[TradeShapExplanation] = []
+        failures: list[TradeExplainFailure] = []
+
+        for trade in trades:
+            result = self.explain(trade)
+            if isinstance(result, TradeShapExplanation):
+                explanations.append(result)
+            else:
+                failures.append(result)
+
+        return explanations, failures

ml4t/diagnostic/evaluation/trade_shap/hypotheses/__init__.py

@@ -0,0 +1,23 @@
+"""Hypothesis generation for trade SHAP error patterns.
+
+This package provides template-based hypothesis generation for explaining
+why trading patterns cause losses, with templates stored as YAML data.
+"""
+
+from ml4t.diagnostic.evaluation.trade_shap.hypotheses.generator import (
+    HypothesisConfig,
+    HypothesisGenerator,
+)
+from ml4t.diagnostic.evaluation.trade_shap.hypotheses.matcher import (
+    Template,
+    TemplateMatcher,
+    load_templates,
+)
+
+__all__ = [
+    "HypothesisGenerator",
+    "HypothesisConfig",
+    "TemplateMatcher",
+    "Template",
+    "load_templates",
+]

ml4t/diagnostic/evaluation/trade_shap/hypotheses/generator.py

@@ -0,0 +1,290 @@
+"""Hypothesis generator for trade SHAP error patterns.
+
+Generates actionable hypotheses and improvement suggestions based on
+template matching against error pattern features.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from ml4t.diagnostic.evaluation.trade_shap.hypotheses.matcher import (
+    TemplateMatcher,
+    load_templates,
+)
+
+if TYPE_CHECKING:
+    from ml4t.diagnostic.evaluation.trade_shap.models import ErrorPattern
+
+
+@dataclass
+class HypothesisConfig:
+    """Configuration for hypothesis generation.
+
+    Attributes:
+        template_library: Which template library to use ('comprehensive' or 'minimal')
+        min_confidence: Minimum confidence threshold for generating hypothesis
+        max_actions: Maximum number of actions to include
+    """
+
+    template_library: str = "comprehensive"
+    min_confidence: float = 0.5
+    max_actions: int = 4
+
+
+class HypothesisGenerator:
+    """Generates hypotheses for error patterns using template matching.
+
+    Matches error pattern features against a library of templates and
+    generates actionable hypotheses about why the pattern causes losses.
+
+    Attributes:
+        config: Hypothesis generation configuration
+        matcher: Template matcher
+
+    Example:
+        >>> generator = HypothesisGenerator()
+        >>> enriched = generator.generate_hypothesis(error_pattern)
+        >>> print(enriched.hypothesis)
+        >>> print(enriched.actions)
+    """
+
+    def __init__(self, config: HypothesisConfig | Any | None = None) -> None:
+        """Initialize generator.
+
+        Args:
+            config: Hypothesis configuration (uses defaults if None).
+                   Accepts HypothesisConfig dataclass or HypothesisGenerationConfig Pydantic model.
+        """
+        # Normalize config to HypothesisConfig dataclass
+        self.config = self._normalize_config(config)
+
+        # Load templates and create matcher
+        templates = load_templates(self.config.template_library)
+        self.matcher = TemplateMatcher(templates)
+
+    def _normalize_config(self, config: Any) -> HypothesisConfig:
+        """Normalize config to HypothesisConfig dataclass.
+
+        Supports both HypothesisConfig dataclass and HypothesisGenerationConfig Pydantic model.
+        """
+        if config is None:
+            return HypothesisConfig()
+
+        if isinstance(config, HypothesisConfig):
+            return config
+
+        # Handle Pydantic HypothesisGenerationConfig or similar
+        return HypothesisConfig(
+            template_library=getattr(config, "template_library", "comprehensive"),
+            min_confidence=getattr(config, "min_confidence", 0.5),
+            max_actions=getattr(config, "max_actions", 4),
+        )
+
+    def generate_hypothesis(
+        self,
+        error_pattern: ErrorPattern,
+        feature_names: list[str] | None = None,
+    ) -> ErrorPattern:
+        """Generate hypothesis for an error pattern.
+
+        Args:
+            error_pattern: Error pattern to analyze
+            feature_names: Optional list of all feature names for context
+
+        Returns:
+            ErrorPattern with hypothesis, actions, and confidence fields populated
+        """
+        from ml4t.diagnostic.evaluation.trade_shap.models import ErrorPattern
+
+        # Parse top_features into dict format for matcher
+        pattern_features = [
+            {
+                "name": feat[0],
+                "mean_shap": feat[1],
+                "p_value_t": feat[2],
+                "p_value_mw": feat[3],
+                "is_significant": feat[4],
+            }
+            for feat in error_pattern.top_features
+        ]
+
+        # Try to match a template
+        match_result = self.matcher.match(pattern_features)
+
+        if match_result is None or match_result.confidence < self.config.min_confidence:
+            # No good match - return pattern unchanged
+            return error_pattern
+
+        # Format hypothesis from template
+        hypothesis = self._format_hypothesis(
+            match_result.template.hypothesis_template,
+            match_result.matched_features,
+        )
+
+        # Get actions (limit to max)
+        actions = match_result.template.actions[: self.config.max_actions]
+
+        # Adjust confidence based on pattern characteristics
+        adjusted_confidence = self._adjust_confidence(
+            match_result.confidence,
+            error_pattern.n_trades,
+            error_pattern.separation_score,
+        )
+
+        # Return enriched pattern
+        return ErrorPattern(
+            cluster_id=error_pattern.cluster_id,
+            n_trades=error_pattern.n_trades,
+            description=error_pattern.description,
+            top_features=error_pattern.top_features,
+            separation_score=error_pattern.separation_score,
+            distinctiveness=error_pattern.distinctiveness,
+            hypothesis=hypothesis,
+            actions=actions,
+            confidence=adjusted_confidence,
+        )
+
+    def _format_hypothesis(
+        self,
+        template: str,
+        matched_features: list[dict[str, Any]],
+    ) -> str:
+        """Format hypothesis string from template.
+
+        Substitutes {feature} placeholder with actual feature name(s).
+        """
+        if not matched_features:
+            return template.replace("{feature}", "the feature")
+
+        # Use first matched feature name
+        feature_name = matched_features[0]["name"]
+
+        # If multiple significant features, mention them
+        sig_features = [f for f in matched_features if f["is_significant"]]
+        if len(sig_features) > 1:
+            names = [f["name"] for f in sig_features[:2]]
+            feature_name = " and ".join(names)
+
+        return template.replace("{feature}", feature_name)
+
+    def _adjust_confidence(
+        self,
+        base_confidence: float,
+        n_trades: int,
+        separation_score: float,
+    ) -> float:
+        """Adjust confidence based on pattern characteristics.
+
+        - More trades = higher confidence (larger sample)
+        - Higher separation = higher confidence (more distinct pattern)
+        - Very small samples or poor separation get significant penalties
+        """
+        # Trade count adjustment - penalize small samples heavily
+        if n_trades >= 20:
+            trade_boost = 0.05
+        elif n_trades >= 10:
+            trade_boost = 0.02
+        elif n_trades >= 5:
+            trade_boost = -0.10
+        elif n_trades >= 2:
+            trade_boost = -0.25
+        else:
+            # Single trade - very unreliable
+            trade_boost = -0.50
+
+        # Separation score adjustment - penalize poor cluster separation
+        if separation_score >= 1.5:
+            sep_boost = 0.05
+        elif separation_score >= 1.0:
+            sep_boost = 0.02
+        elif separation_score >= 0.5:
+            sep_boost = -0.20  # Moderate separation needs noticeable penalty
+        elif separation_score >= 0.3:
+            sep_boost = -0.35
+        else:
+            # Very poor separation - cluster is not distinct
+            sep_boost = -0.50
+
+        adjusted = base_confidence + trade_boost + sep_boost
+        return max(0.0, min(1.0, adjusted))
+
+    def generate_actions(
+        self,
+        error_pattern: ErrorPattern,
+        max_actions: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Generate prioritized action suggestions for an error pattern.
+
+        Args:
+            error_pattern: Error pattern with hypothesis
+            max_actions: Maximum actions to return (defaults to config)
+
+        Returns:
+            List of action dictionaries with category, description, priority, etc.
+        """
+        if max_actions is None:
+            max_actions = self.config.max_actions
+
+        if not error_pattern.actions:
+            return []
+
+        # Categorize and prioritize actions
+        categorized_actions = []
+
+        for i, action in enumerate(error_pattern.actions[:max_actions]):
+            # Determine category from action text
+            category = self._categorize_action(action)
+
+            # Priority based on position and confidence
+            priority = self._determine_priority(i, error_pattern.confidence)
+
+            categorized_actions.append(
+                {
+                    "category": category,
+                    "description": action,
+                    "priority": priority,
+                    "implementation_difficulty": self._estimate_difficulty(action),
+                    "rationale": f"Based on pattern: {error_pattern.description}",
+                }
+            )
+
+        return categorized_actions
+
+    def _categorize_action(self, action: str) -> str:
+        """Categorize an action based on its text."""
+        action_lower = action.lower()
+
+        if any(word in action_lower for word in ["feature", "indicator", "add"]):
+            return "feature_engineering"
+        elif any(word in action_lower for word in ["filter", "regime", "threshold"]):
+            return "filter_regime"
+        elif any(word in action_lower for word in ["size", "position", "stop", "risk"]):
+            return "risk_management"
+        elif any(word in action_lower for word in ["tune", "parameter", "adjust"]):
+            return "model_adjustment"
+        else:
+            return "general"
+
+    def _determine_priority(self, position: int, confidence: float | None) -> str:
+        """Determine action priority."""
+        conf = confidence or 0.5
+
+        if position == 0 and conf >= 0.7:
+            return "high"
+        elif position <= 1 and conf >= 0.5:
+            return "medium"
+        else:
+            return "low"
+
+    def _estimate_difficulty(self, action: str) -> str:
+        """Estimate implementation difficulty from action text."""
+        action_lower = action.lower()
+
+        if any(word in action_lower for word in ["implement", "hmm", "model", "ensemble"]):
+            return "hard"
+        elif any(word in action_lower for word in ["add", "consider", "track"]):
+            return "medium"
+        else:
+            return "easy"