ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/config/validation.py

@@ -0,0 +1,279 @@
+"""Custom validators and validation utilities.
+
+This module provides reusable validators, custom types, and validation
+helpers used across the configuration system.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated
+
+from pydantic import Field
+
+# Custom type aliases for common constraints
+PositiveInt = Annotated[int, Field(gt=0)]
+NonNegativeInt = Annotated[int, Field(ge=0)]
+PositiveFloat = Annotated[float, Field(gt=0.0)]
+NonNegativeFloat = Annotated[float, Field(ge=0.0)]
+Probability = Annotated[float, Field(ge=0.0, le=1.0)]
+CorrelationValue = Annotated[float, Field(ge=-1.0, le=1.0)]
+
+
+class SignificanceLevel(float, Enum):
+    """Standard significance levels for hypothesis testing."""
+
+    LEVEL_01 = 0.01
+    LEVEL_05 = 0.05
+    LEVEL_10 = 0.10
+
+
+class CorrelationMethod(str, Enum):
+    """Correlation calculation methods."""
+
+    PEARSON = "pearson"
+    SPEARMAN = "spearman"
+    KENDALL = "kendall"
+
+
+class StationarityTest(str, Enum):
+    """Stationarity test types."""
+
+    ADF = "adf"  # Augmented Dickey-Fuller
+    KPSS = "kpss"  # Kwiatkowski-Phillips-Schmidt-Shin
+    PP = "pp"  # Phillips-Perron
+
+
+class RegressionType(str, Enum):
+    """Regression types for stationarity tests."""
+
+    CONSTANT = "c"  # Constant only
+    CONSTANT_TREND = "ct"  # Constant and trend
+    CONSTANT_TREND_SQUARED = "ctt"  # Constant, trend, and trend squared
+    NONE = "n"  # No constant or trend
+
+
+class ClusteringMethod(str, Enum):
+    """Clustering algorithm types."""
+
+    HIERARCHICAL = "hierarchical"
+    KMEANS = "kmeans"
+    DBSCAN = "dbscan"
+
+
+class LinkageMethod(str, Enum):
+    """Linkage methods for hierarchical clustering."""
+
+    WARD = "ward"
+    COMPLETE = "complete"
+    AVERAGE = "average"
+    SINGLE = "single"
+
+
+class DistanceMetric(str, Enum):
+    """Distance metrics for clustering."""
+
+    EUCLIDEAN = "euclidean"
+    CORRELATION = "correlation"
+    MANHATTAN = "manhattan"
+    COSINE = "cosine"
+
+
+class NormalityTest(str, Enum):
+    """Normality test types."""
+
+    JARQUE_BERA = "jarque_bera"
+    SHAPIRO = "shapiro"
+    KOLMOGOROV_SMIRNOV = "ks"
+    ANDERSON = "anderson"
+
+
+class OutlierMethod(str, Enum):
+    """Outlier detection methods."""
+
+    ZSCORE = "zscore"
+    IQR = "iqr"
+    ISOLATION_FOREST = "isolation_forest"
+
+
+class VolatilityClusterMethod(str, Enum):
+    """Methods for detecting volatility clustering."""
+
+    LJUNG_BOX = "ljung_box"
+    ENGLE_ARCH = "engle_arch"
+
+
+class ThresholdOptimizationTarget(str, Enum):
+    """Optimization targets for threshold analysis."""
+
+    SHARPE = "sharpe"
+    PRECISION = "precision"
+    RECALL = "recall"
+    F1 = "f1"
+    INFORMATION_COEFFICIENT = "ic"
+
+
+class DriftDetectionMethod(str, Enum):
+    """Feature drift detection methods."""
+
+    KOLMOGOROV_SMIRNOV = "ks"
+    WASSERSTEIN = "wasserstein"
+    PSI = "psi"  # Population Stability Index
+
+
+class PortfolioMetric(str, Enum):
+    """Portfolio performance metrics."""
+
+    SHARPE = "sharpe"
+    SORTINO = "sortino"
+    CALMAR = "calmar"
+    MAX_DRAWDOWN = "max_dd"
+    VAR = "var"  # Value at Risk
+    CVAR = "cvar"  # Conditional Value at Risk
+    OMEGA = "omega"
+
+
+class TimeFrequency(str, Enum):
+    """Time aggregation frequencies."""
+
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+    QUARTERLY = "quarterly"
+    ANNUAL = "annual"
+
+
+class FDRMethod(str, Enum):
+    """False Discovery Rate control methods."""
+
+    BONFERRONI = "bonferroni"
+    HOLM = "holm"
+    BENJAMINI_HOCHBERG = "bh"
+    BENJAMINI_YEKUTIELI = "by"
+
+
+class BayesianPriorDistribution(str, Enum):
+    """Prior distributions for Bayesian analysis."""
+
+    NORMAL = "normal"
+    STUDENT_T = "student_t"
+    UNIFORM = "uniform"
+
+
+class ReportFormat(str, Enum):
+    """Report output formats."""
+
+    HTML = "html"
+    JSON = "json"
+    PDF = "pdf"
+
+
+class ReportTemplate(str, Enum):
+    """Report templates."""
+
+    FULL = "full"
+    SUMMARY = "summary"
+    DIAGNOSTIC = "diagnostic"
+
+
+class ReportTheme(str, Enum):
+    """Report visual themes."""
+
+    LIGHT = "light"
+    DARK = "dark"
+    PROFESSIONAL = "professional"
+
+
+class TableFormat(str, Enum):
+    """Table formatting styles."""
+
+    STYLED = "styled"
+    PLAIN = "plain"
+    DATATABLES = "datatables"
+
+
+class DataFrameExportFormat(str, Enum):
+    """DataFrame serialization formats for JSON."""
+
+    RECORDS = "records"  # list of dicts
+    SPLIT = "split"  # {index: [...], columns: [...], data: [...]}
+    INDEX = "index"  # {index: {column: value}}
+
+
+def validate_positive_int(v: int, field_name: str = "value") -> int:
+    """Validate that an integer is positive.
+
+    Args:
+        v: Value to validate
+        field_name: Name of field for error messages
+
+    Returns:
+        Validated value
+
+    Raises:
+        ValueError: If value is not positive
+    """
+    if v <= 0:
+        raise ValueError(f"{field_name} must be positive (got {v})")
+    return v
+
+
+def validate_probability(v: float, field_name: str = "probability") -> float:
+    """Validate that a float is in [0, 1].
+
+    Args:
+        v: Value to validate
+        field_name: Name of field for error messages
+
+    Returns:
+        Validated value
+
+    Raises:
+        ValueError: If value is not in [0, 1]
+    """
+    if not 0.0 <= v <= 1.0:
+        raise ValueError(f"{field_name} must be in [0, 1] (got {v})")
+    return v
+
+
+def validate_significance_level(v: float) -> float:
+    """Validate significance level is a standard value.
+
+    Args:
+        v: Significance level
+
+    Returns:
+        Validated significance level
+
+    Raises:
+        ValueError: If not a standard significance level
+    """
+    standard_levels = {0.01, 0.05, 0.10}
+    if v not in standard_levels:
+        raise ValueError(
+            f"Significance level {v} is non-standard. Consider using 0.01, 0.05, or 0.10 for interpretability."
+        )
+    return v
+
+
+def validate_min_max_range(
+    min_val: float, max_val: float, field_prefix: str = "range"
+) -> tuple[float, float]:
+    """Validate that min < max.
+
+    Args:
+        min_val: Minimum value
+        max_val: Maximum value
+        field_prefix: Prefix for error messages
+
+    Returns:
+        Validated (min, max) tuple
+
+    Raises:
+        ValueError: If min >= max
+    """
+    if min_val >= max_val:
+        raise ValueError(
+            f"{field_prefix}_min must be < {field_prefix}_max (got {min_val} >= {max_val})"
+        )
+    return min_val, max_val

ml4t/diagnostic/core/__init__.py

@@ -0,0 +1,29 @@
+"""Core functionality for ml4t-diagnostic.
+
+This module contains the fundamental logic for purging, embargo, and sampling
+that underlies all cross-validation splitters.
+"""
+
+from ml4t.diagnostic.core.purging import (
+    apply_purging_and_embargo,
+    calculate_embargo_indices,
+    calculate_purge_indices,
+)
+from ml4t.diagnostic.core.sampling import (
+    balanced_subsample,
+    block_bootstrap,
+    event_based_sample,
+    sample_weights_by_importance,
+    stratified_sample_time_series,
+)
+
+__all__: list[str] = [
+    "apply_purging_and_embargo",
+    "balanced_subsample",
+    "calculate_embargo_indices",
+    "calculate_purge_indices",
+    "event_based_sample",
+    "sample_weights_by_importance",
+    "block_bootstrap",
+    "stratified_sample_time_series",
+]

ml4t/diagnostic/core/numba_utils.py

@@ -0,0 +1,315 @@
+"""Numba-optimized utility functions for ML4T Diagnostic.
+
+This module contains JIT-compiled functions for performance-critical operations.
+Numba is used to optimize computationally intensive loops and array operations.
+
+Note: Numba functions work best with NumPy arrays and simple Python types.
+They cannot handle Pandas objects directly.
+"""
+
+import numpy as np
+from numba import jit
+
+
+@jit(nopython=True, cache=True)
+def calculate_drawdown_numba(
+    cum_returns: np.ndarray,
+) -> tuple[float, int, int, int]:
+    """Numba-optimized maximum drawdown calculation.
+
+    Parameters
+    ----------
+    cum_returns : np.ndarray
+        Array of cumulative returns
+
+    Returns
+    -------
+    Tuple[float, int, int, int]
+        (max_drawdown, duration, peak_idx, trough_idx)
+    """
+    n = len(cum_returns)
+    if n == 0:
+        return np.nan, -1, -1, -1
+
+    max_drawdown = 0.0
+    max_duration = 0
+    peak_idx = 0
+    trough_idx = 0
+    current_peak = cum_returns[0]
+    current_peak_idx = 0
+
+    for i in range(1, n):
+        # Update peak if necessary
+        if cum_returns[i] > current_peak:
+            current_peak = cum_returns[i]
+            current_peak_idx = i
+
+        # Calculate current drawdown
+        drawdown = cum_returns[i] - current_peak
+
+        # Update max drawdown if necessary
+        if drawdown < max_drawdown:
+            max_drawdown = drawdown
+            peak_idx = current_peak_idx
+            trough_idx = i
+            max_duration = i - current_peak_idx
+
+    return max_drawdown, max_duration, peak_idx, trough_idx
+
+
+@jit(nopython=True, cache=True)
+def purge_indices_numba(
+    test_start: int,
+    _test_end: int,
+    label_horizon: int,
+    n_samples: int,
+) -> np.ndarray:
+    """Numba-optimized calculation of purge indices.
+
+    Parameters
+    ----------
+    test_start : int
+        Start index of test period
+    test_end : int
+        End index of test period
+    label_horizon : int
+        Forward-looking period of labels
+    n_samples : int
+        Total number of samples
+
+    Returns
+    -------
+    np.ndarray
+        Array of indices to purge
+    """
+    purge_start = max(0, test_start - label_horizon)
+    purge_end = min(test_start, n_samples)
+
+    if purge_start >= purge_end:
+        return np.empty(0, dtype=np.int64)
+
+    return np.arange(purge_start, purge_end, dtype=np.int64)
+
+
+@jit(nopython=True, cache=True)
+def embargo_indices_numba(
+    test_end: int,
+    embargo_size: int,
+    n_samples: int,
+) -> np.ndarray:
+    """Numba-optimized calculation of embargo indices.
+
+    Parameters
+    ----------
+    test_end : int
+        End index of test period
+    embargo_size : int
+        Number of samples to embargo after test set
+    n_samples : int
+        Total number of samples
+
+    Returns
+    -------
+    np.ndarray
+        Array of indices to embargo
+    """
+    embargo_start = test_end
+    embargo_end = min(test_end + embargo_size, n_samples)
+
+    if embargo_start >= embargo_end:
+        return np.empty(0, dtype=np.int64)
+
+    return np.arange(embargo_start, embargo_end, dtype=np.int64)
+
+
+@jit(nopython=True, cache=True, parallel=True)
+def block_bootstrap_numba(
+    indices: np.ndarray,
+    n_samples: int,
+    sample_length: int,
+    seed: int,
+) -> np.ndarray:
+    """Numba-optimized block bootstrap sampling.
+
+    Parameters
+    ----------
+    indices : np.ndarray
+        Array of indices to sample from
+    n_samples : int
+        Number of bootstrap samples to generate
+    sample_length : int
+        Length of each sequential sample
+    seed : int
+        Random seed for reproducibility
+
+    Returns
+    -------
+    np.ndarray
+        Bootstrap sample indices
+    """
+    np.random.seed(seed)
+    n_indices = len(indices)
+
+    # Handle edge cases
+    if sample_length >= n_indices:
+        if n_samples <= n_indices:
+            return indices[:n_samples].copy()
+        # Repeat indices to meet n_samples requirement
+        repeats = (n_samples // n_indices) + 1
+        result = np.empty(repeats * n_indices, dtype=indices.dtype)
+        for i in range(repeats):
+            result[i * n_indices : (i + 1) * n_indices] = indices
+        return result[:n_samples]
+
+    # Pre-allocate result array
+    result = np.empty(n_samples, dtype=indices.dtype)
+    filled = 0
+
+    while filled < n_samples:
+        # Sample a random starting point
+        start_idx = np.random.randint(0, n_indices - sample_length + 1)
+
+        # Determine how many samples to take
+        samples_to_take = min(sample_length, n_samples - filled)
+
+        # Copy sequential samples
+        for i in range(samples_to_take):
+            result[filled + i] = indices[start_idx + i]
+
+        filled += samples_to_take
+
+    return result
+
+
+@jit(nopython=True, cache=True)
+def rolling_sharpe_numba(
+    returns: np.ndarray,
+    window: int,
+    risk_free_rate: float = 0.0,
+    periods_per_year: int = 252,
+) -> np.ndarray:
+    """Numba-optimized rolling Sharpe ratio calculation.
+
+    Parameters
+    ----------
+    returns : np.ndarray
+        Array of returns
+    window : int
+        Rolling window size
+    risk_free_rate : float
+        Risk-free rate (annualized)
+    periods_per_year : int
+        Number of periods per year for annualization
+
+    Returns
+    -------
+    np.ndarray
+        Array of rolling Sharpe ratios
+    """
+    n = len(returns)
+    if n < window:
+        return np.full(n, np.nan)
+
+    result = np.full(n, np.nan)
+    daily_rf = risk_free_rate / periods_per_year
+    sqrt_periods = np.sqrt(periods_per_year)
+
+    for i in range(window - 1, n):
+        window_returns = returns[i - window + 1 : i + 1]
+        excess_returns = window_returns - daily_rf
+
+        mean_excess = np.mean(excess_returns)
+        std_excess = np.std(excess_returns)
+
+        if std_excess > 0:
+            result[i] = mean_excess / std_excess * sqrt_periods
+        else:
+            # If std is zero, check if mean is also zero
+            if abs(mean_excess) < 1e-10:
+                result[i] = 0.0
+            else:
+                result[i] = np.nan
+
+    return result
+
+
+@jit(nopython=True, cache=True, parallel=True)
+def calculate_ic_vectorized(
+    predictions: np.ndarray,
+    returns: np.ndarray,
+    method: int = 0,  # 0=pearson, 1=spearman
+) -> float:
+    """Numba-optimized Information Coefficient calculation.
+
+    Parameters
+    ----------
+    predictions : np.ndarray
+        Array of predictions
+    returns : np.ndarray
+        Array of returns
+    method : int
+        0 for Pearson, 1 for Spearman
+
+    Returns
+    -------
+    float
+        Information coefficient
+    """
+    n = len(predictions)
+    if n != len(returns) or n < 2:
+        return np.nan
+
+    # Remove NaN values
+    valid_mask = ~(np.isnan(predictions) | np.isnan(returns))
+    pred_clean = predictions[valid_mask]
+    ret_clean = returns[valid_mask]
+
+    if len(pred_clean) < 2:
+        return np.nan
+
+    if method == 1:  # Spearman
+        # Rank the data
+        pred_clean = _rank_data_numba(pred_clean)
+        ret_clean = _rank_data_numba(ret_clean)
+
+    # Calculate Pearson correlation
+    pred_mean = np.mean(pred_clean)
+    ret_mean = np.mean(ret_clean)
+
+    numerator = np.sum((pred_clean - pred_mean) * (ret_clean - ret_mean))
+    denominator = np.sqrt(
+        np.sum((pred_clean - pred_mean) ** 2) * np.sum((ret_clean - ret_mean) ** 2)
+    )
+
+    if denominator == 0:
+        return 0.0
+
+    return numerator / denominator
+
+
+@jit(nopython=True, cache=True)
+def _rank_data_numba(data: np.ndarray) -> np.ndarray:
+    """Helper function to rank data for Spearman correlation."""
+    n = len(data)
+    indices = np.argsort(data)
+    ranks = np.empty(n)
+
+    for i in range(n):
+        ranks[indices[i]] = i + 1
+
+    # Handle ties by averaging ranks
+    sorted_data = data[indices]
+    i = 0
+    while i < n:
+        j = i
+        # Find all equal values
+        while j < n - 1 and sorted_data[j] == sorted_data[j + 1]:
+            j += 1
+        # Average ranks for ties
+        if i != j:
+            avg_rank = (ranks[indices[i]] + ranks[indices[j]]) / 2
+            for k in range(i, j + 1):
+                ranks[indices[k]] = avg_rank
+        i = j + 1
+
+    return ranks