Crate fractal_finance 

Financial Fractal Analysis

Enterprise-grade rigorous fractal analysis for quantitative finance applications.

This crate provides statistically rigorous tools for analyzing long-range dependence, multifractality, and regime changes in financial time series. All estimators include confidence intervals, with optional finite-sample adjustments. Statistical inference uses asymptotic theory and bootstrap methods with appropriate caveats for small samples and heavy-tailed data.

Key Features

• Statistical Rigor: All estimators include confidence intervals; optional bias-reduction heuristics are provided
• Multiple Methods: Hurst exponent estimation via R/S, DFA, GPH, and wavelet methods
• Multifractal Analysis: Complete MF-DFA implementation with singularity spectrum
• Regime Detection: HMM-based detection of structural breaks and fractal regimes
• Bootstrap Validation: Comprehensive resampling and statistical validation
• Cross-Validation: Walk-forward validation and model selection
• Monte Carlo Testing: Hypothesis testing with surrogate data methods

Quick Start

use fractal_finance::{StatisticalFractalAnalyzer, EstimationMethod};
use rand::prelude::*;
use rand_distr::StandardNormal;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut analyzer = StatisticalFractalAnalyzer::new();

    // Generate 500 realistic financial return data points
    let returns = generate_financial_returns(500);
    println!("Generated {} data points for analysis", returns.len());
    analyzer.add_time_series("ASSET".to_string(), returns);

    // Perform comprehensive analysis
    analyzer.analyze_all_series()?;

    // Get results
    let results = analyzer.get_analysis_results("ASSET")?;
    for (method, estimate) in &results.hurst_estimates {
        println!("{:?}: H = {:.3} ± {:.3}", method,
            estimate.estimate, estimate.standard_error);
    }
     
    Ok(())
}

fn generate_financial_returns(n: usize) -> Vec<f64> {
    let mut rng = thread_rng();
    let mut returns = Vec::with_capacity(n);
     
    // Parameters for realistic financial returns
    let base_volatility = 0.015f64; // 1.5% daily volatility
    let mut volatility = base_volatility;
    let mut previous_return = 0.0f64;
     
    for i in 0..n {
        // Add volatility clustering (GARCH-like effect)
        let volatility_shock = rng.gen_range(-0.005..0.005);
        volatility = (base_volatility + 0.1 * previous_return.abs() + volatility_shock).max(0.005f64);
         
        // Generate return with some persistence (memory effect)
        let white_noise: f64 = rng.sample(rand_distr::StandardNormal);
        let persistence_factor = 0.15 * previous_return; // 15% persistence
        let trend_component = 0.0001 * (i as f64 / 100.0).sin(); // Small trend component
         
        let return_val = trend_component + persistence_factor + volatility * white_noise;
         
        returns.push(return_val);
        previous_return = return_val;
    }
     
    returns
}

Analysis Methods

Hurst Exponent Estimation

• Rescaled Range (R/S): Classical method with finite-sample adjustment
• Detrended Fluctuation Analysis (DFA): Robust to non-stationarity
• GPH Periodogram: Frequency domain estimation with HAC standard errors
• Wavelet Methods: Multi-resolution analysis using dyadic scales

Advanced Analysis

• Multifractal Spectrum: Complete f(α) characterization
• Regime Detection: Hidden Markov model for structural breaks
• Statistical Testing: Comprehensive hypothesis tests for long-range dependence

Architecture

The crate is organized around the StatisticalFractalAnalyzer which orchestrates all analysis methods and provides a unified interface. Individual analysis methods can also be used directly for specialized applications.

Re-exports

pub use config::AnalysisConfig;

pub use config::AnalysisDepth;

pub use errors::FractalAnalysisError;

pub use errors::FractalResult;

pub use results::AssumptionValidation;

pub use results::DataQualityMetrics;

pub use results::FractalEstimationResults;

pub use results::HeteroskedasticityTests;

pub use results::MethodValidity;

pub use results::ModelSelectionCriteria;

pub use results::NormalityTests;

pub use results::PredictionAccuracy;

pub use results::RegimeAnalysis;

pub use results::RegimeChange;

pub use results::RegimeDurationStatistics;

pub use results::RobustnessTests;

pub use results::SensitivityAnalysis;

pub use results::SerialCorrelationTests;

pub use results::StationarityTests;

pub use results::StatisticalTestResults;

pub use results::ValidationStatistics;

pub use hurst_estimators::EstimationMethod;

pub use hurst_estimators::HurstEstimate;

pub use hurst_estimators::HurstEstimationConfig;

pub use hurst_estimators::estimate_hurst_multiple_methods;

pub use hurst_estimators::estimate_hurst_by_method;

pub use hurst_estimators::estimate_hurst_rescaled_range;

pub use hurst_estimators::estimate_hurst_dfa;

pub use hurst_estimators::estimate_hurst_periodogram;

pub use hurst_estimators::estimate_hurst_wavelet;

pub use hurst_estimators::estimate_hurst_simple_short_series;

pub use hurst_estimators::estimate_local_hurst;

pub use statistical_tests::gph_test;

pub use statistical_tests::ljung_box_test;

pub use statistical_tests::ljung_box_test_with_config;

pub use statistical_tests::portmanteau_test;

pub use statistical_tests::robinson_test;

pub use statistical_tests::test_goodness_of_fit;

pub use statistical_tests::test_long_range_dependence;

pub use statistical_tests::test_short_range_dependence;

pub use statistical_tests::test_structural_breaks;

pub use statistical_tests::GoodnessOfFitTests;

pub use statistical_tests::LongRangeDependenceTest;

pub use statistical_tests::ShortRangeDependenceTest;

pub use statistical_tests::StructuralBreakTest;

pub use statistical_tests::StructuralBreakTestType;

pub use statistical_tests::TestConfiguration;

pub use statistical_tests::TestResult;

pub use statistical_tests::PValueMethod;

pub use statistical_tests::LjungBoxDenominator;

pub use multifractal::calculate_asymmetry_parameter;

pub use multifractal::calculate_generalized_hurst_exponent;

pub use multifractal::calculate_multifractality_degree;

pub use multifractal::calculate_singularity_spectrum;

pub use multifractal::fit_quadratic_and_get_residuals;

pub use multifractal::perform_multifractal_analysis;

pub use multifractal::perform_multifractal_analysis_with_config;

pub use multifractal::perform_wtmm_analysis;

pub use multifractal::perform_wtmm_analysis_with_config;

pub use multifractal::MultifractalAnalysis;

pub use multifractal::MultifractalConfig;

pub use multifractal::MultifractalityTest;

pub use multifractal::WtmmAnalysis;

pub use multifractal::WtmmConfig;

pub use bootstrap::bootstrap_validate;

pub use bootstrap::bootstrap_validate_pairs;

pub use bootstrap::calculate_bca_confidence_interval;

pub use bootstrap::calculate_bootstrap_confidence_interval;

pub use bootstrap::calculate_normal_confidence_interval;

pub use bootstrap::generate_bootstrap_sample;

pub use bootstrap::BootstrapConfiguration;

pub use bootstrap::BootstrapMethod;

pub use bootstrap::BootstrapValidation;

pub use bootstrap::ConfidenceInterval;

pub use bootstrap::ConfidenceIntervalMethod;

pub use bootstrap::EstimatorComplexity;

pub use generators::fbm_to_fgn;

pub use generators::generate_arfima;

pub use generators::generate_benchmark_series;

pub use generators::generate_fractional_brownian_motion;

pub use generators::generate_multifractal_cascade;

pub use generators::generate_regime_switching_series;

pub use generators::ArfimaConfig;

pub use generators::BenchmarkSeriesType;

pub use generators::FbmConfig;

pub use generators::FbmMethod;

pub use generators::GeneratorConfig;

pub use generators::MultifractalCascadeConfig;

pub use monte_carlo::fourier_surrogate;

pub use monte_carlo::get_power_spectrum;

pub use monte_carlo::monte_carlo_hurst_test;

pub use monte_carlo::monte_carlo_multifractal_test;

pub use monte_carlo::power_analysis_hurst_estimator;

pub use monte_carlo::surrogate_data_test;

pub use monte_carlo::MonteCarloConfig;

pub use monte_carlo::MonteCarloTestResult;

pub use monte_carlo::NullHypothesis;

pub use monte_carlo::PowerAnalysisResult;

pub use monte_carlo::SurrogateMethod;

pub use cross_validation::cross_validate_fractal_models;

pub use cross_validation::CrossValidationConfig;

pub use cross_validation::CrossValidationMethod;

pub use cross_validation::CrossValidationResult;

pub use cross_validation::FoldResult;

pub use cross_validation::FractalEstimator;

pub use cross_validation::ModelSelectionResult;

pub use cross_validation::PerformanceMetrics;

pub use cross_validation::SelectionCriterion;

pub use regime_detection::detect_fractal_regimes;

pub use regime_detection::detect_fractal_regimes_with_hmm;

pub use regime_detection::EmissionParameters;

pub use regime_detection::FeatureExtractionMethod;

pub use regime_detection::FractalHMM;

pub use regime_detection::HMMParameters;

pub use regime_detection::HMMRegimeDetectionConfig;

pub use regime_detection::ModelCriteria;

pub use regime_detection::MultifractalRegimeParams;

pub use regime_detection::ObservationFeatures;

pub use regime_detection::RegimeChangePoint;

pub use regime_detection::RegimeDetectionConfig;

pub use regime_detection::RegimeDetectionResult;

pub use regime_detection::RegimeStatistics;

pub use regime_detection::ValidationMethod;

pub use regime_detection::VolatilityStatistics;

pub use fft_ops::calculate_periodogram_fft;

pub use fft_ops::clear_fft_cache;

pub use fft_ops::fft_autocorrelation;

pub use fft_ops::get_cached_fft_forward;

pub use fft_ops::get_cached_fft_inverse;

pub use fft_ops::get_fft_cache_stats;

pub use math_utils::calculate_autocorrelations;

pub use math_utils::calculate_segment_fluctuation;

pub use math_utils::calculate_variance;

pub use math_utils::calculate_wald_statistic;

pub use math_utils::erf;

pub use math_utils::float_ops::approx_eq;

pub use math_utils::float_ops::approx_eq_eps;

pub use math_utils::float_ops::approx_zero;

pub use math_utils::float_ops::approx_zero_eps;

pub use math_utils::float_ops::safe_div;

pub use math_utils::float_ops::safe_ln;

pub use math_utils::float_ops::safe_sqrt;

pub use math_utils::generate_window_sizes;

pub use math_utils::integrate_series;

pub use math_utils::local_whittle_estimate;

pub use math_utils::ols_regression;

pub use math_utils::standard_normal_cdf;

pub use diagnostics::analyze_circulant_eigenvalues;

pub use diagnostics::deep_gph_debug;

pub use diagnostics::diagnose_gph_variance_bias;

pub use diagnostics::run_comprehensive_diagnostics;

pub use diagnostics::test_gph_corrections;

pub use diagnostics::validate_gph_correction;

pub use analyzer::*;

Modules

analyzer

Main Statistical Fractal Analyzer

audit

Audit trail and transaction logging for financial computations.

batch_testing

Optimized batch processing for statistical tests in financial fractal analysis.

block_size

Automatic block size selection for block bootstrap methods.

bootstrap

Bootstrap validation and confidence interval methods.

bootstrap_config

Bootstrap configuration structures and validation.

bootstrap_sampling

Bootstrap sample generation methods.

collections

Deterministic collection types for reproducible financial computations.

computation_cache

Computation cache for expensive operations in fractal analysis.

confidence_intervals

Confidence interval calculation methods for bootstrap analysis.

config

Analysis Configuration

cross_validation

Time-series cross-validation for fractal model selection and validation.

decimal_finance

Production-grade financial calculations using exact decimal arithmetic

deterministic_config

Configuration management for deterministic financial computations.

diagnostics

Diagnostic and Debugging Tools

emission_models

Emission models and parameters for Hidden Markov Model regime detection.

errors

Error types and validation functions for fractal analysis.

fft_ops

High-performance FFT operations for financial fractal analysis.

generators

Synthetic fractal time series generators for testing and validation.

hmm_core

Core Hidden Markov Model implementation for regime detection.

hurst_estimators

Hurst exponent estimation methods for fractal analysis

linear_algebra

Linear algebra operations for financial fractal analysis

math_utils

Mathematical utility functions and constants for fractal analysis.

memory_pool

High-performance memory pool for financial computations.

monte_carlo

Monte Carlo hypothesis testing framework for fractal analysis.

multifractal

Multifractal analysis methods including MF-DFA and WTMM.

preprocessing

Data preprocessing utilities for financial time series analysis

regime_config

Configuration structures for regime detection.

regime_detection

Advanced regime detection using Hidden Markov Models for fractal time series.

regime_results

Result structures for regime detection.

results

Analysis Results Structures

secure_rng

Cryptographically secure random number generation for financial applications.

statistical_tests

Statistical tests for fractal time series analysis.

wavelet

Wavelet analysis methods for fractal characterization