boruta-quant 0.1.0

Temporal-aware Boruta feature selection for quantitative finance. OOS-only importance with purged cross-validation.

boruta-quant

Temporal-aware Boruta feature selection for quantitative finance.

boruta-quant computes feature importance on validation data only, using purged cross-validation to prevent lookahead bias. Built for financial time series where temporal integrity matters.

Why boruta-quant?

Standard feature selection (SHAP, sklearn permutation importance) computes importance on training data. In financial time series, this leaks future information into feature rankings. boruta-quant fixes this:

• OOS-Only Importance: Importance computed exclusively on validation folds
• Purged Cross-Validation: Train/test gap with purge and embargo windows
• Shadow Features: Boruta's all-relevant selection via shadow comparison

Installation

# Basic (permutation importance only)
pip install boruta-quant

# With LightGBM
pip install boruta-quant[lightgbm]

# With SHAP support
pip install boruta-quant[shap]

# Everything
pip install boruta-quant[all]

Development

git clone https://github.com/BlackArbsCEO/boruta-quant.git
cd boruta-quant
uv sync --all-extras --dev

Quick Start

from boruta_quant import BorutaSelector, BorutaSelectorConfig
from boruta_quant.oracle import PermutationImportanceOracle
from boruta_quant.temporal import PurgedTemporalCV, PurgedCVConfig
from boruta_quant.metrics import rank_ic_scorer
from lightgbm import LGBMRegressor

# 1. Configure purged temporal CV
cv = PurgedTemporalCV(PurgedCVConfig(
    n_splits=5,
    purge_window_days=5,      # gap before validation fold
    embargo_window_days=5,    # gap after validation fold
    min_train_size=100,
    test_size_ratio=0.2,
))

# 2. Configure importance oracle (OOS-only)
oracle = PermutationImportanceOracle(
    scoring=rank_ic_scorer,   # Spearman rank correlation
    n_repeats=10,
    random_state=42,
)

# 3. Configure Boruta selector
selector = BorutaSelector(
    config=BorutaSelectorConfig(
        n_trials=20,          # Boruta iterations
        percentile=100,       # shadow threshold percentile
        alpha=0.05,           # significance level
        two_step=True,        # resolve tentative features
        random_state=42,
    ),
    oracle=oracle,
    cv=cv,
)

# 4. Fit — model goes here, not in the constructor
result = selector.fit(
    X, y,
    timestamps=timestamps,   # must be timezone-aware
    model=LGBMRegressor(n_estimators=100, random_state=42),
)

# 5. Results
print(result.accepted_features)    # confirmed important
print(result.rejected_features)    # confirmed unimportant
print(result.tentative_features)   # borderline (resolved if two_step=True)

Importance Oracles

All oracles fit the model on training data but measure importance on validation data only.

Oracle	How it works	When to use
PermutationImportanceOracle	Shuffles one feature in validation set, measures prediction drop	Default — reliable, no refit needed
DropColumnImportanceOracle	Removes feature, refits model, measures prediction drop	When refit cost is acceptable
BlockPermutationImportanceOracle	Block-shuffles feature (preserves autocorrelation structure)	Autocorrelated time series

Temporal Cross-Validation

     Training         Purge   Validation   Embargo
  |--------------| |-------| |----------| |-------|
  ^                                                ^
  train_start                               embargo_end

- Purge: removes observations that could leak into validation
- Embargo: prevents information from validation bleeding forward

Shadow Shuffle Modes

Shadow features are shuffled copies of real features. The shuffle mode controls how temporal structure is handled:

Mode	Description	Use case
ShuffleMode.RANDOM	Standard i.i.d. permutation	Default — i.i.d. data
ShuffleMode.BLOCK	Block-preserving shuffle	Autocorrelated features
ShuffleMode.ERA	Shuffle within eras only	Regime-aware selection

Metrics

Function	Description
rank_ic	Spearman correlation between predictions and actuals
rank_ic_scorer	sklearn-compatible scorer wrapping rank_ic
directional_accuracy	Fraction of correct sign predictions (up vs down)
directional_accuracy_scorer	sklearn-compatible scorer wrapping directional_accuracy
auc_score	Area under ROC curve
auc_scorer	sklearn-compatible scorer wrapping auc_score

Design Principles

1. OOS-Only: Importance never computed on training data
2. Fail-Fast: Invalid temporal data (naive timestamps, unsorted) raises immediately
3. Type-Safe: Runtime enforcement with beartype, strict Pyright
4. Explicit: All config parameters required — no hidden defaults

References

• Boruta Algorithm — Kursa & Rudnicki (2010)
• Advances in Financial Machine Learning — Lopez de Prado (2018), Ch. 7 (purged CV)

License

MIT — see LICENSE.