boruta-quant 0.1.0__py3-none-any.whl

boruta_quant/__init__.py

@@ -0,0 +1,29 @@
+"""
+boruta-quant: Temporal-aware Boruta feature selection for quantitative finance.
+
+OOS-only importance computation with purged cross-validation,
+for financial time series where temporal integrity is critical.
+
+Example:
+    >>> from boruta_quant import BorutaSelector, BorutaSelectorConfig
+    >>> from boruta_quant.oracle import PermutationImportanceOracle
+    >>> from boruta_quant.temporal import PurgedTemporalCV, PurgedCVConfig
+    >>>
+    >>> selector = BorutaSelector(
+    ...     config=BorutaSelectorConfig(n_trials=20, percentile=100, alpha=0.05, two_step=True, random_state=42),
+    ...     oracle=PermutationImportanceOracle(scoring="neg_mean_squared_error"),
+    ...     cv=PurgedTemporalCV(PurgedCVConfig(n_splits=5, purge_window_days=5, embargo_window_days=5, min_train_size=100, test_size_ratio=0.2)),
+    ... )
+    >>> result = selector.fit(X, y, timestamps, model)
+    >>> print(result.accepted_features)
+"""
+
+from boruta_quant._version import __version__
+from boruta_quant.selector import BorutaResult, BorutaSelector, BorutaSelectorConfig
+
+__all__ = [
+    "__version__",
+    "BorutaSelector",
+    "BorutaSelectorConfig",
+    "BorutaResult",
+]

boruta_quant/_version.py

@@ -0,0 +1,3 @@
+"""Version information for boruta-quant."""
+
+__version__ = "0.1.0"

boruta_quant/metrics/__init__.py

@@ -0,0 +1,31 @@
+"""
+Scoring metrics for boruta-quant.
+
+Available Metrics:
+- rank_ic / rank_ic_scorer: Spearman correlation (rank information coefficient).
+- directional_accuracy / directional_accuracy_scorer: Fraction of correct sign predictions.
+- auc_score / auc_scorer: Area under ROC curve.
+
+Example:
+    >>> from boruta_quant.metrics import rank_ic_scorer, directional_accuracy_scorer
+    >>> from boruta_quant.oracle import PermutationImportanceOracle
+    >>>
+    >>> oracle = PermutationImportanceOracle(scoring=rank_ic_scorer)
+"""
+
+from boruta_quant.metrics.auc import auc_score, auc_scorer, auc_scorer_sklearn
+from boruta_quant.metrics.directional_accuracy import (
+    directional_accuracy,
+    directional_accuracy_scorer,
+)
+from boruta_quant.metrics.rank_ic import rank_ic, rank_ic_scorer
+
+__all__ = [
+    "rank_ic",
+    "rank_ic_scorer",
+    "directional_accuracy",
+    "directional_accuracy_scorer",
+    "auc_score",
+    "auc_scorer",
+    "auc_scorer_sklearn",
+]

boruta_quant/metrics/auc.py

@@ -0,0 +1,83 @@
+"""
+AUC-ROC scorer for classification-based feature selection.
+
+Use cases:
+- Direction prediction (up/down)
+- Regime classification
+- Binary signal classification
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from beartype import beartype
+from sklearn.metrics import make_scorer, roc_auc_score
+
+
+@beartype
+def auc_score(
+    y_true: npt.NDArray[Any],
+    y_pred_proba: npt.NDArray[Any],
+) -> float:
+    """
+    Compute AUC-ROC score for binary classification.
+
+    Args:
+        y_true: True binary labels (0 or 1)
+        y_pred_proba: Predicted probabilities for positive class
+
+    Returns:
+        AUC-ROC score in [0, 1]. 0.5 = random, 1.0 = perfect.
+
+    Raises:
+        AssertionError: If inputs have wrong shape or values.
+    """
+    assert len(y_true) == len(y_pred_proba), "Length mismatch"
+    assert len(y_true) >= 2, "Need at least 2 samples"
+
+    # Handle edge case: single class in y_true
+    unique_classes = np.unique(y_true)
+    if len(unique_classes) == 1:
+        return 0.5  # Undefined AUC, return random baseline
+
+    return float(roc_auc_score(y_true, y_pred_proba))
+
+
+@beartype
+def auc_scorer(
+    estimator: Any,
+    X: npt.NDArray[Any],
+    y_true: npt.NDArray[Any],
+) -> float:
+    """
+    sklearn-compatible AUC scorer for use with permutation_importance.
+
+    Args:
+        estimator: Fitted classifier with predict_proba method
+        X: Feature matrix
+        y_true: True binary labels
+
+    Returns:
+        AUC-ROC score
+    """
+    assert hasattr(estimator, "predict_proba"), "Estimator must have predict_proba"
+
+    y_pred_proba = estimator.predict_proba(X)[:, 1]
+    return auc_score(y_true, y_pred_proba)
+
+
+# sklearn make_scorer compatible version
+auc_scorer_sklearn = make_scorer(roc_auc_score, needs_proba=True, response_method="predict_proba")
+"""
+sklearn-compatible scorer for AUC-ROC.
+
+Usage with PermutationImportanceOracle:
+    >>> oracle = PermutationImportanceOracle(scoring=auc_scorer_sklearn)
+
+Usage with sklearn cross_val_score:
+    >>> from sklearn.model_selection import cross_val_score
+    >>> scores = cross_val_score(model, X, y, cv=cv, scoring=auc_scorer_sklearn)
+"""

boruta_quant/metrics/directional_accuracy.py

@@ -0,0 +1,67 @@
+"""
+Directional Accuracy scoring metric.
+
+Measures what fraction of predictions got the sign right (up vs down).
+The most intuitive alpha signal metric — "did you predict the right direction?"
+
+Why Directional Accuracy?
+- Every PM understands it immediately
+- Works with continuous return predictions
+- Complementary to Rank IC (IC measures rank order, DA measures sign)
+- Baseline is 50% (random guessing)
+"""
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from beartype import beartype
+from sklearn.metrics import make_scorer
+
+
+@beartype
+def directional_accuracy(
+    y_true: npt.NDArray[Any],
+    y_pred: npt.NDArray[Any],
+) -> float:
+    """
+    Compute directional accuracy (fraction of correct sign predictions).
+
+    Args:
+        y_true: Actual values (e.g., forward returns).
+        y_pred: Predicted values (e.g., alpha signal).
+
+    Returns:
+        Fraction of correct sign predictions in [0.0, 1.0].
+        0.5 = random, 1.0 = perfect direction.
+
+    Raises:
+        AssertionError: If inputs are empty or mismatched length.
+
+    Example:
+        >>> y_true = np.array([0.01, -0.02, 0.03, -0.01, 0.02])
+        >>> y_pred = np.array([0.5, -0.3, 0.8, 0.2, 0.4])
+        >>> da = directional_accuracy(y_true, y_pred)
+        >>> print(f"DA: {da:.2%}")  # 80.00% (4/5 correct)
+    """
+    assert len(y_true) == len(y_pred), (
+        f"Length mismatch: y_true={len(y_true)}, y_pred={len(y_pred)}"
+    )
+    assert len(y_true) > 0, "Need at least 1 sample"
+
+    true_signs = np.sign(y_true)
+    pred_signs = np.sign(y_pred)
+
+    # Zero returns/predictions are ambiguous — count as correct only if both zero
+    correct = true_signs == pred_signs
+    return float(np.mean(correct))
+
+
+# sklearn-compatible scorer for use with permutation_importance
+directional_accuracy_scorer = make_scorer(directional_accuracy, greater_is_better=True)
+"""
+sklearn-compatible scorer for Directional Accuracy.
+
+Usage with PermutationImportanceOracle:
+    >>> oracle = PermutationImportanceOracle(scoring=directional_accuracy_scorer)
+"""

boruta_quant/metrics/rank_ic.py

@@ -0,0 +1,72 @@
+"""
+Rank Information Coefficient (IC) scoring metric.
+
+The Rank IC is the standard metric in quantitative finance for evaluating
+alpha signals. It measures the Spearman correlation between predicted
+values and actual forward returns.
+
+Why Rank IC?
+- Robust to outliers (uses ranks, not raw values)
+- Interpretable: -1 to +1 scale
+- Industry standard for alpha research
+- Works with continuous predictions
+"""
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from beartype import beartype
+from scipy.stats import spearmanr
+from sklearn.metrics import make_scorer
+
+
+@beartype
+def rank_ic(y_true: npt.NDArray[Any], y_pred: npt.NDArray[Any]) -> float:
+    """
+    Compute Rank Information Coefficient (Spearman correlation).
+
+    Args:
+        y_true: Actual values (e.g., forward returns).
+        y_pred: Predicted values (e.g., alpha signal).
+
+    Returns:
+        Spearman correlation coefficient in [-1, 1].
+        Returns 0.0 if correlation cannot be computed (e.g., constant input).
+
+    Example:
+        >>> y_true = np.array([0.01, -0.02, 0.03, -0.01, 0.02])
+        >>> y_pred = np.array([0.5, -0.3, 0.8, -0.2, 0.4])
+        >>> ic = rank_ic(y_true, y_pred)
+        >>> print(f"IC: {ic:.4f}")
+    """
+    if len(y_true) < 2:
+        return 0.0
+
+    # Handle constant arrays
+    if np.std(y_true) == 0 or np.std(y_pred) == 0:
+        return 0.0
+
+    result = spearmanr(y_true, y_pred)
+    # Use index access for type safety (result is SignificanceResult namedtuple)
+    correlation: float = float(result[0])  # type: ignore[arg-type]
+
+    # Handle NaN (can occur with insufficient variance)
+    if np.isnan(correlation):
+        return 0.0
+
+    return correlation
+
+
+# sklearn-compatible scorer for use with permutation_importance
+rank_ic_scorer = make_scorer(rank_ic, greater_is_better=True)
+"""
+sklearn-compatible scorer for Rank IC.
+
+Usage with PermutationImportanceOracle:
+    >>> oracle = PermutationImportanceOracle(scoring=rank_ic_scorer)
+
+Usage with sklearn cross_val_score:
+    >>> from sklearn.model_selection import cross_val_score
+    >>> scores = cross_val_score(model, X, y, cv=cv, scoring=rank_ic_scorer)
+"""

boruta_quant/oracle/__init__.py

@@ -0,0 +1,32 @@
+"""
+Importance oracles for boruta-quant.
+
+All oracles compute importance on VALIDATION data only (never training data).
+
+Available Oracles:
+- PermutationImportanceOracle: Default. OOS permutation importance.
+- DropColumnImportanceOracle: Ablation-based importance (refit without feature).
+- BlockPermutationImportanceOracle: Temporal-aware block permutation.
+
+Example:
+    >>> from boruta_quant.oracle import PermutationImportanceOracle
+    >>>
+    >>> oracle = PermutationImportanceOracle(
+    ...     scoring="neg_mean_squared_error",
+    ...     n_repeats=10,
+    ...     random_state=42,
+    ... )
+"""
+
+from boruta_quant.oracle.base import ImportanceOracle, validate_importance_inputs
+from boruta_quant.oracle.block_permutation import BlockPermutationImportanceOracle
+from boruta_quant.oracle.drop_column import DropColumnImportanceOracle
+from boruta_quant.oracle.permutation import PermutationImportanceOracle
+
+__all__ = [
+    "ImportanceOracle",
+    "validate_importance_inputs",
+    "PermutationImportanceOracle",
+    "DropColumnImportanceOracle",
+    "BlockPermutationImportanceOracle",
+]

boruta_quant/oracle/base.py

@@ -0,0 +1,124 @@
+"""
+Base protocol for importance oracles.
+
+All importance oracles must implement this protocol to ensure they compute
+importance on validation data only, never on training data.
+"""
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+import numpy as np
+import pandas as pd
+from beartype import beartype
+from sklearn.metrics import get_scorer
+
+# Type alias for scorer callables (DRY: used by all oracles)
+ScorerType = str | Callable[[Any, pd.DataFrame, pd.Series], float]
+ScorerCallable = Callable[[Any, pd.DataFrame, pd.Series], float]
+
+__all__ = [
+    "ImportanceOracle",
+    "validate_importance_inputs",
+    "get_scorer_callable",
+    "ScorerType",
+    "ScorerCallable",
+]
+
+
+class ImportanceOracle(Protocol):
+    """
+    Protocol for pluggable importance computation.
+
+    All implementations MUST compute importance on validation data only.
+    This is the core contract that ensures temporal integrity in feature selection.
+
+    The oracle is responsible for:
+    1. Fitting the model on training data (X_train, y_train)
+    2. Computing feature importance on validation data (X_val, y_val)
+    3. Returning importance scores for all features
+
+    CRITICAL: Importance MUST be computed on X_val, y_val only.
+    Computing importance on training data causes look-ahead bias.
+    """
+
+    @beartype
+    def compute_importance(
+        self,
+        model: Any,
+        X_train: pd.DataFrame,
+        y_train: pd.Series,
+        X_val: pd.DataFrame,
+        y_val: pd.Series,
+        feature_names: list[str],
+    ) -> dict[str, float]:
+        """
+        Compute feature importance on VALIDATION data only.
+
+        Args:
+            model: Unfitted model instance (will be cloned and fitted internally).
+            X_train: Training features (for fitting only).
+            y_train: Training target (for fitting only).
+            X_val: Validation features (importance computed HERE).
+            y_val: Validation target (importance computed HERE).
+            feature_names: List of feature names in X_train/X_val.
+
+        Returns:
+            Dict mapping feature name to importance score.
+            Higher values indicate more important features.
+
+        Raises:
+            AssertionError: If validation data is empty or has wrong shape.
+        """
+        ...
+
+
+@beartype
+def validate_importance_inputs(
+    X_train: pd.DataFrame,
+    y_train: pd.Series,
+    X_val: pd.DataFrame,
+    y_val: pd.Series,
+    feature_names: list[str],
+) -> None:
+    """
+    Validate inputs to importance computation.
+
+    This is a helper function that all oracle implementations should call
+    at the start of compute_importance().
+
+    Raises:
+        AssertionError: If any validation fails.
+    """
+    assert len(X_train) > 0, "X_train is empty"
+    assert len(X_val) > 0, "X_val is empty - cannot compute OOS importance"
+    assert len(y_train) == len(X_train), (
+        f"y_train length mismatch: {len(y_train)} vs {len(X_train)}"
+    )
+    assert len(y_val) == len(X_val), f"y_val length mismatch: {len(y_val)} vs {len(X_val)}"
+    assert list(X_train.columns) == feature_names, "X_train columns don't match feature_names"
+    assert list(X_val.columns) == feature_names, "X_val columns don't match feature_names"
+    assert not np.any(np.isnan(X_train.values)), "X_train contains NaN values"
+    assert not np.any(np.isnan(X_val.values)), "X_val contains NaN values"
+
+
+@beartype
+def get_scorer_callable(
+    scoring: ScorerType,
+) -> ScorerCallable:
+    """
+    Convert scoring parameter to callable scorer function.
+
+    DRY: Shared by all importance oracles that need custom scoring.
+
+    Args:
+        scoring: Sklearn scorer string (e.g., "r2", "neg_mean_squared_error")
+                 or callable(estimator, X, y) -> float.
+
+    Returns:
+        Callable that takes (estimator, X, y) and returns score.
+    """
+    if callable(scoring):
+        return scoring
+    scorer = get_scorer(scoring)
+    return lambda est, X, y: scorer(est, X, y)

boruta_quant/oracle/block_permutation.py

@@ -0,0 +1,165 @@
+"""
+Block Permutation Importance Oracle - Temporal-aware permutation importance.
+
+Unlike standard permutation importance which shuffles individual rows,
+this oracle shuffles contiguous blocks to preserve within-block temporal structure.
+This is more appropriate for time-series data.
+
+CRITICAL: Importance is ALWAYS computed on validation data, NEVER on training.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from beartype import beartype
+from sklearn.base import clone
+
+from .base import ScorerType, get_scorer_callable, validate_importance_inputs
+
+
+@beartype
+class BlockPermutationImportanceOracle:
+    """
+    Block permutation importance: shuffle temporal blocks, not individual rows.
+
+    For time-series data, shuffling individual rows destroys temporal patterns
+    within blocks. Block permutation preserves within-block structure while
+    breaking cross-block dependencies.
+
+    Importance = baseline_score - mean(permuted_scores)
+    Higher values indicate more important features.
+    """
+
+    def __init__(
+        self,
+        scoring: ScorerType,
+        block_size: int,
+        n_repeats: int = 10,
+        random_state: int | None = None,
+    ) -> None:
+        """
+        Initialize BlockPermutationImportanceOracle.
+
+        Args:
+            scoring: Sklearn scorer string or callable(estimator, X, y) -> float.
+            block_size: Number of consecutive rows per block.
+            n_repeats: Number of permutation repeats (default: 10).
+            random_state: Seed for reproducibility (default: None).
+
+        Raises:
+            AssertionError: If scoring is None, block_size <= 0, or n_repeats <= 0.
+        """
+        assert scoring is not None, "scoring is required"
+        assert block_size > 0, f"block_size must be > 0, got {block_size}"
+        assert n_repeats > 0, f"n_repeats must be > 0, got {n_repeats}"
+
+        self.scoring = scoring
+        self.block_size = block_size
+        self.n_repeats = n_repeats
+        self.random_state = random_state
+
+    def compute_importance(
+        self,
+        model: Any,
+        X_train: pd.DataFrame,
+        y_train: pd.Series,
+        X_val: pd.DataFrame,
+        y_val: pd.Series,
+        feature_names: list[str],
+    ) -> dict[str, float]:
+        """
+        Compute block permutation importance on VALIDATION data only.
+
+        For each feature:
+        1. Divide validation data into blocks
+        2. Shuffle the order of blocks (preserving within-block order)
+        3. Score on shuffled data
+        4. Repeat n_repeats times
+        5. Importance = baseline_score - mean(permuted_scores)
+
+        Args:
+            model: Unfitted model instance (will be cloned and fitted once).
+            X_train: Training features (for fitting only).
+            y_train: Training target (for fitting only).
+            X_val: Validation features (importance computed HERE).
+            y_val: Validation target (importance computed HERE).
+            feature_names: List of feature names in X_train/X_val.
+
+        Returns:
+            Dict mapping feature name to importance score.
+        """
+        validate_importance_inputs(X_train, y_train, X_val, y_val, feature_names)
+
+        n_val = len(X_val)
+        assert self.block_size <= n_val, (
+            f"block_size ({self.block_size}) > validation set size ({n_val})"
+        )
+
+        rng = np.random.default_rng(self.random_state)
+        # DRY: Use shared scorer utility
+        scorer = get_scorer_callable(self.scoring)
+
+        # Fit model once on training data
+        fitted_model = clone(model)
+        fitted_model.fit(X_train, y_train)
+        baseline_score = scorer(fitted_model, X_val, y_val)
+
+        block_indices = self._compute_block_indices(n_val)
+        importances: dict[str, float] = {}
+
+        for feature in feature_names:
+            permuted_scores: list[float] = []
+
+            for _ in range(self.n_repeats):
+                X_permuted = X_val.copy()
+                X_permuted[feature] = self._permute_blocks(
+                    X_val[feature].values, block_indices, rng
+                )
+                score = scorer(fitted_model, X_permuted, y_val)
+                permuted_scores.append(score)
+
+            importances[feature] = baseline_score - float(np.mean(permuted_scores))
+
+        return importances
+
+    def _compute_block_indices(self, n_samples: int) -> list[tuple[int, int]]:
+        """
+        Compute block start/end indices.
+
+        Args:
+            n_samples: Total number of samples.
+
+        Returns:
+            List of (start, end) tuples for each block.
+        """
+        blocks: list[tuple[int, int]] = []
+        start = 0
+        while start < n_samples:
+            end = min(start + self.block_size, n_samples)
+            blocks.append((start, end))
+            start = end
+        return blocks
+
+    def _permute_blocks(
+        self,
+        values: np.ndarray,
+        block_indices: list[tuple[int, int]],
+        rng: np.random.Generator,
+    ) -> np.ndarray:
+        """
+        Permute values by shuffling blocks.
+
+        Args:
+            values: 1D array of feature values.
+            block_indices: List of (start, end) tuples.
+            rng: Numpy random generator.
+
+        Returns:
+            Permuted values with blocks shuffled but within-block order preserved.
+        """
+        blocks = [values[start:end].copy() for start, end in block_indices]
+        rng.shuffle(blocks)
+        return np.concatenate(blocks)