ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/signal/core.py

@@ -0,0 +1,275 @@
+"""Core signal analysis functions.
+
+The main entry point is `analyze_signal()` - one function for 95% of use cases.
+For power users, `prepare_data()` allows custom workflows.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import polars as pl
+
+from ml4t.diagnostic.signal._utils import (
+    QuantileMethod,
+    compute_forward_returns,
+    ensure_polars,
+    filter_outliers,
+    quantize_factor,
+)
+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,
+)
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+def prepare_data(
+    factor: pl.DataFrame | pd.DataFrame,
+    prices: pl.DataFrame | pd.DataFrame,
+    periods: tuple[int, ...] = (1, 5, 21),
+    quantiles: int = 5,
+    filter_zscore: float | None = 3.0,
+    quantile_method: str = "quantile",
+    factor_col: str = "factor",
+    date_col: str = "date",
+    asset_col: str = "asset",
+    price_col: str = "price",
+) -> pl.DataFrame:
+    """Prepare factor data for analysis.
+
+    Joins factor with prices, computes forward returns, filters outliers,
+    and assigns quantiles.
+
+    Parameters
+    ----------
+    factor : DataFrame
+        Factor data with columns: date, asset, factor.
+    prices : DataFrame
+        Price data with columns: date, asset, price.
+    periods : tuple[int, ...]
+        Forward return periods in trading days.
+    quantiles : int
+        Number of quantiles.
+    filter_zscore : float | None
+        Z-score threshold for outlier filtering. None disables.
+    quantile_method : str
+        "quantile" (equal frequency) or "uniform" (equal width).
+    factor_col, date_col, asset_col, price_col : str
+        Column names.
+
+    Returns
+    -------
+    pl.DataFrame
+        Prepared data with: date, asset, factor, quantile, {period}D_fwd_return.
+    """
+    # Convert to Polars
+    factor_pl = ensure_polars(factor)
+    prices_pl = ensure_polars(prices)
+
+    # Compute forward returns
+    data = compute_forward_returns(factor_pl, prices_pl, periods, date_col, asset_col, price_col)
+
+    # Filter outliers
+    if filter_zscore is not None and filter_zscore > 0:
+        data = filter_outliers(data, filter_zscore, factor_col, date_col)
+
+    # Assign quantiles
+    method = QuantileMethod.QUANTILE if quantile_method == "quantile" else QuantileMethod.UNIFORM
+    data = quantize_factor(data, quantiles, method, factor_col, date_col)
+
+    return data
+
+
+def analyze_signal(
+    factor: pl.DataFrame | pd.DataFrame,
+    prices: pl.DataFrame | pd.DataFrame,
+    *,
+    periods: tuple[int, ...] = (1, 5, 21),
+    quantiles: int = 5,
+    filter_zscore: float | None = 3.0,
+    quantile_method: str = "quantile",
+    ic_method: str = "spearman",
+    compute_turnover_flag: bool = True,
+    autocorrelation_lags: int = 10,
+    min_assets: int = 10,
+    factor_col: str = "factor",
+    date_col: str = "date",
+    asset_col: str = "asset",
+    price_col: str = "price",
+) -> SignalResult:
+    """Analyze a factor signal.
+
+    This is the main entry point for signal analysis. Computes IC, quantile
+    returns, spread, monotonicity, and optionally turnover/autocorrelation.
+
+    Parameters
+    ----------
+    factor : DataFrame
+        Factor data with columns: date, asset, factor.
+        Higher factor values should predict higher returns.
+    prices : DataFrame
+        Price data with columns: date, asset, price.
+    periods : tuple[int, ...]
+        Forward return periods in trading days (default: 1, 5, 21 days).
+    quantiles : int
+        Number of quantiles for grouping assets (default: 5 quintiles).
+    filter_zscore : float | None
+        Z-score threshold for outlier filtering. None disables.
+    quantile_method : str
+        "quantile" (equal frequency) or "uniform" (equal width).
+    ic_method : str
+        "spearman" (rank correlation) or "pearson" (linear correlation).
+    compute_turnover_flag : bool
+        Whether to compute turnover and autocorrelation metrics.
+    autocorrelation_lags : int
+        Number of lags for autocorrelation analysis.
+    min_assets : int
+        Minimum assets per date for IC computation.
+    factor_col, date_col, asset_col, price_col : str
+        Column names.
+
+    Returns
+    -------
+    SignalResult
+        Analysis results with IC, quantile returns, spread, monotonicity,
+        and optionally turnover metrics.
+
+    Examples
+    --------
+    Basic usage:
+
+    >>> result = analyze_signal(factor_df, prices_df)
+    >>> print(result.summary())
+    >>> result.to_json("results.json")
+
+    With custom parameters:
+
+    >>> result = analyze_signal(
+    ...     factor_df, prices_df,
+    ...     periods=(1, 5, 21, 63),
+    ...     quantiles=10,
+    ...     ic_method="pearson",
+    ... )
+    """
+    # Prepare data
+    data = prepare_data(
+        factor,
+        prices,
+        periods,
+        quantiles,
+        filter_zscore,
+        quantile_method,
+        factor_col,
+        date_col,
+        asset_col,
+        price_col,
+    )
+
+    # Extract metadata
+    n_assets = data.select(asset_col).n_unique()
+    n_dates = data.select(date_col).n_unique()
+    all_dates = data.select(date_col).unique().sort(date_col).to_series().to_list()
+    date_range = (str(all_dates[0]), str(all_dates[-1])) if all_dates else ("", "")
+
+    # Initialize result dicts
+    ic: dict[str, float] = {}
+    ic_std: dict[str, float] = {}
+    ic_t_stat: dict[str, float] = {}
+    ic_p_value: dict[str, float] = {}
+    ic_ir: dict[str, float] = {}
+    ic_positive_pct: dict[str, float] = {}
+    ic_series: dict[str, list[float]] = {}
+    quantile_returns: dict[str, dict[int, float]] = {}
+    spread: dict[str, float] = {}
+    spread_t_stat: dict[str, float] = {}
+    spread_p_value: dict[str, float] = {}
+    monotonicity: dict[str, float] = {}
+
+    # Compute metrics for each period
+    for period in periods:
+        period_key = f"{period}D"
+
+        # IC
+        dates, ic_vals = compute_ic_series(
+            data, period, ic_method, factor_col, date_col, min_assets
+        )
+        summary = compute_ic_summary(ic_vals)
+
+        ic[period_key] = summary["mean"]
+        ic_std[period_key] = summary["std"]
+        ic_t_stat[period_key] = summary["t_stat"]
+        ic_p_value[period_key] = summary["p_value"]
+        ic_series[period_key] = ic_vals
+
+        # IC Information Ratio and positive percentage
+        if summary["std"] > 0:
+            ic_ir[period_key] = summary["mean"] / summary["std"]
+        else:
+            ic_ir[period_key] = 0.0
+        if ic_vals:
+            ic_positive_pct[period_key] = sum(1 for x in ic_vals if x > 0) / len(ic_vals) * 100
+        else:
+            ic_positive_pct[period_key] = 0.0
+
+        # Quantile returns
+        q_returns = compute_quantile_returns(data, period, quantiles)
+        quantile_returns[period_key] = q_returns
+
+        # Spread
+        spread_stats = compute_spread(data, period, quantiles)
+        spread[period_key] = spread_stats["spread"]
+        spread_t_stat[period_key] = spread_stats["t_stat"]
+        spread_p_value[period_key] = spread_stats["p_value"]
+
+        # Monotonicity
+        monotonicity[period_key] = compute_monotonicity(q_returns)
+
+    # Turnover (optional)
+    turnover_dict: dict[str, float] | None = None
+    autocorr: list[float] | None = None
+    half_life: float | None = None
+
+    if compute_turnover_flag:
+        turnover_val = compute_turnover(data, quantiles, date_col, asset_col)
+        turnover_dict = {f"{p}D": turnover_val for p in periods}
+
+        lags = list(range(1, autocorrelation_lags + 1))
+        autocorr = compute_autocorrelation(data, lags, date_col, asset_col, factor_col)
+        half_life = estimate_half_life(autocorr)
+
+    return SignalResult(
+        ic=ic,
+        ic_std=ic_std,
+        ic_t_stat=ic_t_stat,
+        ic_p_value=ic_p_value,
+        ic_ir=ic_ir,
+        ic_positive_pct=ic_positive_pct,
+        ic_series=ic_series,
+        quantile_returns=quantile_returns,
+        spread=spread,
+        spread_t_stat=spread_t_stat,
+        spread_p_value=spread_p_value,
+        monotonicity=monotonicity,
+        turnover=turnover_dict,
+        autocorrelation=autocorr,
+        half_life=half_life,
+        n_assets=n_assets,
+        n_dates=n_dates,
+        date_range=date_range,
+        periods=periods,
+        quantiles=quantiles,
+    )
+
+
+__all__ = ["prepare_data", "analyze_signal"]

ml4t/diagnostic/signal/quantile.py

@@ -0,0 +1,148 @@
+"""Quantile analysis functions.
+
+Simple, pure functions for analyzing returns by quantile.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import polars as pl
+from scipy.stats import spearmanr, ttest_ind
+
+
+def compute_quantile_returns(
+    data: pl.DataFrame,
+    period: int,
+    n_quantiles: int,
+    quantile_col: str = "quantile",
+) -> dict[int, float]:
+    """Compute mean forward returns by quantile.
+
+    Parameters
+    ----------
+    data : pl.DataFrame
+        Data with quantile and forward return columns.
+    period : int
+        Forward return period in days.
+    n_quantiles : int
+        Number of quantiles.
+    quantile_col : str, default "quantile"
+        Quantile column name.
+
+    Returns
+    -------
+    dict[int, float]
+        Mean return by quantile (1 = lowest factor).
+    """
+    return_col = f"{period}D_fwd_return"
+
+    if return_col not in data.columns:
+        return dict.fromkeys(range(1, n_quantiles + 1), float("nan"))
+
+    result: dict[int, float] = {}
+
+    quantile_means = (
+        data.filter(pl.col(return_col).is_not_null())
+        .group_by(quantile_col)
+        .agg(pl.col(return_col).mean().alias("mean_return"))
+        .sort(quantile_col)
+    )
+
+    for row in quantile_means.iter_rows(named=True):
+        result[int(row[quantile_col])] = float(row["mean_return"])
+
+    # Fill missing quantiles
+    for q in range(1, n_quantiles + 1):
+        if q not in result:
+            result[q] = float("nan")
+
+    return result
+
+
+def compute_spread(
+    data: pl.DataFrame,
+    period: int,
+    n_quantiles: int,
+    quantile_col: str = "quantile",
+) -> dict[str, float]:
+    """Compute long-short spread and statistics.
+
+    Parameters
+    ----------
+    data : pl.DataFrame
+        Data with quantile and forward return columns.
+    period : int
+        Forward return period in days.
+    n_quantiles : int
+        Number of quantiles.
+    quantile_col : str, default "quantile"
+        Quantile column name.
+
+    Returns
+    -------
+    dict[str, float]
+        spread, t_stat, p_value
+    """
+    return_col = f"{period}D_fwd_return"
+
+    if return_col not in data.columns:
+        return {
+            "spread": float("nan"),
+            "t_stat": float("nan"),
+            "p_value": float("nan"),
+        }
+
+    top_returns = data.filter(pl.col(quantile_col) == n_quantiles)[return_col].to_numpy()
+    bottom_returns = data.filter(pl.col(quantile_col) == 1)[return_col].to_numpy()
+
+    top_returns = top_returns[~np.isnan(top_returns)]
+    bottom_returns = bottom_returns[~np.isnan(bottom_returns)]
+
+    if len(top_returns) < 2 or len(bottom_returns) < 2:
+        return {
+            "spread": float("nan"),
+            "t_stat": float("nan"),
+            "p_value": float("nan"),
+        }
+
+    spread = float(np.mean(top_returns) - np.mean(bottom_returns))
+    t_stat, p_value = ttest_ind(top_returns, bottom_returns)
+
+    return {
+        "spread": spread,
+        "t_stat": float(t_stat),
+        "p_value": float(p_value),
+    }
+
+
+def compute_monotonicity(
+    quantile_returns: dict[int, float],
+) -> float:
+    """Compute monotonicity of quantile returns.
+
+    Measures how well returns increase monotonically across quantiles.
+    Uses Spearman correlation: 1.0 = perfect increase, -1.0 = perfect decrease.
+
+    Parameters
+    ----------
+    quantile_returns : dict[int, float]
+        Mean return by quantile.
+
+    Returns
+    -------
+    float
+        Monotonicity score (-1 to 1).
+    """
+    # Sort by quantile
+    sorted_items = sorted(quantile_returns.items())
+    quantiles = [q for q, r in sorted_items if not np.isnan(r)]
+    returns = [r for q, r in sorted_items if not np.isnan(r)]
+
+    if len(quantiles) < 3:
+        return float("nan")
+
+    rho, _ = spearmanr(quantiles, returns)
+    return float(rho) if not np.isnan(rho) else float("nan")
+
+
+__all__ = ["compute_quantile_returns", "compute_spread", "compute_monotonicity"]

ml4t/diagnostic/signal/result.py

@@ -0,0 +1,214 @@
+"""Signal analysis result dataclass.
+
+Simple, immutable result container for signal analysis.
+No Pydantic, no inheritance - just a frozen dataclass.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SignalResult:
+    """Immutable result from signal analysis.
+
+    All metrics are keyed by period (e.g., "1D", "5D", "21D").
+
+    Attributes
+    ----------
+    ic : dict[str, float]
+        Mean IC by period.
+    ic_std : dict[str, float]
+        IC standard deviation by period.
+    ic_t_stat : dict[str, float]
+        T-statistic for IC != 0.
+    ic_p_value : dict[str, float]
+        P-value for IC significance.
+    ic_ir : dict[str, float]
+        Information Ratio (IC mean / IC std) by period.
+    ic_positive_pct : dict[str, float]
+        Percentage of periods with positive IC.
+    ic_series : dict[str, list[float]]
+        IC time series by period.
+    quantile_returns : dict[str, dict[int, float]]
+        Mean returns by period and quantile.
+    spread : dict[str, float]
+        Top minus bottom quantile spread.
+    spread_t_stat : dict[str, float]
+        T-statistic for spread.
+    spread_p_value : dict[str, float]
+        P-value for spread significance.
+    monotonicity : dict[str, float]
+        Rank correlation of quantile returns (how monotonic).
+    turnover : dict[str, float] | None
+        Mean turnover rate by period.
+    autocorrelation : list[float] | None
+        Factor autocorrelation at lags 1, 2, ...
+    half_life : float | None
+        Estimated signal half-life in periods.
+    n_assets : int
+        Number of unique assets.
+    n_dates : int
+        Number of unique dates.
+    date_range : tuple[str, str]
+        (first_date, last_date).
+    periods : tuple[int, ...]
+        Forward return periods analyzed.
+    quantiles : int
+        Number of quantiles used.
+    """
+
+    # IC metrics
+    ic: dict[str, float]
+    ic_std: dict[str, float]
+    ic_t_stat: dict[str, float]
+    ic_p_value: dict[str, float]
+    ic_ir: dict[str, float] = field(default_factory=dict)  # Information Ratio (ic/ic_std)
+    ic_positive_pct: dict[str, float] = field(default_factory=dict)  # % of positive ICs
+    ic_series: dict[str, list[float]] = field(default_factory=dict)
+
+    # Quantile metrics
+    quantile_returns: dict[str, dict[int, float]] = field(default_factory=dict)
+    spread: dict[str, float] = field(default_factory=dict)
+    spread_t_stat: dict[str, float] = field(default_factory=dict)
+    spread_p_value: dict[str, float] = field(default_factory=dict)
+    monotonicity: dict[str, float] = field(default_factory=dict)
+
+    # Turnover (optional)
+    turnover: dict[str, float] | None = None
+    autocorrelation: list[float] | None = None
+    half_life: float | None = None
+
+    # Metadata
+    n_assets: int = 0
+    n_dates: int = 0
+    date_range: tuple[str, str] = ("", "")
+    periods: tuple[int, ...] = ()
+    quantiles: int = 5
+
+    def summary(self) -> str:
+        """Human-readable summary of results."""
+        lines = [
+            f"Signal Analysis: {self.n_assets} assets, {self.n_dates} dates",
+            f"Date range: {self.date_range[0]} to {self.date_range[1]}",
+            f"Periods: {self.periods}, Quantiles: {self.quantiles}",
+            "",
+            "IC Summary:",
+        ]
+
+        for period in [f"{p}D" for p in self.periods]:
+            ic_val = self.ic.get(period, float("nan"))
+            t = self.ic_t_stat.get(period, float("nan"))
+            p = self.ic_p_value.get(period, float("nan"))
+            ir = self.ic_ir.get(period, float("nan"))
+            pos_pct = self.ic_positive_pct.get(period, float("nan"))
+            sig = "*" if p < 0.05 else ""
+            lines.append(
+                f"  {period}: IC={ic_val:+.4f} (t={t:.2f}, p={p:.3f}){sig}, IR={ir:.2f}, +%={pos_pct:.0f}%"
+            )
+
+        lines.append("\nSpread (Top - Bottom):")
+        for period in [f"{p}D" for p in self.periods]:
+            spread = self.spread.get(period, float("nan"))
+            t = self.spread_t_stat.get(period, float("nan"))
+            p = self.spread_p_value.get(period, float("nan"))
+            sig = "*" if p < 0.05 else ""
+            lines.append(f"  {period}: {spread:+.4f} (t={t:.2f}, p={p:.3f}){sig}")
+
+        lines.append("\nMonotonicity:")
+        for period in [f"{p}D" for p in self.periods]:
+            mono = self.monotonicity.get(period, float("nan"))
+            lines.append(f"  {period}: {mono:+.3f}")
+
+        if self.turnover:
+            lines.append("\nTurnover:")
+            for period in [f"{p}D" for p in self.periods]:
+                t = self.turnover.get(period, float("nan"))
+                lines.append(f"  {period}: {t:.1%}")
+
+        if self.half_life is not None:
+            lines.append(f"\nHalf-life: {self.half_life:.1f} periods")
+
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Export to dictionary."""
+        return asdict(self)
+
+    def to_json(self, path: str | None = None, indent: int = 2) -> str:
+        """Export to JSON string or file.
+
+        Parameters
+        ----------
+        path : str | None
+            If provided, write to file. Otherwise return string.
+        indent : int
+            JSON indentation level.
+
+        Returns
+        -------
+        str
+            JSON string.
+        """
+        data = self.to_dict()
+
+        def convert(obj: Any) -> Any:
+            if isinstance(obj, float) and (obj != obj):  # NaN check
+                return None
+            if isinstance(obj, tuple):
+                return list(obj)
+            return obj
+
+        def serialize(d: Any) -> Any:
+            if isinstance(d, dict):
+                return {str(k): serialize(v) for k, v in d.items()}
+            if isinstance(d, list):
+                return [serialize(v) for v in d]
+            return convert(d)
+
+        serialized = serialize(data)
+        json_str = json.dumps(serialized, indent=indent)
+
+        if path:
+            with open(path, "w") as f:
+                f.write(json_str)
+
+        return json_str
+
+    @classmethod
+    def from_json(cls, path: str) -> SignalResult:
+        """Load from JSON file.
+
+        Parameters
+        ----------
+        path : str
+            Path to JSON file.
+
+        Returns
+        -------
+        SignalResult
+            Loaded result.
+        """
+        with open(path) as f:
+            data = json.load(f)
+
+        # Convert lists back to tuples for immutable fields
+        if "date_range" in data:
+            data["date_range"] = tuple(data["date_range"])
+        if "periods" in data:
+            data["periods"] = tuple(data["periods"])
+
+        # Convert quantile keys back to int
+        if "quantile_returns" in data:
+            data["quantile_returns"] = {
+                period: {int(k): v for k, v in qr.items()}
+                for period, qr in data["quantile_returns"].items()
+            }
+
+        return cls(**data)
+
+
+__all__ = ["SignalResult"]