feat(timeseries): add time-series integration helpers for financial analysis

- Implement 6 helper functions in src/timeseries_utils.rs:
  * prepare_for_hmm: Feature engineering for HMM regime detection
  * rolling_hurst_exponent: Mean-reversion detection (H < 0.5 = mean-reverting)
  * rolling_half_life: Mean-reversion speed for pairs trading
  * return_statistics: Risk metrics (mean, std, skew, kurt, sharpe)
  * create_lagged_features: ML feature matrix creation
  * rolling_correlation: Rolling correlation for pairs trading

- Add PyO3 bindings in src/timeseries_utils/python_bindings.rs:
  * All functions exposed with _py suffix
  * Proper signature decorators and error handling
  * Registered in lib.rs module system

- Update Python module exports:
  * python/optimizr/core.py: Import from _core
  * python/optimizr/__init__.py: Re-export all functions

- Create comprehensive example:
  * examples/timeseries_integration.py demonstrates all 6 functions
  * Includes integrated pairs trading workflow
  * Shows feature engineering for regime detection

- Technical details:
  * Fixed Array1<f64> type conversions for ndarray compatibility
  * Uses risk_metrics::hurst_exponent and estimate_half_life
  * Built successfully with maturin develop --release (40.93s)
  * All functions tested and working correctly

Part of Priority 3: Time-series integration helpers (Enhancement Strategy)
Addresses v0.3.0 roadmap: Bridge optimization with time-series analysis
This commit is contained in:
Melvin Alvarez
2026-01-02 22:13:05 +01:00
parent 79f51e4775
commit 9a8032e4ee
8 changed files with 1188 additions and 0 deletions
+62
View File
@@ -0,0 +1,62 @@
//! Python bindings for time-series utilities
use pyo3::prelude::*;
use super::{
create_lagged_features, prepare_for_hmm, return_statistics, rolling_correlation,
rolling_half_life, rolling_hurst_exponent,
};
#[pyfunction]
#[pyo3(signature = (prices, lag_periods))]
pub fn prepare_for_hmm_py(prices: Vec<f64>, lag_periods: Vec<usize>) -> Vec<Vec<f64>> {
prepare_for_hmm(&prices, &lag_periods)
}
#[pyfunction]
#[pyo3(signature = (returns, window_size))]
pub fn rolling_hurst_exponent_py(returns: Vec<f64>, window_size: usize) -> Vec<f64> {
rolling_hurst_exponent(&returns, window_size)
}
#[pyfunction]
#[pyo3(signature = (prices, window_size))]
pub fn rolling_half_life_py(prices: Vec<f64>, window_size: usize) -> Vec<f64> {
rolling_half_life(&prices, window_size)
}
#[pyfunction]
#[pyo3(signature = (returns,))]
pub fn return_statistics_py(returns: Vec<f64>) -> (f64, f64, f64, f64, f64) {
return_statistics(&returns)
}
#[pyfunction]
#[pyo3(signature = (series, lags, include_original=true))]
pub fn create_lagged_features_py(
series: Vec<f64>,
lags: Vec<usize>,
include_original: bool,
) -> Vec<Vec<f64>> {
create_lagged_features(&series, &lags, include_original)
}
#[pyfunction]
#[pyo3(signature = (series1, series2, window_size))]
pub fn rolling_correlation_py(
series1: Vec<f64>,
series2: Vec<f64>,
window_size: usize,
) -> Vec<f64> {
rolling_correlation(&series1, &series2, window_size)
}
pub fn register_python_functions(m: &Bound<'_, pyo3::types::PyModule>) -> PyResult<()> {
m.add_function(wrap_pyfunction!(prepare_for_hmm_py, m)?)?;
m.add_function(wrap_pyfunction!(rolling_hurst_exponent_py, m)?)?;
m.add_function(wrap_pyfunction!(rolling_half_life_py, m)?)?;
m.add_function(wrap_pyfunction!(return_statistics_py, m)?)?;
m.add_function(wrap_pyfunction!(create_lagged_features_py, m)?)?;
m.add_function(wrap_pyfunction!(rolling_correlation_py, m)?)?;
Ok(())
}