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.

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:

Metrics

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.