ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/evaluation/metrics/monotonicity.py

@@ -0,0 +1,226 @@
+"""Monotonicity: Test monotonic relationship between feature values and outcomes.
+
+Monotonicity is a key property for predictive features - we expect higher
+(or lower) feature values to consistently correspond to higher outcomes.
+"""
+
+from typing import TYPE_CHECKING, Any, Union
+
+import numpy as np
+import pandas as pd
+import polars as pl
+from scipy import stats
+from scipy.stats import spearmanr
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def compute_monotonicity(
+    features: Union[pl.DataFrame, pd.DataFrame, "NDArray[Any]"],
+    outcomes: Union[pl.DataFrame, pd.DataFrame, "NDArray[Any]"],
+    n_quantiles: int = 5,
+    feature_col: str | None = None,
+    outcome_col: str | None = None,
+    method: str = "spearman",
+) -> dict[str, Any]:
+    """Test monotonic relationship between feature values and outcomes.
+
+    Monotonicity is a key property for predictive features - we expect higher
+    (or lower) feature values to consistently correspond to higher outcomes.
+    Non-monotonic relationships often indicate:
+    1. Feature needs transformation (e.g., absolute value, log)
+    2. Feature has regime-dependent behavior
+    3. Feature is not truly predictive
+
+    This function bins features into quantiles and checks if mean outcomes
+    increase/decrease monotonically across bins.
+
+    Parameters
+    ----------
+    features : Union[pl.DataFrame, pd.DataFrame, np.ndarray]
+        Feature values to test
+    outcomes : Union[pl.DataFrame, pd.DataFrame, np.ndarray]
+        Outcome values (typically returns)
+    n_quantiles : int, default 5
+        Number of quantile bins (5 = quintiles, 10 = deciles)
+    feature_col : str | None, default None
+        Column name for features (if DataFrame)
+    outcome_col : str | None, default None
+        Column name for outcomes (if DataFrame)
+    method : str, default "spearman"
+        Correlation method: "spearman" or "pearson"
+
+    Returns
+    -------
+    dict[str, Any]
+        Dictionary with monotonicity analysis:
+        - correlation: Spearman/Pearson correlation
+        - p_value: Statistical significance of correlation
+        - quantile_means: Mean outcome per quantile
+        - quantile_labels: Quantile labels (Q1, Q2, ...)
+        - is_monotonic: Boolean, True if strictly monotonic
+        - monotonicity_score: Fraction of quantile pairs that are monotonic (0-1)
+        - direction: "increasing", "decreasing", or "non-monotonic"
+        - n_observations: Total observations
+        - n_per_quantile: Observations per quantile
+
+    Examples
+    --------
+    >>> # Test if momentum predicts returns
+    >>> features = df['momentum']
+    >>> outcomes = df['forward_return']
+    >>> result = compute_monotonicity(features, outcomes, n_quantiles=5)
+    >>>
+    >>> print(f"Correlation: {result['correlation']:.3f}")
+    >>> print(f"P-value: {result['p_value']:.4f}")
+    >>> print(f"Monotonic: {result['is_monotonic']}")
+    >>> print(f"Direction: {result['direction']}")
+    >>> print(f"Quantile means: {result['quantile_means']}")
+    Correlation: 0.156
+    P-value: 0.0001
+    Monotonic: True
+    Direction: increasing
+    Quantile means: [-0.002, 0.001, 0.003, 0.005, 0.008]
+
+    Notes
+    -----
+    Monotonicity Score:
+    - 1.0: Perfect monotonicity (all adjacent quantiles ordered correctly)
+    - 0.8-1.0: Strong monotonicity (minor violations)
+    - 0.6-0.8: Moderate monotonicity
+    - <0.6: Weak or no monotonicity
+
+    Common Patterns:
+    - Monotonic increasing: Good positive predictor
+    - Monotonic decreasing: Good negative predictor (consider sign flip)
+    - U-shaped: Consider absolute value or squared feature
+    - Flat: Feature not predictive
+
+    References
+    ----------
+    .. [1] Kakushadze, Z., & Serur, J. A. (2018). "151 Trading Strategies."
+    """
+    # Extract feature and outcome arrays
+    feature_vals: NDArray[Any]
+    if isinstance(features, pl.DataFrame):
+        if feature_col is None:
+            raise ValueError("feature_col must be specified for DataFrame input")
+        feature_vals = features[feature_col].to_numpy()
+    elif isinstance(features, pd.DataFrame):
+        if feature_col is None:
+            raise ValueError("feature_col must be specified for DataFrame input")
+        feature_vals = features[feature_col].to_numpy()
+    else:
+        feature_vals = np.asarray(features).flatten()
+
+    outcome_vals: NDArray[Any]
+    if isinstance(outcomes, pl.DataFrame):
+        if outcome_col is None:
+            raise ValueError("outcome_col must be specified for DataFrame input")
+        outcome_vals = outcomes[outcome_col].to_numpy()
+    elif isinstance(outcomes, pd.DataFrame):
+        if outcome_col is None:
+            raise ValueError("outcome_col must be specified for DataFrame input")
+        outcome_vals = outcomes[outcome_col].to_numpy()
+    else:
+        outcome_vals = np.asarray(outcomes).flatten()
+
+    # Validate inputs
+    if len(feature_vals) != len(outcome_vals):
+        raise ValueError(
+            f"Features ({len(feature_vals)}) and outcomes ({len(outcome_vals)}) must have same length"
+        )
+
+    # Remove NaN values
+    valid_mask = ~(np.isnan(feature_vals.astype(float)) | np.isnan(outcome_vals.astype(float)))
+    feature_clean = feature_vals[valid_mask]
+    outcome_clean = outcome_vals[valid_mask]
+
+    n = len(feature_clean)
+    if n < n_quantiles * 2:
+        # Insufficient data for quantile analysis
+        return {
+            "correlation": np.nan,
+            "p_value": np.nan,
+            "quantile_means": [],
+            "quantile_labels": [],
+            "is_monotonic": False,
+            "monotonicity_score": 0.0,
+            "direction": "insufficient_data",
+            "n_observations": n,
+            "n_per_quantile": [],
+        }
+
+    # Compute correlation
+    if method == "spearman":
+        correlation, p_value = spearmanr(feature_clean, outcome_clean)
+    elif method == "pearson":
+        correlation, p_value = stats.pearsonr(feature_clean, outcome_clean)
+    else:
+        raise ValueError(f"Unknown method: {method}. Use 'spearman' or 'pearson'.")
+
+    # Create quantile bins
+    quantile_edges = np.linspace(0, 100, n_quantiles + 1)
+    quantile_bins = np.percentile(feature_clean, quantile_edges)
+
+    # Assign observations to quantiles
+    quantile_assignments = np.digitize(feature_clean, quantile_bins[1:-1])  # 0-indexed bins
+
+    # Compute mean outcome per quantile
+    quantile_means = []
+    n_per_quantile = []
+
+    for q in range(n_quantiles):
+        mask = quantile_assignments == q
+        if np.sum(mask) > 0:
+            quantile_means.append(float(np.mean(outcome_clean[mask])))
+            n_per_quantile.append(int(np.sum(mask)))
+        else:
+            quantile_means.append(np.nan)
+            n_per_quantile.append(0)
+
+    # Check monotonicity
+    # Count how many adjacent pairs are ordered correctly
+    monotonic_pairs = 0
+    total_pairs = 0
+
+    for i in range(len(quantile_means) - 1):
+        if not (np.isnan(quantile_means[i]) or np.isnan(quantile_means[i + 1])):
+            total_pairs += 1
+            # Check if ordered (either increasing or decreasing)
+            if correlation > 0:
+                # Expect increasing
+                if quantile_means[i + 1] > quantile_means[i]:
+                    monotonic_pairs += 1
+            # Expect decreasing
+            elif quantile_means[i + 1] < quantile_means[i]:
+                monotonic_pairs += 1
+
+    monotonicity_score = monotonic_pairs / total_pairs if total_pairs > 0 else 0.0
+
+    # Strict monotonicity check (all pairs ordered correctly)
+    is_monotonic = monotonicity_score == 1.0
+
+    # Determine direction
+    if is_monotonic:
+        direction = "increasing" if correlation > 0 else "decreasing"
+    elif monotonicity_score >= 0.8:
+        direction = "mostly_" + ("increasing" if correlation > 0 else "decreasing")
+    else:
+        direction = "non_monotonic"
+
+    # Create quantile labels
+    quantile_labels = [f"Q{i + 1}" for i in range(n_quantiles)]
+
+    return {
+        "correlation": float(correlation),
+        "p_value": float(p_value),
+        "quantile_means": quantile_means,
+        "quantile_labels": quantile_labels,
+        "is_monotonic": is_monotonic,
+        "monotonicity_score": float(monotonicity_score),
+        "direction": direction,
+        "n_observations": n,
+        "n_per_quantile": n_per_quantile,
+    }

ml4t/diagnostic/evaluation/metrics/risk_adjusted.py

@@ -0,0 +1,324 @@
+"""Risk-adjusted performance metrics: Sharpe, Sortino, Maximum Drawdown.
+
+This module provides standard risk-adjusted return metrics used in portfolio
+and strategy evaluation.
+"""
+
+from typing import TYPE_CHECKING, Any, Union
+
+import numpy as np
+import pandas as pd
+import polars as pl
+
+from ml4t.diagnostic.backends.adapter import DataFrameAdapter
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def sharpe_ratio(
+    returns: Union[pl.Series, pd.Series, "NDArray[Any]"],
+    risk_free_rate: float = 0.0,
+    annualization_factor: float | None = None,
+    confidence_intervals: bool = False,
+    alpha: float = 0.05,
+    bootstrap_samples: int = 1000,
+    random_state: int | None = None,
+) -> float | dict[str, float]:
+    """Calculate Sharpe Ratio with optional confidence intervals.
+
+    The Sharpe Ratio measures risk-adjusted returns by dividing excess returns
+    by return volatility. Higher values indicate better risk-adjusted performance.
+
+    Parameters
+    ----------
+    returns : Union[pl.Series, pd.Series, np.ndarray]
+        Time series of returns
+    risk_free_rate : float, default 0.0
+        Risk-free rate (same frequency as returns)
+    annualization_factor : Optional[float], default None
+        Factor to annualize the ratio. If None, no annualization applied
+    confidence_intervals : bool, default False
+        Whether to compute bootstrap confidence intervals
+    alpha : float, default 0.05
+        Significance level for confidence intervals
+    bootstrap_samples : int, default 1000
+        Number of bootstrap samples for confidence intervals
+    random_state : Optional[int], default None
+        Random seed for reproducible bootstrap samples
+
+    Returns
+    -------
+    Union[float, dict]
+        If confidence_intervals=False: Sharpe ratio value
+        If confidence_intervals=True: dict with 'sharpe', 'lower_ci', 'upper_ci'
+
+    Examples
+    --------
+    >>> returns = np.array([0.01, 0.02, -0.01, 0.03, 0.00])
+    >>> sharpe = sharpe_ratio(returns, annualization_factor=252)
+    >>> print(f"Sharpe Ratio: {sharpe:.3f}")
+
+    >>> # With confidence intervals
+    >>> result = sharpe_ratio(returns, confidence_intervals=True, random_state=42)
+    >>> print(f"Sharpe: {result['sharpe']:.3f}")
+    """
+    if confidence_intervals:
+        return sharpe_ratio_with_ci(
+            returns, risk_free_rate, annualization_factor, alpha, bootstrap_samples, random_state
+        )
+    return _sharpe_ratio_core(returns, risk_free_rate, annualization_factor)
+
+
+def _sharpe_ratio_core(
+    returns: Union[pl.Series, pd.Series, "NDArray[Any]"],
+    risk_free_rate: float = 0.0,
+    annualization_factor: float | None = None,
+) -> float:
+    """Calculate Sharpe Ratio (core calculation without confidence intervals).
+
+    Parameters
+    ----------
+    returns : Union[pl.Series, pd.Series, np.ndarray]
+        Time series of returns
+    risk_free_rate : float, default 0.0
+        Risk-free rate (same frequency as returns)
+    annualization_factor : Optional[float], default None
+        Factor to annualize the ratio
+
+    Returns
+    -------
+    float
+        Sharpe ratio value
+    """
+    ret_array = DataFrameAdapter.to_numpy(returns).flatten()
+    ret_clean = ret_array[~np.isnan(ret_array)]
+
+    if len(ret_clean) < 2:
+        return np.nan
+
+    excess_returns = ret_clean - risk_free_rate
+    mean_excess = np.mean(excess_returns)
+    std_excess = np.std(excess_returns, ddof=1)
+
+    if std_excess == 0:
+        if mean_excess > 0:
+            return np.inf
+        if mean_excess < 0:
+            return -np.inf
+        return np.nan
+
+    sharpe = mean_excess / std_excess
+
+    if annualization_factor is not None and not np.isinf(sharpe) and not np.isnan(sharpe):
+        sharpe *= np.sqrt(annualization_factor)
+
+    return float(sharpe) if not np.isinf(sharpe) else sharpe
+
+
+def sharpe_ratio_with_ci(
+    returns: Union[pl.Series, pd.Series, "NDArray[Any]"],
+    risk_free_rate: float = 0.0,
+    annualization_factor: float | None = None,
+    alpha: float = 0.05,
+    bootstrap_samples: int = 1000,
+    random_state: int | None = None,
+) -> dict[str, float]:
+    """Calculate Sharpe Ratio with bootstrap confidence intervals.
+
+    Parameters
+    ----------
+    returns : Union[pl.Series, pd.Series, np.ndarray]
+        Time series of returns
+    risk_free_rate : float, default 0.0
+        Risk-free rate (same frequency as returns)
+    annualization_factor : Optional[float], default None
+        Factor to annualize the ratio
+    alpha : float, default 0.05
+        Significance level for confidence intervals
+    bootstrap_samples : int, default 1000
+        Number of bootstrap samples for confidence intervals
+    random_state : Optional[int], default None
+        Random seed for reproducible bootstrap samples
+
+    Returns
+    -------
+    dict[str, float]
+        Dict with 'sharpe', 'lower_ci', 'upper_ci' keys
+    """
+    sharpe = _sharpe_ratio_core(returns, risk_free_rate, annualization_factor)
+
+    if np.isnan(sharpe) or np.isinf(sharpe):
+        return {"sharpe": sharpe, "lower_ci": np.nan, "upper_ci": np.nan}
+
+    ret_array = DataFrameAdapter.to_numpy(returns).flatten()
+    ret_clean = ret_array[~np.isnan(ret_array)]
+
+    if len(ret_clean) < 10:
+        return {"sharpe": sharpe, "lower_ci": np.nan, "upper_ci": np.nan}
+
+    if random_state is not None:
+        np.random.seed(random_state)
+
+    bootstrap_sharpes = []
+    for _ in range(bootstrap_samples):
+        bootstrap_sample = np.random.choice(ret_clean, size=len(ret_clean), replace=True)
+        bootstrap_excess = bootstrap_sample - risk_free_rate
+        bootstrap_mean = np.mean(bootstrap_excess)
+        bootstrap_std = np.std(bootstrap_excess, ddof=1)
+
+        if bootstrap_std > 0:
+            bs_sharpe = bootstrap_mean / bootstrap_std
+            if annualization_factor is not None:
+                bs_sharpe *= np.sqrt(annualization_factor)
+            bootstrap_sharpes.append(bs_sharpe)
+
+    if len(bootstrap_sharpes) == 0:
+        return {"sharpe": sharpe, "lower_ci": np.nan, "upper_ci": np.nan}
+
+    lower_ci = np.percentile(bootstrap_sharpes, (alpha / 2) * 100)
+    upper_ci = np.percentile(bootstrap_sharpes, (1 - alpha / 2) * 100)
+
+    return {"sharpe": sharpe, "lower_ci": float(lower_ci), "upper_ci": float(upper_ci)}
+
+
+def maximum_drawdown(
+    returns: Union[pl.Series, pd.Series, "NDArray[Any]"],
+    cumulative: bool = False,
+) -> dict[str, float]:
+    """Calculate Maximum Drawdown and related statistics.
+
+    Maximum Drawdown measures the largest peak-to-trough decline in cumulative
+    returns. It represents the worst-case loss an investor would experience.
+
+    Parameters
+    ----------
+    returns : Union[pl.Series, pd.Series, np.ndarray]
+        Time series of returns (or cumulative returns if cumulative=True)
+    cumulative : bool, default False
+        Whether input is already cumulative returns
+
+    Returns
+    -------
+    dict
+        Dictionary with 'max_drawdown', 'max_drawdown_duration', 'peak_date', 'trough_date'
+
+    Examples
+    --------
+    >>> returns = np.array([0.10, -0.05, 0.08, -0.12, 0.03])
+    >>> dd = maximum_drawdown(returns)
+    >>> print(f"Max Drawdown: {dd['max_drawdown']:.3f}")
+    Max Drawdown: -0.102
+    """
+    # Import here to avoid circular dependency
+    from ml4t.diagnostic.core.numba_utils import calculate_drawdown_numba
+
+    # Convert to numpy array
+    ret_array = DataFrameAdapter.to_numpy(returns).flatten()
+
+    # Remove NaN values
+    ret_clean = ret_array[~np.isnan(ret_array)]
+
+    if len(ret_clean) == 0:
+        return {
+            "max_drawdown": np.nan,
+            "max_drawdown_duration": np.nan,
+            "peak_date": np.nan,
+            "trough_date": np.nan,
+        }
+
+    # Calculate cumulative returns if needed
+    if cumulative:
+        cum_returns = ret_clean
+    else:
+        cum_returns = np.cumprod(1 + ret_clean) - 1  # Compound returns
+
+    # Use Numba-optimized function
+    max_drawdown_val, dd_duration, peak_idx, trough_idx = calculate_drawdown_numba(cum_returns)
+
+    # Handle case where no drawdown was found
+    if peak_idx == -1:
+        return {
+            "max_drawdown": 0.0,
+            "max_drawdown_duration": 0,
+            "peak_date": 0,
+            "trough_date": 0,
+        }
+
+    return {
+        "max_drawdown": float(max_drawdown_val),
+        "max_drawdown_duration": int(dd_duration),
+        "peak_date": int(peak_idx),
+        "trough_date": int(trough_idx),
+    }
+
+
+def sortino_ratio(
+    returns: Union[pl.Series, pd.Series, "NDArray[Any]"],
+    target_return: float = 0.0,
+    annualization_factor: float | None = None,
+) -> float:
+    """Calculate Sortino Ratio focusing on downside risk.
+
+    The Sortino Ratio is similar to Sharpe ratio but only penalizes downside
+    volatility, making it more appropriate for asymmetric return distributions.
+
+    Parameters
+    ----------
+    returns : Union[pl.Series, pd.Series, np.ndarray]
+        Time series of returns
+    target_return : float, default 0.0
+        Target return threshold (same frequency as returns)
+    annualization_factor : Optional[float], default None
+        Factor to annualize the ratio
+
+    Returns
+    -------
+    float
+        Sortino ratio value
+
+    Examples
+    --------
+    >>> returns = np.array([0.01, 0.02, -0.01, 0.03, -0.02])
+    >>> sortino = sortino_ratio(returns, annualization_factor=252)
+    >>> print(f"Sortino Ratio: {sortino:.3f}")
+    Sortino Ratio: 0.894
+    """
+    # Convert to numpy array
+    ret_array = DataFrameAdapter.to_numpy(returns).flatten()
+
+    # Remove NaN values
+    ret_clean = ret_array[~np.isnan(ret_array)]
+
+    if len(ret_clean) < 2:
+        return np.nan
+
+    # Calculate excess returns relative to target
+    excess_returns = ret_clean - target_return
+
+    # Calculate downside returns (only negative excess returns)
+    downside_returns = excess_returns[excess_returns < 0]
+
+    if len(downside_returns) == 0:
+        # No downside - infinite Sortino ratio if mean is positive
+        mean_excess = np.mean(excess_returns)
+        if mean_excess > 0:
+            return np.inf
+        if mean_excess < 0:
+            return -np.inf
+        return np.nan
+
+    # Calculate Sortino ratio
+    mean_excess = np.mean(excess_returns)
+    downside_std = np.sqrt(np.mean(downside_returns**2))  # Downside deviation
+
+    if downside_std == 0:
+        return np.nan
+
+    sortino = mean_excess / downside_std
+
+    # Apply annualization if specified
+    if annualization_factor is not None:
+        sortino *= np.sqrt(annualization_factor)
+
+    return float(sortino)