Metadata-Version: 2.4
Name: lrdbenchmark
Version: 2.1.8
Summary: Comprehensive Long-Range Dependence Benchmarking Framework with Classical, ML, and Neural Network Estimators
Author-email: "Davian R. Chin" <d.r.chin@reading.ac.uk>
License: MIT
Project-URL: Homepage, https://github.com/dave2k77/LRDBenchmark
Project-URL: Documentation, https://lrdbenchmark.readthedocs.io/
Project-URL: Repository, https://github.com/dave2k77/LRDBenchmark.git
Project-URL: Issues, https://github.com/dave2k77/LRDBenchmark/issues
Project-URL: Download, https://pypi.org/project/lrdbenchmark/
Project-URL: Source, https://github.com/dave2k77/LRDBenchmark
Keywords: long-range dependence,hurst parameter,time series analysis,benchmarking,machine learning,neural networks,reproducible research,fractional brownian motion,wavelet analysis,spectral analysis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: pywavelets>=1.3.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: networkx>=2.6.0
Requires-Dist: joblib>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.12; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.9; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=0.5; extra == "docs"
Requires-Dist: myst-parser>=0.15; extra == "docs"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.28.0; extra == "dashboard"
Requires-Dist: plotly>=5.15.0; extra == "dashboard"
Provides-Extra: accel
Requires-Dist: jax>=0.3.0; extra == "accel"
Requires-Dist: jaxlib>=0.3.0; extra == "accel"
Requires-Dist: numba>=0.56.0; extra == "accel"
Provides-Extra: ml
Requires-Dist: torch>=1.9.0; extra == "ml"
Provides-Extra: bayes
Requires-Dist: optuna>=3.0.0; extra == "bayes"
Requires-Dist: numpyro>=0.12.0; extra == "bayes"
Provides-Extra: all
Requires-Dist: jax>=0.3.0; extra == "all"
Requires-Dist: jaxlib>=0.3.0; extra == "all"
Requires-Dist: numba>=0.56.0; extra == "all"
Requires-Dist: torch>=1.9.0; extra == "all"
Requires-Dist: optuna>=3.0.0; extra == "all"
Requires-Dist: numpyro>=0.12.0; extra == "all"
Dynamic: license-file

# LRDBenchmark

A comprehensive, reproducible framework for Long-Range Dependence (LRD) estimation and benchmarking across Classical, Machine Learning, and Neural Network methods.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

## 🚀 Features

**Comprehensive Estimator Suite:**
- **8 Classical Methods**: R/S, DFA, DMA, Higuchi, Periodogram, GPH, Whittle, CWT
- **3 Machine Learning Models**: Random Forest, SVR, Gradient Boosting with optimized hyperparameters  
- **4 Neural Network Architectures**: LSTM, GRU, CNN, Transformer with pre-trained models
- **Generalized Hurst Exponent (GHE)**: Advanced multifractal analysis capabilities

**🏆 Latest Performance Results:**
- **LSTM leads overall performance**: 9.68/10 (0.097 MAE) - Rank #1
- **CNN follows closely**: 9.66/10 (0.103 MAE) - Rank #2
- **R/S (Classical) excels**: 9.51/10 (0.099 MAE) - Rank #5
- **All methods achieve perfect robustness** (1.00/1.00) across contamination scenarios

**Robust Heavy-Tail Analysis:**
- α-stable distribution modeling for heavy-tailed time series
- Adaptive preprocessing: standardization, winsorization, log-winsorization, detrending
- Contamination-aware estimation with intelligent fallback mechanisms

**High-Performance Computing:**
- Intelligent optimization backend with graceful fallbacks: JAX → Numba → NumPy
- GPU acceleration support where available
- Optimized implementations for large-scale analysis

**Comprehensive Benchmarking:**
- End-to-end benchmarking scripts with statistical analysis
- Confidence intervals, significance tests, and effect size calculations
- Performance leaderboards and comparative analysis tools

## 🔧 Quick Start

### Basic Usage

```python
from lrdbenchmark.analysis.temporal.rs.rs_estimator_unified import RSEstimator
from lrdbenchmark.models.data_models.fbm.fbm_model import FractionalBrownianMotion

# Generate synthetic fractional Brownian motion
fbm = FractionalBrownianMotion(H=0.7, sigma=1.0)
x = fbm.generate(n=1000, seed=42)

# Estimate Hurst parameter using R/S analysis
estimator = RSEstimator()
result = estimator.estimate(x)
print(f"Estimated H: {result['hurst_parameter']:.3f}")  # ~0.7
```

### Advanced Benchmarking

```python
from lrdbenchmark.analysis.benchmark import ComprehensiveBenchmark

# Run comprehensive benchmark across multiple estimators
benchmark = ComprehensiveBenchmark()
results = benchmark.run_classical_estimators(
    data_models=['fbm', 'fgn', 'arfima'],
    n_samples=1000,
    n_trials=100
)
benchmark.generate_leaderboard(results)
```

### Heavy-Tail Robustness Analysis

```python
from lrdbenchmark.models.data_models.alpha_stable.alpha_stable_model import AlphaStableModel
from lrdbenchmark.robustness.adaptive_preprocessor import AdaptivePreprocessor

# Generate heavy-tailed α-stable process
alpha_stable = AlphaStableModel(alpha=1.5, beta=0.0, scale=1.0)
x = alpha_stable.generate(n=1000, seed=42)

# Apply adaptive preprocessing for robust estimation
preprocessor = AdaptivePreprocessor()
x_processed = preprocessor.preprocess(x, method='auto')

# Estimate with robust preprocessing
estimator = RSEstimator()
result = estimator.estimate(x_processed)
```

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install lrdbenchmark
```

### Development Installation

```bash
git clone https://github.com/dave2k77/LRDBenchmark.git
cd LRDBenchmark
pip install -e .
```

### Optional Dependencies

For enhanced performance and additional features:

```bash
# GPU acceleration (JAX)
pip install "lrdbenchmark[jax]"

# Documentation building
pip install "lrdbenchmark[docs]"

# Development tools
pip install "lrdbenchmark[dev]"
```

## 📚 Documentation

- **📖 Full Documentation**: [https://lrdbenchmark.readthedocs.io/](https://lrdbenchmark.readthedocs.io/)
- **🚀 Quick Start Guide**: [`docs/quickstart.rst`](docs/quickstart.rst)
- **💡 Examples**: [`docs/examples/`](docs/examples/) and [`examples/`](examples/)
- **🔧 API Reference**: [API Documentation](https://lrdbenchmark.readthedocs.io/en/latest/api/)

## 🏗️ Project Structure

```
LRDBenchmark/
├── lrdbenchmark/           # Main package
│   ├── analysis/           # Estimator implementations
│   ├── models/            # Data generation models
│   ├── analytics/         # Performance monitoring
│   └── robustness/        # Heavy-tail robustness tools
├── scripts/               # Benchmarking and analysis scripts
├── examples/              # Usage examples
├── docs/                  # Documentation
├── tests/                 # Test suite
├── tools/                 # Development utilities
└── config/                # Configuration files
```

## 🏆 Performance Leaderboard

Our comprehensive benchmark evaluated 15 estimators across 920 test cases. Here are the top performers:

| Rank | Estimator | Category | Overall Score | MAE | Robustness |
|------|-----------|----------|---------------|-----|------------|
| 1 | **LSTM** | Neural Network | **9.68/10** | **0.097** | 1.00 |
| 2 | **CNN** | Neural Network | **9.66/10** | **0.103** | 1.00 |
| 3 | **Transformer** | Neural Network | **9.65/10** | **0.106** | 1.00 |
| 4 | **GRU** | Neural Network | **9.64/10** | **0.108** | 1.00 |
| 5 | **R/S** | Classical | **9.51/10** | **0.099** | 1.00 |
| 6 | **Higuchi** | Classical | **9.41/10** | **0.118** | 1.00 |

**Category Averages:**
- **Neural Networks**: 9.66/10 (Tier 1)
- **Machine Learning**: 9.34/10 (Tier 2)  
- **Classical**: 8.65/10 (Tiers 2-4)

## 🛠️ Available Estimators

### Classical Methods
- **R/S Analysis** - Rescaled Range analysis (9.51/10)
- **DFA** - Detrended Fluctuation Analysis (7.67/10)
- **DMA** - Detrended Moving Average (7.36/10)
- **Higuchi** - Higuchi's fractal dimension method (9.41/10)
- **Periodogram** - Periodogram-based estimation (8.97/10)
- **GPH** - Geweke and Porter-Hudak estimator (8.63/10)
- **Whittle** - Whittle maximum likelihood (9.00/10)
- **CWT** - Continuous Wavelet Transform (8.65/10)
- **GHE** - Generalized Hurst Exponent

### Machine Learning
- **Random Forest** - Ensemble tree-based estimation (9.33/10)
- **Support Vector Regression** - SVM-based estimation (9.33/10)
- **Gradient Boosting** - Boosted tree estimation (9.36/10)

### Neural Networks
- **LSTM** - Long Short-Term Memory networks (9.68/10)
- **GRU** - Gated Recurrent Units (9.64/10)
- **CNN** - Convolutional Neural Networks (9.66/10)
- **Transformer** - Attention-based architectures (9.65/10)

## 🧪 Testing

Run the test suite:

```bash
# Basic tests
python -m pytest tests/

# With coverage
python -m pytest tests/ --cov=lrdbenchmark --cov-report=html
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with modern Python scientific computing stack
- Leverages JAX for high-performance computing
- Inspired by the need for reproducible LRD analysis
- Community-driven development and validation

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/dave2k77/LRDBenchmark/issues)
- **Discussions**: [GitHub Discussions](https://github.com/dave2k77/LRDBenchmark/discussions)
- **Documentation**: [ReadTheDocs](https://lrdbenchmark.readthedocs.io/)

---

**Made with ❤️ for the time series analysis community**









