Add Multifractal Fractional Noise Generator

[Sinitca-Aleksandr]

Summary

This PR introduces a comprehensive multifractal fractional noise generator to the StatTools library, enabling the creation of signals with piecewise power-law spectral densities and multiple Hurst exponents.

Key Features

Core Implementation

• New Generator: mfnoise() function in StatTools/generators/mfnoise_generator.py
• Spectral Density Calculation: _calculate_spectral_density() for piecewise power-law spectra
• Multiple Hurst Exponents: Support for signals with different scaling behaviors in different frequency ranges
• Crossover Points: Configurable transition points between different Hurst regimes

Functionality

• Single/Multiple Tracks: Generate one or multiple independent noise tracks
• Normalization: Optional zero-mean, unit-variance normalization
• Flexible Input: Accepts both single values and tuples/lists for Hurst exponents
• Robust Error Handling: Comprehensive parameter validation

Mathematical Foundation

• Spectral Method: Uses FFT-based generation with piecewise power-law spectral density
• Hurst Relationship: Spectral exponent α = 2H + 1 for each segment
• Continuity: Ensures smooth transitions at crossover frequencies
• Fractional Noise: Outputs are differences of fractional Brownian motion

Usage Examples

Basic Usage

# Single Hurst exponent
signal = mfnoise(2**15, hurst=0.8, crossover_points=())

# Multifractal with crossover
signal = mfnoise(2**15, hurst=(0.8, 0.5), crossover_points=(200,))

# Multiple tracks
signals = mfnoise(2**15, hurst=(1.0, 0.5), crossover_points=(500,), n_tracks=3)

Visualization

The included Jupyter notebook (examples/mfnoise_visualization.ipynb) demonstrates:

• Spectral density visualization in dB scale
• Generated signal plots
• DFA analysis showing scaling behavior
• Multiple parameter configurations

Testing

Comprehensive test suite in tests/test_mfnoise_generator.py covering:

• Unit Tests: Individual function testing
• Integration Tests: End-to-end functionality
• Edge Cases: Short signals, large signals, boundary conditions
• Statistical Properties: Mean, variance, finite values
• Reproducibility: Seed-based deterministic behavior
• Error Handling: Invalid parameter validation

Files Modified

• New: StatTools/generators/mfnoise_generator.py - Core implementation
• New: tests/test_mfnoise_generator.py - Comprehensive test suite
• New: examples/mfnoise_visualization.ipynb - Visualization examples

Technical Details

• Dependencies: Only requires NumPy (already in project dependencies)
• Performance: Efficient FFT-based implementation
• Memory: Linear scaling with signal length
• Compatibility: Python 3.8+ with standard scientific computing stack

Applications

This generator is particularly useful for:

• Multifractal Analysis: Testing DFA and other scaling analysis methods
• Signal Processing: Generating realistic noise with complex scaling behavior
• Research: Simulating physical processes with multiple scaling regimes
• Education: Demonstrating multifractal concepts and spectral methods

Validation

The implementation has been validated through:

• Spectral Analysis: Confirmed power-law behavior in frequency domain
• DFA Verification: Demonstrated expected scaling exponents
• Statistical Tests: Verified finite values and reasonable magnitudes
• Reproducibility: Consistent results with fixed random seeds

This addition significantly expands the library's capabilities for generating complex noise signals with controllable multifractal properties.

[kilo-code-bot]

Code Review Summary

Status: No New Issues Found | Recommendation: Merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	0

The existing inline comments adequately address the issues in this PR:

• Unused local variable prev_mask at line 60
• Terminology note about alpha/beta parameters
• Unused import comment in test file

Files Reviewed (3 files)

• StatTools/generators/mfnoise_generator.py - New multifractal noise generator implementation
• tests/test_mfnoise_generator.py - Comprehensive test suite
• examples/mfnoise_visualization.ipynb - Visualization example (generated file)

Notes

The implementation appears sound. The code correctly handles:

• Single and multiple Hurst exponent cases
• Piecewise spectral density calculation with crossover points
• Multiple track generation
• Signal normalization
• Proper error handling for invalid parameters