ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/validation/timeseries.py

@@ -0,0 +1,299 @@
+"""Time series validation utilities."""
+
+from __future__ import annotations
+
+from typing import SupportsFloat, SupportsInt, cast
+
+import polars as pl
+
+from ml4t.diagnostic.validation.dataframe import ValidationError
+
+
+class TimeSeriesValidator:
+    """Validator for time series DataFrames.
+
+    Examples:
+        >>> validator = TimeSeriesValidator(df, index_col="date")
+        >>> validator.check_sorted()
+        >>> validator.check_duplicates()
+        >>> validator.check_frequency()
+    """
+
+    def __init__(self, df: pl.DataFrame, index_col: str = "date"):
+        """Initialize validator.
+
+        Args:
+            df: DataFrame to validate
+            index_col: Name of index/date column
+        """
+        self.df = df
+        self.index_col = index_col
+
+    def check_index_exists(self) -> TimeSeriesValidator:
+        """Check that index column exists.
+
+        Returns:
+            Self for chaining
+
+        Raises:
+            ValidationError: If index column missing
+        """
+        if self.index_col not in self.df.columns:
+            raise ValidationError(
+                f"Index column '{self.index_col}' not found",
+                context={"available_columns": self.df.columns},
+            )
+
+        return self
+
+    def check_index_type(self) -> TimeSeriesValidator:
+        """Check that index is datetime/date type.
+
+        Returns:
+            Self for chaining
+
+        Raises:
+            ValidationError: If index not datetime/date
+        """
+        self.check_index_exists()
+
+        dtype = self.df[self.index_col].dtype
+
+        if not (dtype.is_temporal() or str(dtype) in ["Date", "Datetime", "Time"]):
+            raise ValidationError(
+                "Index column must be temporal type",
+                context={
+                    "column": self.index_col,
+                    "actual_type": str(dtype),
+                    "expected": "Date, Datetime, or Time",
+                },
+            )
+
+        return self
+
+    def check_sorted(self, ascending: bool = True) -> TimeSeriesValidator:
+        """Check that time series is sorted.
+
+        Args:
+            ascending: Whether series should be ascending
+
+        Returns:
+            Self for chaining
+
+        Raises:
+            ValidationError: If not sorted
+        """
+        self.check_index_exists()
+
+        index = self.df[self.index_col]
+
+        # Check if sorted using is_sorted() method
+        is_sorted = index.is_sorted() if ascending else index.is_sorted(descending=True)
+
+        if not is_sorted:
+            direction = "ascending" if ascending else "descending"
+            raise ValidationError(
+                f"Time series not sorted in {direction} order",
+                context={"index_column": self.index_col},
+            )
+
+        return self
+
+    def check_duplicates(self) -> TimeSeriesValidator:
+        """Check for duplicate timestamps.
+
+        Returns:
+            Self for chaining
+
+        Raises:
+            ValidationError: If duplicates found
+        """
+        self.check_index_exists()
+
+        duplicates = self.df[self.index_col].is_duplicated().sum()
+
+        if duplicates > 0:
+            # Get some example duplicates
+            dup_values = (
+                self.df.filter(pl.col(self.index_col).is_duplicated())
+                .select(self.index_col)
+                .unique()
+                .head(5)
+                .to_series()
+                .to_list()
+            )
+
+            raise ValidationError(
+                f"Found {duplicates} duplicate timestamps",
+                context={
+                    "index_column": self.index_col,
+                    "duplicate_count": duplicates,
+                    "examples": dup_values,
+                },
+            )
+
+        return self
+
+    def check_gaps(self, max_gap_days: int | None = None) -> TimeSeriesValidator:
+        """Check for large gaps in time series.
+
+        Args:
+            max_gap_days: Maximum allowed gap in days (None = no check)
+
+        Returns:
+            Self for chaining
+
+        Raises:
+            ValidationError: If gaps exceed threshold
+        """
+        if max_gap_days is None:
+            return self
+
+        self.check_index_exists()
+
+        # Calculate gaps
+        gaps = self.df[self.index_col].diff().drop_nulls()
+
+        if len(gaps) == 0:
+            return self
+
+        # Check if any gap exceeds threshold
+        max_gap_raw = gaps.max()
+
+        # Convert to days if datetime (cast to handle Polars scalar types)
+        from datetime import timedelta
+
+        if isinstance(max_gap_raw, timedelta):
+            max_gap_days_actual = max_gap_raw.days
+        else:
+            # Assume already in days (Polars scalar type)
+            max_gap_days_actual = int(cast(SupportsInt, max_gap_raw))
+
+        if max_gap_days_actual > max_gap_days:
+            raise ValidationError(
+                f"Time series has gap of {max_gap_days_actual} days",
+                context={
+                    "max_allowed": max_gap_days,
+                    "max_gap": max_gap_days_actual,
+                },
+            )
+
+        return self
+
+
+def validate_timeseries(
+    df: pl.DataFrame,
+    index_col: str = "date",
+    require_sorted: bool = True,
+    check_duplicates: bool = True,
+    max_gap_days: int | None = None,
+) -> None:
+    """Validate time series DataFrame.
+
+    Args:
+        df: DataFrame to validate
+        index_col: Name of index/date column
+        require_sorted: Whether series must be sorted
+        check_duplicates: Whether to check for duplicate timestamps
+        max_gap_days: Maximum allowed gap in days (None = no check)
+
+    Raises:
+        ValidationError: If validation fails
+
+    Examples:
+        >>> validate_timeseries(
+        ...     df,
+        ...     index_col="date",
+        ...     require_sorted=True,
+        ...     check_duplicates=True,
+        ...     max_gap_days=7
+        ... )
+    """
+    validator = TimeSeriesValidator(df, index_col)
+
+    validator.check_index_exists().check_index_type()
+
+    if require_sorted:
+        validator.check_sorted()
+
+    if check_duplicates:
+        validator.check_duplicates()
+
+    if max_gap_days is not None:
+        validator.check_gaps(max_gap_days)
+
+
+def validate_index(df: pl.DataFrame, index_col: str = "date") -> None:
+    """Validate time series index column.
+
+    Args:
+        df: DataFrame to validate
+        index_col: Name of index column
+
+    Raises:
+        ValidationError: If index invalid
+    """
+    validator = TimeSeriesValidator(df, index_col)
+    validator.check_index_exists().check_index_type()
+
+
+def validate_frequency(
+    df: pl.DataFrame,
+    index_col: str = "date",
+    expected_freq: str | None = None,
+) -> None:
+    """Validate time series frequency.
+
+    Args:
+        df: DataFrame to validate
+        index_col: Name of index column
+        expected_freq: Expected frequency ("daily", "weekly", "monthly")
+
+    Raises:
+        ValidationError: If frequency doesn't match
+
+    Note:
+        Basic implementation checks consistent spacing.
+        Full frequency detection would require more sophisticated logic.
+    """
+    validator = TimeSeriesValidator(df, index_col)
+    validator.check_index_exists().check_sorted()
+
+    if expected_freq is not None:
+        # Basic frequency validation - check consistent spacing
+        gaps = df[index_col].diff().drop_nulls()
+
+        if len(gaps) == 0:
+            return
+
+        # Check if gaps are consistent (within tolerance)
+        # Convert Duration to microseconds for numeric comparison
+        from datetime import timedelta
+
+        gaps_us = gaps.dt.total_microseconds()
+        median_gap_us = gaps_us.median()
+        max_deviation_us = (gaps_us - median_gap_us).abs().max()
+
+        # Handle None cases (shouldn't happen with valid data)
+        if median_gap_us is None or max_deviation_us is None:
+            return
+
+        # Cast to float for arithmetic
+        median_gap = float(cast(SupportsFloat, median_gap_us))
+        max_deviation = float(cast(SupportsFloat, max_deviation_us))
+
+        # Allow 20% deviation
+        tolerance = median_gap * 0.2
+
+        if max_deviation > tolerance:
+            # Convert back to timedelta for human-readable output
+            median_td = timedelta(microseconds=median_gap)
+            max_dev_td = timedelta(microseconds=max_deviation)
+            raise ValidationError(
+                f"Inconsistent {expected_freq} frequency detected",
+                context={
+                    "expected": expected_freq,
+                    "median_gap": str(median_td),
+                    "max_deviation": str(max_dev_td),
+                },
+            )

ml4t/diagnostic/visualization/AGENT.md

@@ -0,0 +1,19 @@
+# visualization/ - Plotly Charts
+
+## Modules
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| core.py | 1060 | Theme, base utilities |
+| barrier_plots.py | 782 | Barrier analysis charts |
+| feature_plots.py | 888 | Importance charts |
+| interaction_plots.py | 618 | Interaction visualization |
+| report_generation.py | 1343 | HTML/PDF export |
+
+## Subdirectories
+
+dashboards/, data_extraction/, backtest/, signal/, portfolio/
+
+## Key Functions
+
+`plot_hit_rate_heatmap()`, `plot_importance_bar()`, `plot_interaction_heatmap()`, `generate_importance_report()`, `combine_figures_to_html()`

ml4t/diagnostic/visualization/__init__.py

@@ -0,0 +1,223 @@
+"""ML4T Diagnostic Visualization Module.
+
+Provides interactive Plotly-based visualizations for all analysis results.
+
+This module implements the four-tier visualization architecture:
+- Layer 1: Analysis (compute_*, analyze_*) - Returns dicts
+- Layer 2: Visualization (plot_*) - Returns Plotly Figures
+- Layer 3: Reporting (generate_*_report) - HTML/PDF outputs
+- Layer 4: Dashboard (Streamlit) - Separate package
+
+All plot functions follow consistent patterns:
+- Accept results dict from analyze_*() functions
+- Return go.Figure objects
+- Support theming and customization
+- Interactive by default
+
+Examples
+--------
+>>> from ml4t-diagnostic import analyze_ml_importance
+>>> from ml4t.diagnostic.visualization import plot_importance_bar
+>>>
+>>> # Analyze
+>>> results = analyze_ml_importance(model, X, y)
+>>>
+>>> # Visualize
+>>> fig = plot_importance_bar(results)
+>>> fig.show()
+>>>
+>>> # Or save
+>>> fig.write_html("importance.html")
+"""
+
+from ml4t.diagnostic.visualization.barrier_plots import (
+    # Barrier analysis plots (Phase 4)
+    plot_hit_rate_heatmap,
+    plot_precision_recall_curve,
+    plot_profit_factor_bar,
+    plot_time_to_target_box,
+)
+from ml4t.diagnostic.visualization.core import (
+    # Common plot elements
+    add_annotation,
+    add_confidence_band,
+    add_threshold_line,
+    apply_responsive_layout,
+    # Layout helpers
+    create_base_figure,
+    # Color schemes
+    get_color_scheme,
+    get_colorscale,
+    get_plot_theme,
+    get_theme_config,
+    # Theme management
+    set_plot_theme,
+    # Validation
+    validate_plot_results,
+    validate_positive_int,
+    validate_theme,
+)
+from ml4t.diagnostic.visualization.dashboards import (
+    # Dashboard base classes
+    BaseDashboard,
+    DashboardSection,
+    # Interactive dashboards
+    FeatureImportanceDashboard,
+    FeatureInteractionDashboard,
+)
+from ml4t.diagnostic.visualization.data_extraction import (
+    # TypedDict structures
+    ImportanceVizData,
+    InteractionVizData,
+    # Data extraction functions
+    extract_importance_viz_data,
+    extract_interaction_viz_data,
+)
+from ml4t.diagnostic.visualization.feature_plots import (
+    # Feature importance visualizations
+    plot_importance_bar,
+    plot_importance_distribution,
+    plot_importance_heatmap,
+    plot_importance_summary,
+)
+from ml4t.diagnostic.visualization.interaction_plots import (
+    # Feature interaction visualizations
+    plot_interaction_bar,
+    plot_interaction_heatmap,
+    plot_interaction_network,
+)
+from ml4t.diagnostic.visualization.portfolio import (
+    create_portfolio_dashboard,
+    plot_annual_returns_bar,
+    plot_drawdown_periods,
+    plot_drawdown_underwater,
+    plot_monthly_returns_heatmap,
+    plot_returns_distribution,
+    plot_rolling_beta,
+    plot_rolling_sharpe,
+    plot_rolling_volatility,
+)
+from ml4t.diagnostic.visualization.portfolio import (
+    # Portfolio tear sheet (pyfolio replacement)
+    plot_cumulative_returns as plot_portfolio_cumulative_returns,
+)
+from ml4t.diagnostic.visualization.portfolio import (
+    plot_rolling_returns as plot_portfolio_rolling_returns,
+)
+from ml4t.diagnostic.visualization.report_generation import (
+    combine_figures_to_html,
+    # PDF export
+    export_figures_to_pdf,
+    generate_combined_report,
+    # HTML report generation
+    generate_importance_report,
+    generate_interaction_report,
+)
+from ml4t.diagnostic.visualization.signal import (
+    MultiSignalDashboard,
+    # Dashboards
+    SignalDashboard,
+    # Turnover plots
+    plot_autocorrelation,
+    # Quantile plots
+    plot_cumulative_returns,
+    # IC plots
+    plot_ic_heatmap,
+    plot_ic_histogram,
+    plot_ic_qq,
+    # Multi-signal plots (Phase 3)
+    plot_ic_ridge,
+    plot_ic_ts,
+    plot_pareto_frontier,
+    plot_quantile_returns_bar,
+    plot_quantile_returns_violin,
+    plot_signal_correlation_heatmap,
+    plot_signal_ranking_bar,
+    plot_spread_timeseries,
+    plot_top_bottom_turnover,
+)
+
+__all__ = [
+    # Theme management
+    "set_plot_theme",
+    "get_plot_theme",
+    "get_theme_config",
+    # Color schemes
+    "get_color_scheme",
+    "get_colorscale",
+    # Validation
+    "validate_plot_results",
+    "validate_positive_int",
+    "validate_theme",
+    # Layout helpers
+    "create_base_figure",
+    "apply_responsive_layout",
+    # Common plot elements
+    "add_annotation",
+    "add_threshold_line",
+    "add_confidence_band",
+    # Feature importance plots
+    "plot_importance_bar",
+    "plot_importance_heatmap",
+    "plot_importance_distribution",
+    "plot_importance_summary",
+    # Feature interaction plots
+    "plot_interaction_bar",
+    "plot_interaction_heatmap",
+    "plot_interaction_network",
+    # HTML report generation
+    "generate_importance_report",
+    "generate_interaction_report",
+    "generate_combined_report",
+    "combine_figures_to_html",
+    # PDF export
+    "export_figures_to_pdf",
+    # Data extraction
+    "extract_importance_viz_data",
+    "extract_interaction_viz_data",
+    "ImportanceVizData",
+    "InteractionVizData",
+    # Dashboard components
+    "BaseDashboard",
+    "DashboardSection",
+    "FeatureImportanceDashboard",
+    "FeatureInteractionDashboard",
+    # Signal IC plots
+    "plot_ic_ts",
+    "plot_ic_histogram",
+    "plot_ic_qq",
+    "plot_ic_heatmap",
+    # Signal quantile plots
+    "plot_quantile_returns_bar",
+    "plot_quantile_returns_violin",
+    "plot_cumulative_returns",
+    "plot_spread_timeseries",
+    # Signal turnover plots
+    "plot_top_bottom_turnover",
+    "plot_autocorrelation",
+    # Multi-signal plots (Phase 3)
+    "plot_ic_ridge",
+    "plot_signal_ranking_bar",
+    "plot_signal_correlation_heatmap",
+    "plot_pareto_frontier",
+    # Signal dashboards
+    "SignalDashboard",
+    "MultiSignalDashboard",
+    # Barrier analysis plots (Phase 4)
+    "plot_hit_rate_heatmap",
+    "plot_profit_factor_bar",
+    "plot_precision_recall_curve",
+    "plot_time_to_target_box",
+    # Portfolio tear sheet (pyfolio replacement)
+    "plot_portfolio_cumulative_returns",
+    "plot_portfolio_rolling_returns",
+    "plot_annual_returns_bar",
+    "plot_monthly_returns_heatmap",
+    "plot_returns_distribution",
+    "plot_rolling_volatility",
+    "plot_rolling_sharpe",
+    "plot_rolling_beta",
+    "plot_drawdown_underwater",
+    "plot_drawdown_periods",
+    "create_portfolio_dashboard",
+]

ml4t/diagnostic/visualization/backtest/__init__.py

@@ -0,0 +1,98 @@
+"""Backtest visualization module.
+
+Plotly-based interactive visualizations for backtest analysis.
+State-of-the-art tearsheet generation exceeding QuantStats.
+
+This module provides:
+- Executive summary with KPI cards and traffic lights
+- Trade-level visualizations (MFE/MAE, exit reasons, waterfall)
+- Cost attribution analysis (gross-to-net decomposition)
+- Statistical validity displays (DSR gauge, confidence intervals)
+- Unified tearsheet generation with template system
+"""
+
+from .cost_attribution import (
+    plot_cost_by_asset,
+    plot_cost_over_time,
+    plot_cost_pie,
+    plot_cost_sensitivity,
+    plot_cost_waterfall,
+)
+from .executive_summary import (
+    create_executive_summary,
+    create_key_insights,
+    create_metric_card,
+    get_traffic_light_color,
+)
+from .interactive_controls import (
+    get_date_range_html,
+    get_drill_down_modal_html,
+    get_interactive_toolbar_html,
+    get_metric_filter_html,
+    get_section_navigation_html,
+    get_theme_switcher_html,
+)
+from .statistical_validity import (
+    plot_confidence_intervals,
+    plot_dsr_gauge,
+    plot_minimum_track_record,
+    plot_ras_analysis,
+    plot_statistical_summary_card,
+)
+from .tearsheet import (
+    BacktestTearsheet,
+    generate_backtest_tearsheet,
+)
+from .template_system import (
+    TearsheetSection,
+    TearsheetTemplate,
+    get_template,
+)
+from .trade_plots import (
+    plot_consecutive_analysis,
+    plot_exit_reason_breakdown,
+    plot_mfe_mae_scatter,
+    plot_trade_duration_distribution,
+    plot_trade_size_vs_return,
+    plot_trade_waterfall,
+)
+
+__all__ = [
+    # Executive Summary
+    "create_executive_summary",
+    "create_key_insights",
+    "create_metric_card",
+    "get_traffic_light_color",
+    # Trade Plots (Phase 2)
+    "plot_mfe_mae_scatter",
+    "plot_exit_reason_breakdown",
+    "plot_trade_waterfall",
+    "plot_trade_duration_distribution",
+    "plot_trade_size_vs_return",
+    "plot_consecutive_analysis",
+    # Cost Attribution (Phase 3)
+    "plot_cost_waterfall",
+    "plot_cost_sensitivity",
+    "plot_cost_over_time",
+    "plot_cost_by_asset",
+    "plot_cost_pie",
+    # Statistical Validity (Phase 4)
+    "plot_dsr_gauge",
+    "plot_confidence_intervals",
+    "plot_ras_analysis",
+    "plot_minimum_track_record",
+    "plot_statistical_summary_card",
+    # Unified Tearsheet (Phase 5)
+    "generate_backtest_tearsheet",
+    "BacktestTearsheet",
+    "get_template",
+    "TearsheetTemplate",
+    "TearsheetSection",
+    # Interactive Controls (Phase 6)
+    "get_date_range_html",
+    "get_metric_filter_html",
+    "get_section_navigation_html",
+    "get_drill_down_modal_html",
+    "get_interactive_toolbar_html",
+    "get_theme_switcher_html",
+]