ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/results/barrier_results/time_to_target.py

@@ -0,0 +1,305 @@
+"""Time-to-target analysis results for barrier outcomes.
+
+This module provides the TimeToTargetResult class for storing time-to-target
+metrics (mean, median, std bars to TP/SL/timeout) by signal quantile.
+"""
+
+from __future__ import annotations
+
+import polars as pl
+from pydantic import Field, model_validator
+
+from ml4t.diagnostic.results.barrier_results.validation import _validate_quantile_dict_keys
+from ml4t.diagnostic.results.base import BaseResult
+
+
+class TimeToTargetResult(BaseResult):
+    """Results from time-to-target analysis by signal decile.
+
+    Analyzes how quickly different signal quantiles reach their barrier
+    outcomes (TP, SL, or timeout).
+
+    Examples
+    --------
+    >>> result = time_to_target_result
+    >>> print(result.summary())
+    >>> df = result.get_dataframe()
+    """
+
+    analysis_type: str = Field(default="barrier_time_to_target", frozen=True)
+
+    # ==========================================================================
+    # Configuration
+    # ==========================================================================
+
+    n_quantiles: int = Field(
+        ...,
+        description="Number of quantiles used",
+    )
+
+    quantile_labels: list[str] = Field(
+        ...,
+        description="Labels for each quantile (e.g., ['D1', 'D2', ..., 'D10'])",
+    )
+
+    # ==========================================================================
+    # Mean Time to Exit by Quantile and Outcome
+    # ==========================================================================
+
+    mean_bars_tp: dict[str, float] = Field(
+        ...,
+        description="Mean bars to TP per quantile",
+    )
+
+    mean_bars_sl: dict[str, float] = Field(
+        ...,
+        description="Mean bars to SL per quantile",
+    )
+
+    mean_bars_timeout: dict[str, float] = Field(
+        ...,
+        description="Mean bars to timeout per quantile",
+    )
+
+    mean_bars_all: dict[str, float] = Field(
+        ...,
+        description="Mean bars to any exit per quantile",
+    )
+
+    # ==========================================================================
+    # Median Time to Exit
+    # ==========================================================================
+
+    median_bars_tp: dict[str, float] = Field(
+        ...,
+        description="Median bars to TP per quantile",
+    )
+
+    median_bars_sl: dict[str, float] = Field(
+        ...,
+        description="Median bars to SL per quantile",
+    )
+
+    median_bars_all: dict[str, float] = Field(
+        ...,
+        description="Median bars to any exit per quantile",
+    )
+
+    # ==========================================================================
+    # Standard Deviation
+    # ==========================================================================
+
+    std_bars_tp: dict[str, float] = Field(
+        ...,
+        description="Std dev of bars to TP per quantile",
+    )
+
+    std_bars_sl: dict[str, float] = Field(
+        ...,
+        description="Std dev of bars to SL per quantile",
+    )
+
+    std_bars_all: dict[str, float] = Field(
+        ...,
+        description="Std dev of bars to any exit per quantile",
+    )
+
+    # ==========================================================================
+    # Counts
+    # ==========================================================================
+
+    count_tp: dict[str, int] = Field(
+        ...,
+        description="Number of TP outcomes per quantile",
+    )
+
+    count_sl: dict[str, int] = Field(
+        ...,
+        description="Number of SL outcomes per quantile",
+    )
+
+    count_timeout: dict[str, int] = Field(
+        ...,
+        description="Number of timeout outcomes per quantile",
+    )
+
+    # ==========================================================================
+    # Overall Statistics
+    # ==========================================================================
+
+    overall_mean_bars: float = Field(
+        ...,
+        description="Overall mean bars to exit",
+    )
+
+    overall_median_bars: float = Field(
+        ...,
+        description="Overall median bars to exit",
+    )
+
+    overall_mean_bars_tp: float = Field(
+        ...,
+        description="Overall mean bars to TP",
+    )
+
+    overall_mean_bars_sl: float = Field(
+        ...,
+        description="Overall mean bars to SL",
+    )
+
+    n_observations: int = Field(
+        ...,
+        description="Total number of observations",
+    )
+
+    # ==========================================================================
+    # Speed Analysis
+    # ==========================================================================
+
+    tp_faster_than_sl: dict[str, bool] = Field(
+        ...,
+        description="Whether TP is reached faster than SL on average per quantile",
+    )
+
+    speed_advantage_tp: dict[str, float] = Field(
+        ...,
+        description="Speed advantage of TP over SL (positive = TP faster) per quantile",
+    )
+
+    # ==========================================================================
+    # Validation
+    # ==========================================================================
+
+    @model_validator(mode="after")
+    def _validate_quantile_keys(self) -> TimeToTargetResult:
+        """Validate that all quantile-keyed dicts have consistent keys."""
+        if self.n_quantiles != len(self.quantile_labels):
+            raise ValueError(
+                f"n_quantiles ({self.n_quantiles}) != len(quantile_labels) ({len(self.quantile_labels)})"
+            )
+        _validate_quantile_dict_keys(
+            self.quantile_labels,
+            [
+                ("mean_bars_tp", self.mean_bars_tp),
+                ("mean_bars_sl", self.mean_bars_sl),
+                ("mean_bars_timeout", self.mean_bars_timeout),
+                ("mean_bars_all", self.mean_bars_all),
+                ("median_bars_tp", self.median_bars_tp),
+                ("median_bars_sl", self.median_bars_sl),
+                ("median_bars_all", self.median_bars_all),
+                ("std_bars_tp", self.std_bars_tp),
+                ("std_bars_sl", self.std_bars_sl),
+                ("std_bars_all", self.std_bars_all),
+                ("count_tp", self.count_tp),
+                ("count_sl", self.count_sl),
+                ("count_timeout", self.count_timeout),
+                ("tp_faster_than_sl", self.tp_faster_than_sl),
+                ("speed_advantage_tp", self.speed_advantage_tp),
+            ],
+        )
+        return self
+
+    def get_dataframe(self, name: str | None = None) -> pl.DataFrame:
+        """Get results as Polars DataFrame.
+
+        Parameters
+        ----------
+        name : str | None
+            DataFrame to retrieve:
+            - None or "time_to_target": Mean times by quantile and outcome
+            - "detailed": Full statistics including median and std
+            - "summary": Overall statistics
+
+        Returns
+        -------
+        pl.DataFrame
+            Requested DataFrame
+        """
+        if name is None or name == "time_to_target":
+            return pl.DataFrame(
+                {
+                    "quantile": self.quantile_labels,
+                    "mean_bars_tp": [self.mean_bars_tp[q] for q in self.quantile_labels],
+                    "mean_bars_sl": [self.mean_bars_sl[q] for q in self.quantile_labels],
+                    "mean_bars_timeout": [self.mean_bars_timeout[q] for q in self.quantile_labels],
+                    "mean_bars_all": [self.mean_bars_all[q] for q in self.quantile_labels],
+                    "tp_faster": [self.tp_faster_than_sl[q] for q in self.quantile_labels],
+                }
+            )
+
+        if name == "detailed":
+            return pl.DataFrame(
+                {
+                    "quantile": self.quantile_labels,
+                    "mean_bars_tp": [self.mean_bars_tp[q] for q in self.quantile_labels],
+                    "median_bars_tp": [self.median_bars_tp[q] for q in self.quantile_labels],
+                    "std_bars_tp": [self.std_bars_tp[q] for q in self.quantile_labels],
+                    "mean_bars_sl": [self.mean_bars_sl[q] for q in self.quantile_labels],
+                    "median_bars_sl": [self.median_bars_sl[q] for q in self.quantile_labels],
+                    "std_bars_sl": [self.std_bars_sl[q] for q in self.quantile_labels],
+                    "count_tp": [self.count_tp[q] for q in self.quantile_labels],
+                    "count_sl": [self.count_sl[q] for q in self.quantile_labels],
+                    "count_timeout": [self.count_timeout[q] for q in self.quantile_labels],
+                }
+            )
+
+        if name == "summary":
+            return pl.DataFrame(
+                {
+                    "metric": [
+                        "n_observations",
+                        "n_quantiles",
+                        "overall_mean_bars",
+                        "overall_median_bars",
+                        "overall_mean_bars_tp",
+                        "overall_mean_bars_sl",
+                    ],
+                    "value": [
+                        float(self.n_observations),
+                        float(self.n_quantiles),
+                        self.overall_mean_bars,
+                        self.overall_median_bars,
+                        self.overall_mean_bars_tp,
+                        self.overall_mean_bars_sl,
+                    ],
+                }
+            )
+
+        raise ValueError(
+            f"Unknown DataFrame name: {name}. Available: 'time_to_target', 'detailed', 'summary'"
+        )
+
+    def list_available_dataframes(self) -> list[str]:
+        """List available DataFrame views."""
+        return ["time_to_target", "detailed", "summary"]
+
+    def summary(self) -> str:
+        """Get human-readable summary of time-to-target results."""
+        lines = [
+            "=" * 60,
+            "Barrier Time-to-Target Analysis",
+            "=" * 60,
+            "",
+            f"Observations:        {self.n_observations:>10,}",
+            f"Quantiles:           {self.n_quantiles:>10}",
+            "",
+            "Overall Time to Exit:",
+            f"  Mean Bars:         {self.overall_mean_bars:>10.1f}",
+            f"  Median Bars:       {self.overall_median_bars:>10.1f}",
+            f"  Mean Bars (TP):    {self.overall_mean_bars_tp:>10.1f}",
+            f"  Mean Bars (SL):    {self.overall_mean_bars_sl:>10.1f}",
+            "",
+            "-" * 60,
+            "Mean Bars to Exit by Quantile:",
+            "-" * 60,
+            f"{'Quantile':<10} {'TP':>8} {'SL':>8} {'Timeout':>8} {'All':>8} {'TP Faster?':>12}",
+        ]
+
+        for q in self.quantile_labels:
+            tp_faster = "Yes" if self.tp_faster_than_sl[q] else "No"
+            lines.append(
+                f"{q:<10} {self.mean_bars_tp[q]:>8.1f} {self.mean_bars_sl[q]:>8.1f} "
+                f"{self.mean_bars_timeout[q]:>8.1f} {self.mean_bars_all[q]:>8.1f} {tp_faster:>12}"
+            )
+
+        return "\n".join(lines)

ml4t/diagnostic/results/barrier_results/validation.py

@@ -0,0 +1,38 @@
+"""Validation helper functions for barrier analysis results.
+
+This module provides validation utilities for quantile-keyed dictionaries
+used across all barrier result classes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _validate_quantile_dict_keys(
+    quantile_labels: list[str],
+    dicts: list[tuple[str, dict[str, Any]]],
+) -> None:
+    """Validate that all quantile-keyed dicts have the expected keys.
+
+    Parameters
+    ----------
+    quantile_labels : list[str]
+        Expected quantile labels (keys).
+    dicts : list[tuple[str, dict]]
+        List of (field_name, dict) tuples to validate.
+
+    Raises
+    ------
+    ValueError
+        If any dict has different keys than quantile_labels.
+    """
+    expected_keys = set(quantile_labels)
+    for name, d in dicts:
+        actual_keys = set(d.keys())
+        if actual_keys != expected_keys:
+            missing = expected_keys - actual_keys
+            extra = actual_keys - expected_keys
+            raise ValueError(
+                f"Key mismatch in '{name}': missing={missing or 'none'}, extra={extra or 'none'}"
+            )

ml4t/diagnostic/results/base.py

@@ -0,0 +1,177 @@
+"""Base result class with common functionality for all evaluation results."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+import polars as pl
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BaseResult(BaseModel):
+    """Base class for all evaluation results.
+
+    Provides common functionality:
+    - Metadata (timestamp, version, analysis type)
+    - JSON export via model_dump_json()
+    - Dict export via to_dict()
+    - DataFrame conversion via get_dataframe()
+    - Human-readable summary via summary()
+
+    All result schemas inherit from this class to ensure consistent behavior.
+
+    Examples:
+        >>> result = FeatureDiagnosticsResult(...)
+        >>> json_str = result.model_dump_json(indent=2)
+        >>> df = result.get_dataframe()
+        >>> available = result.list_available_dataframes()
+        >>> print(result.summary())
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",  # Catch typos
+        validate_assignment=True,  # Validate on mutation
+        arbitrary_types_allowed=True,  # Allow Polars types if needed
+        use_enum_values=True,  # Serialize enums as values
+    )
+
+    # Metadata fields - present in all results
+    created_at: str = Field(
+        default_factory=lambda: datetime.now(UTC).isoformat(),
+        description="ISO timestamp of result creation (UTC)",
+    )
+    analysis_type: str = Field(
+        ...,
+        description="Type of analysis performed (e.g., 'feature_diagnostics')",
+    )
+    version: str = Field(
+        default="2.0.0",
+        description="ML4T Diagnostic version used to generate results",
+    )
+
+    def to_dict(self, *, exclude_none: bool = False) -> dict[str, Any]:
+        """Export to Python dictionary.
+
+        Args:
+            exclude_none: Exclude fields with None values
+
+        Returns:
+            Dictionary representation of result
+        """
+        return self.model_dump(exclude_none=exclude_none, mode="python")
+
+    def to_json_string(self, *, indent: int | None = 2) -> str:
+        """Export to JSON string.
+
+        Args:
+            indent: Indentation level (None for compact)
+
+        Returns:
+            JSON string representation
+        """
+        return self.model_dump_json(indent=indent)
+
+    def get_dataframe(self, name: str | None = None) -> pl.DataFrame:
+        """Get results as Polars DataFrame.
+
+        Provides programmatic access to underlying data for QEngine storage
+        and further analysis. Subclasses should override to provide specific
+        DataFrame views.
+
+        Args:
+            name: Optional DataFrame name to retrieve specific view.
+                  If None, returns primary/default DataFrame.
+                  Use list_available_dataframes() to see available names.
+
+        Returns:
+            Polars DataFrame with results
+
+        Raises:
+            NotImplementedError: If not implemented by subclass
+            ValueError: If requested DataFrame name not available
+
+        Examples:
+            >>> result = FeatureDiagnosticsResult(...)
+            >>> df = result.get_dataframe()  # Primary DataFrame
+            >>> df = result.get_dataframe("stationarity")  # Specific view
+            >>> available = result.list_available_dataframes()
+            >>> for name in available:
+            ...     df = result.get_dataframe(name)
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} must implement get_dataframe()")
+
+    def list_available_dataframes(self) -> list[str]:
+        """List available DataFrame views for this result.
+
+        Returns names that can be passed to get_dataframe() to retrieve
+        specific data views. Useful for discovery and QEngine integration.
+
+        Returns:
+            List of available DataFrame names
+
+        Examples:
+            >>> result.list_available_dataframes()
+            ['primary', 'stationarity', 'autocorrelation', 'volatility']
+        """
+        # Default implementation - subclasses should override
+        return ["primary"]
+
+    def get_dataframe_schema(self, name: str | None = None) -> dict[str, str]:
+        """Get schema information for a DataFrame.
+
+        Returns column names and types for a DataFrame without loading data.
+        Useful for QEngine to understand data structure before retrieval.
+
+        Args:
+            name: DataFrame name (None for primary)
+
+        Returns:
+            Dictionary mapping column names to Polars dtype strings
+
+        Examples:
+            >>> result.get_dataframe_schema("stationarity")
+            {
+                'feature': 'String',
+                'adf_pvalue': 'Float64',
+                'is_stationary': 'Boolean'
+            }
+        """
+        # Get actual DataFrame and extract schema
+        df = self.get_dataframe(name)
+        return {col: str(dtype) for col, dtype in zip(df.columns, df.dtypes, strict=False)}
+
+    def summary(self) -> str:
+        """Get human-readable summary of results.
+
+        This method should be overridden by subclasses to provide
+        meaningful summaries of their specific data.
+
+        Returns:
+            Formatted summary string
+
+        Raises:
+            NotImplementedError: If not implemented by subclass
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} must implement summary()")
+
+    def interpret(self) -> list[str]:
+        """Get human-readable interpretation of results.
+
+        Returns actionable insights and recommendations based on
+        the analysis results. Default implementation returns empty list.
+
+        Returns:
+            List of interpretation strings with insights and recommendations
+
+        Examples:
+            >>> result.interpret()
+            ['Strategy is statistically significant (DSR=98.2% > 95%)',
+             'Recommendation: Strategy shows robust performance']
+        """
+        # Default implementation - subclasses can override
+        return []
+
+    def __repr__(self) -> str:
+        """Concise representation showing type and timestamp."""
+        return f"{self.__class__.__name__}(analysis_type={self.analysis_type!r}, created_at={self.created_at!r})"