ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/results/signal_results/validation.py

@@ -0,0 +1,147 @@
+"""Validation helper functions for signal result classes.
+
+This module provides utility functions for validating dictionary key consistency
+and normalizing period strings used in signal analysis results.
+
+References
+----------
+Lopez de Prado, M. (2018). "Advances in Financial Machine Learning"
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _validate_dict_keys_match(
+    data: dict[str, Any],
+    required_fields: list[str],
+    optional_fields: list[str] | None = None,
+    reference_field: str | None = None,
+) -> None:
+    """Validate that all dict fields share the same keys.
+
+    Parameters
+    ----------
+    data : dict
+        Model data dictionary.
+    required_fields : list[str]
+        Required dict field names that must all share the same keys.
+    optional_fields : list[str] | None
+        Optional dict field names that, if present and not None, must also share the same keys.
+    reference_field : str | None
+        Field to use as reference for key set. If None, uses first required field.
+
+    Raises
+    ------
+    ValueError
+        If any dict field has different keys than the reference.
+    """
+    if not required_fields:
+        return
+
+    ref_field = reference_field or required_fields[0]
+    ref_keys = set(data.get(ref_field, {}).keys())
+
+    if not ref_keys:
+        return  # Empty reference, nothing to validate
+
+    # Check required fields
+    for field in required_fields:
+        if field == ref_field:
+            continue
+        field_data = data.get(field)
+        if field_data is None:
+            raise ValueError(
+                f"Required field '{field}' is None but '{ref_field}' has keys: {ref_keys}"
+            )
+        field_keys = set(field_data.keys())
+        if field_keys != ref_keys:
+            missing = ref_keys - field_keys
+            extra = field_keys - ref_keys
+            raise ValueError(
+                f"Key mismatch in '{field}': "
+                f"missing={missing or 'none'}, extra={extra or 'none'} "
+                f"(reference: '{ref_field}')"
+            )
+
+    # Check optional fields (only if they exist and are not None)
+    for field in optional_fields or []:
+        field_data = data.get(field)
+        if field_data is None:
+            continue
+        field_keys = set(field_data.keys())
+        if field_keys != ref_keys:
+            missing = ref_keys - field_keys
+            extra = field_keys - ref_keys
+            raise ValueError(
+                f"Key mismatch in '{field}': "
+                f"missing={missing or 'none'}, extra={extra or 'none'} "
+                f"(reference: '{ref_field}')"
+            )
+
+
+def _normalize_period(period: int | str) -> str:
+    """Normalize period to canonical string format used internally.
+
+    Accepts:
+    - int: 21 -> "21D"
+    - str without suffix: "21" -> "21D"
+    - str with suffix: "21D" -> "21D"
+
+    Parameters
+    ----------
+    period : int | str
+        Period as integer or string, with or without 'D' suffix.
+
+    Returns
+    -------
+    str
+        Canonical period key with 'D' suffix (e.g., "21D").
+
+    Examples
+    --------
+    >>> _normalize_period(21)
+    '21D'
+    >>> _normalize_period('21')
+    '21D'
+    >>> _normalize_period('21D')
+    '21D'
+    """
+    if isinstance(period, int):
+        return f"{period}D"
+    period_str = str(period).strip()
+    if period_str.endswith("D"):
+        return period_str
+    return f"{period_str}D"
+
+
+def _figure_from_data(data: dict | str) -> Any:
+    """Convert figure data to Plotly Figure.
+
+    Handles both dict (direct) and JSON string formats transparently.
+    This fixes the type ambiguity where figures may be stored as either
+    Python dicts or JSON strings.
+
+    Parameters
+    ----------
+    data : dict | str
+        Figure data as Python dict or JSON string.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+        Plotly Figure object.
+    """
+    import plotly.io as pio
+
+    if isinstance(data, str):
+        # Already JSON string
+        return pio.from_json(data)
+    elif isinstance(data, dict):
+        # Python dict - convert directly to Figure
+        import plotly.graph_objects as go
+
+        return go.Figure(data)
+    else:
+        raise TypeError(f"Expected dict or str for figure data, got {type(data)}")

ml4t/diagnostic/signal/AGENT.md

@@ -0,0 +1,17 @@
+# signal/ - Factor Signal Analysis
+
+Alphalens-style signal quality analysis.
+
+## Modules
+
+| File | Purpose |
+|------|---------|
+| core.py | `analyze_signal()` entry point |
+| result.py | `SignalResult` dataclass |
+| ic.py | IC computation |
+| quantile.py | Quantile returns, spread |
+| turnover.py | Turnover, autocorrelation |
+
+## Key Functions
+
+`analyze_signal()`, `compute_ic_series()`, `compute_quantile_returns()`, `compute_turnover()`

ml4t/diagnostic/signal/__init__.py

@@ -0,0 +1,69 @@
+"""Signal analysis for factor/alpha evaluation.
+
+This module provides tools for analyzing the predictive power of signals
+(factors) for future returns.
+
+Main Entry Point
+----------------
+analyze_signal : Compute IC, quantile returns, spread, and turnover
+    for a factor signal. This is the recommended way to use this module.
+
+Example
+-------
+>>> from ml4t.diagnostic.signal import analyze_signal
+>>> result = analyze_signal(factor_df, prices_df)
+>>> print(result.summary())
+>>> result.to_json("results.json")
+
+Building Blocks
+---------------
+For custom workflows, use the component functions:
+
+- prepare_data : Join factor with prices and compute forward returns
+- compute_ic_series : Compute IC time series
+- compute_quantile_returns : Compute returns by quantile
+- compute_turnover : Compute factor turnover rate
+- filter_outliers : Remove cross-sectional outliers
+- quantize_factor : Assign quantile labels
+"""
+
+from ml4t.diagnostic.signal._utils import (
+    QuantileMethod,
+    filter_outliers,
+    quantize_factor,
+)
+from ml4t.diagnostic.signal.core import analyze_signal, prepare_data
+from ml4t.diagnostic.signal.quantile import (
+    compute_monotonicity,
+    compute_quantile_returns,
+    compute_spread,
+)
+from ml4t.diagnostic.signal.result import SignalResult
+from ml4t.diagnostic.signal.signal_ic import compute_ic_series, compute_ic_summary
+from ml4t.diagnostic.signal.turnover import (
+    compute_autocorrelation,
+    compute_turnover,
+    estimate_half_life,
+)
+
+__all__ = [
+    # Main entry point
+    "analyze_signal",
+    "SignalResult",
+    # Data preparation
+    "prepare_data",
+    "filter_outliers",
+    "quantize_factor",
+    "QuantileMethod",
+    # IC functions
+    "compute_ic_series",
+    "compute_ic_summary",
+    # Quantile functions
+    "compute_quantile_returns",
+    "compute_spread",
+    "compute_monotonicity",
+    # Turnover functions
+    "compute_turnover",
+    "compute_autocorrelation",
+    "estimate_half_life",
+]

ml4t/diagnostic/signal/_report.py

@@ -0,0 +1,152 @@
+"""Report generation for signal analysis.
+
+Internal module for HTML report generation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ml4t.diagnostic.signal.result import SignalResult
+
+
+def generate_html(result: SignalResult, path: str) -> None:
+    """Generate HTML report from signal analysis results.
+
+    Parameters
+    ----------
+    result : SignalResult
+        Analysis results.
+    path : str
+        Output file path.
+    """
+    try:
+        import plotly.graph_objects as go
+        from plotly.subplots import make_subplots
+    except ImportError:
+        # Fallback to text-only report
+        _generate_text_html(result, path)
+        return
+
+    # Create figure with subplots
+    fig = make_subplots(
+        rows=2,
+        cols=2,
+        subplot_titles=("IC Time Series", "Quantile Returns", "IC Summary", "Spread Summary"),
+        specs=[
+            [{"type": "scatter"}, {"type": "bar"}],
+            [{"type": "table"}, {"type": "table"}],
+        ],
+    )
+
+    # IC Time Series
+    for period_key, ic_vals in result.ic_series.items():
+        if ic_vals:
+            fig.add_trace(
+                go.Scatter(
+                    y=ic_vals,
+                    mode="lines",
+                    name=f"IC {period_key}",
+                ),
+                row=1,
+                col=1,
+            )
+
+    # Quantile Returns (first period)
+    if result.periods:
+        first_period = f"{result.periods[0]}D"
+        q_returns = result.quantile_returns.get(first_period, {})
+        if q_returns:
+            quantiles = sorted(q_returns.keys())
+            returns = [q_returns[q] for q in quantiles]
+            fig.add_trace(
+                go.Bar(
+                    x=[f"Q{q}" for q in quantiles],
+                    y=returns,
+                    name=f"Returns {first_period}",
+                ),
+                row=1,
+                col=2,
+            )
+
+    # IC Summary Table
+    ic_data = []
+    for period in result.periods:
+        period_key = f"{period}D"
+        ic_data.append(
+            [
+                period_key,
+                f"{result.ic.get(period_key, float('nan')):.4f}",
+                f"{result.ic_t_stat.get(period_key, float('nan')):.2f}",
+                f"{result.ic_p_value.get(period_key, float('nan')):.4f}",
+            ]
+        )
+
+    fig.add_trace(
+        go.Table(
+            header={"values": ["Period", "IC", "t-stat", "p-value"]},
+            cells={"values": list(zip(*ic_data)) if ic_data else [[], [], [], []]},
+        ),
+        row=2,
+        col=1,
+    )
+
+    # Spread Summary Table
+    spread_data = []
+    for period in result.periods:
+        period_key = f"{period}D"
+        spread_data.append(
+            [
+                period_key,
+                f"{result.spread.get(period_key, float('nan')):.4f}",
+                f"{result.spread_t_stat.get(period_key, float('nan')):.2f}",
+                f"{result.monotonicity.get(period_key, float('nan')):.3f}",
+            ]
+        )
+
+    fig.add_trace(
+        go.Table(
+            header={"values": ["Period", "Spread", "t-stat", "Monotonicity"]},
+            cells={"values": list(zip(*spread_data)) if spread_data else [[], [], [], []]},
+        ),
+        row=2,
+        col=2,
+    )
+
+    # Update layout
+    fig.update_layout(
+        title_text=f"Signal Analysis: {result.n_assets} assets, {result.n_dates} dates",
+        height=800,
+        showlegend=True,
+    )
+
+    # Write HTML
+    fig.write_html(path, include_plotlyjs=True)
+
+
+def _generate_text_html(result: SignalResult, path: str) -> None:
+    """Generate text-only HTML report (no Plotly)."""
+    html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <title>Signal Analysis Report</title>
+    <style>
+        body {{ font-family: monospace; padding: 20px; }}
+        table {{ border-collapse: collapse; margin: 10px 0; }}
+        th, td {{ border: 1px solid #ddd; padding: 8px; text-align: right; }}
+        th {{ background-color: #f2f2f2; }}
+        pre {{ background-color: #f5f5f5; padding: 15px; }}
+    </style>
+</head>
+<body>
+    <h1>Signal Analysis Report</h1>
+    <pre>{result.summary()}</pre>
+</body>
+</html>"""
+
+    with open(path, "w") as f:
+        f.write(html)
+
+
+__all__ = ["generate_html"]

ml4t/diagnostic/signal/_utils.py

@@ -0,0 +1,261 @@
+"""Internal utilities for signal analysis.
+
+Simple, pure functions for data preparation.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+import polars as pl
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class QuantileMethod(str, Enum):
+    """Method for quantile assignment."""
+
+    QUANTILE = "quantile"  # Equal frequency (rank-based)
+    UNIFORM = "uniform"  # Equal width
+
+
+def ensure_polars(df: pl.DataFrame | pd.DataFrame) -> pl.DataFrame:
+    """Convert pandas DataFrame to Polars if needed.
+
+    Parameters
+    ----------
+    df : pl.DataFrame | pd.DataFrame
+        Input DataFrame.
+
+    Returns
+    -------
+    pl.DataFrame
+        Polars DataFrame.
+    """
+    if isinstance(df, pl.DataFrame):
+        return df
+    # Pandas DataFrame
+    return pl.from_pandas(df)
+
+
+def filter_outliers(
+    data: pl.DataFrame,
+    z_threshold: float = 3.0,
+    factor_col: str = "factor",
+    date_col: str = "date",
+) -> pl.DataFrame:
+    """Filter outliers using cross-sectional z-score.
+
+    Removes observations where factor z-score exceeds threshold
+    within each date's cross-section.
+
+    Parameters
+    ----------
+    data : pl.DataFrame
+        Data with date and factor columns.
+    z_threshold : float, default 3.0
+        Z-score threshold. Values <= 0 disable filtering.
+    factor_col : str, default "factor"
+        Factor column name.
+    date_col : str, default "date"
+        Date column name.
+
+    Returns
+    -------
+    pl.DataFrame
+        Data with outliers removed.
+    """
+    if z_threshold <= 0:
+        return data
+
+    # Cross-sectional z-score with std=0 edge case
+    data = data.with_columns(
+        pl.when(pl.col(factor_col).std().over(date_col) > 0)
+        .then(
+            (pl.col(factor_col) - pl.col(factor_col).mean().over(date_col))
+            / pl.col(factor_col).std().over(date_col)
+        )
+        .otherwise(pl.lit(None))
+        .alias("_zscore")
+    )
+
+    # Keep rows within threshold or with null z-score (constant cross-section)
+    data = data.filter(pl.col("_zscore").is_null() | (pl.col("_zscore").abs() <= z_threshold))
+    return data.drop("_zscore")
+
+
+def quantize_factor(
+    data: pl.DataFrame,
+    n_quantiles: int = 5,
+    method: QuantileMethod = QuantileMethod.QUANTILE,
+    factor_col: str = "factor",
+    date_col: str = "date",
+) -> pl.DataFrame:
+    """Assign quantile labels to factor values within each date.
+
+    Parameters
+    ----------
+    data : pl.DataFrame
+        Data with date and factor columns.
+    n_quantiles : int, default 5
+        Number of quantiles.
+    method : QuantileMethod, default QUANTILE
+        QUANTILE = equal frequency, UNIFORM = equal width.
+    factor_col : str, default "factor"
+        Factor column name.
+    date_col : str, default "date"
+        Date column name.
+
+    Returns
+    -------
+    pl.DataFrame
+        Data with "quantile" column (1 = lowest, n = highest).
+    """
+    if method == QuantileMethod.QUANTILE:
+        # Rank-based (equal count per quantile)
+        data = data.with_columns(
+            (
+                (pl.col(factor_col).rank().over(date_col) - 1)
+                / pl.col(factor_col).count().over(date_col)
+                * n_quantiles
+            )
+            .floor()
+            .cast(pl.Int32)
+            .clip(0, n_quantiles - 1)
+            .alias("_rank")
+        )
+        data = data.with_columns((pl.col("_rank") + 1).alias("quantile"))
+        return data.drop("_rank")
+    else:
+        # Equal width
+        data = data.with_columns(
+            (
+                (pl.col(factor_col) - pl.col(factor_col).min().over(date_col))
+                / (
+                    pl.col(factor_col).max().over(date_col)
+                    - pl.col(factor_col).min().over(date_col)
+                    + 1e-10
+                )
+                * n_quantiles
+            )
+            .floor()
+            .cast(pl.Int32)
+            .clip(0, n_quantiles - 1)
+            .alias("_pct")
+        )
+        data = data.with_columns((pl.col("_pct") + 1).alias("quantile"))
+        return data.drop("_pct")
+
+
+def compute_forward_returns(
+    data: pl.DataFrame,
+    prices: pl.DataFrame,
+    periods: tuple[int, ...],
+    date_col: str = "date",
+    asset_col: str = "asset",
+    price_col: str = "price",
+) -> pl.DataFrame:
+    """Compute forward returns for each period using vectorized operations.
+
+    For each (date, asset), computes return from date to date + period.
+    Forward returns are computed using the factor data's date universe,
+    so period N means "N dates forward in the factor dates", not calendar days.
+
+    Parameters
+    ----------
+    data : pl.DataFrame
+        Factor data with date and asset columns.
+    prices : pl.DataFrame
+        Price data with date, asset, and price columns.
+    periods : tuple[int, ...]
+        Forward return periods in trading days (factor date indices).
+    date_col, asset_col, price_col : str
+        Column names.
+
+    Returns
+    -------
+    pl.DataFrame
+        Data with forward return columns (e.g., "1D_fwd_return").
+    """
+    if data.is_empty():
+        # Add empty columns for each period
+        for p in periods:
+            data = data.with_columns(pl.lit(None).cast(pl.Float64).alias(f"{p}D_fwd_return"))
+        return data
+
+    # 1. Create date index mapping from FACTOR data (not prices)
+    # This ensures forward returns align with factor date universe
+    factor_dates = data.select(date_col).unique().sort(date_col)
+    factor_dates = factor_dates.with_row_index("_factor_date_idx")
+
+    # 2. Join data with current prices
+    result = data.join(
+        prices.select([date_col, asset_col, price_col]).rename({price_col: "_current_price"}),
+        on=[date_col, asset_col],
+        how="left",
+    )
+
+    # 3. Join to get factor date index for each row
+    result = result.join(factor_dates, on=date_col, how="left")
+
+    # 4. For each period, compute forward return via joins
+    for p in periods:
+        col_name = f"{p}D_fwd_return"
+
+        # Create mapping: current_factor_idx -> future_factor_date
+        # future_factor_idx = current_factor_idx + p
+        future_date_map = factor_dates.with_columns(
+            (pl.col("_factor_date_idx") - p).alias("_current_idx")
+        ).filter(pl.col("_current_idx") >= 0)
+
+        # Join to get future date (from factor date sequence)
+        result = result.join(
+            future_date_map.select([date_col, "_current_idx"]).rename(
+                {date_col: f"_future_date_{p}"}
+            ),
+            left_on="_factor_date_idx",
+            right_on="_current_idx",
+            how="left",
+        )
+
+        # Join to get future price (from price data)
+        result = result.join(
+            prices.select([date_col, asset_col, price_col]).rename(
+                {price_col: f"_future_price_{p}"}
+            ),
+            left_on=[f"_future_date_{p}", asset_col],
+            right_on=[date_col, asset_col],
+            how="left",
+        )
+
+        # Compute return: (future - current) / current
+        # Handle NaN in current price (use is_nan check)
+        result = result.with_columns(
+            pl.when(
+                pl.col("_current_price").is_not_null()
+                & pl.col("_current_price").is_not_nan()
+                & pl.col(f"_future_price_{p}").is_not_null()
+                & pl.col(f"_future_price_{p}").is_not_nan()
+                & (pl.col("_current_price") != 0)
+            )
+            .then(
+                (pl.col(f"_future_price_{p}") - pl.col("_current_price")) / pl.col("_current_price")
+            )
+            .otherwise(None)
+            .alias(col_name)
+        )
+
+    # 5. Clean up temporary columns
+    temp_cols = [c for c in result.columns if c.startswith("_")]
+    return result.drop(temp_cols)
+
+
+__all__ = [
+    "QuantileMethod",
+    "ensure_polars",
+    "filter_outliers",
+    "quantize_factor",
+    "compute_forward_returns",
+]