Metadata-Version: 2.4
Name: lrdbenchmark
Version: 1.5.0
Summary: Long-Range Dependence Benchmarking Toolkit
Home-page: https://github.com/dave2k77/LRDBenchmark
Author: LRDBench Development Team
Author-email: LRDBench Development Team <lrdbench@example.com>
License: MIT
Project-URL: Homepage, https://github.com/dave2k77/LRDBenchmark
Project-URL: Documentation, https://github.com/dave2k77/LRDBenchmark/tree/main/documentation
Project-URL: Repository, https://github.com/dave2k77/LRDBenchmark.git
Project-URL: Issues, https://github.com/dave2k77/LRDBenchmark/issues
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
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: torch>=1.9.0
Requires-Dist: jax>=0.3.0
Requires-Dist: jaxlib>=0.3.0
Requires-Dist: numba>=0.56.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
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"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🚀 **LRDBench: Long-Range Dependence Benchmarking Toolkit**

A comprehensive Python package for benchmarking long-range dependence estimators on synthetic and real-world time series data. LRDBench provides ready-to-use implementations of classical, machine learning, and neural network estimators with built-in analytics and performance monitoring.

## 🎯 **What is LRDBench?**

LRDBench is designed for researchers, data scientists, and practitioners who need to:
- **Compare different long-range dependence estimation methods**
- **Generate synthetic data from stochastic processes**
- **Benchmark estimator performance across various data types**
- **Monitor usage patterns and performance metrics**
- **Use pre-trained models without additional training**

## ✨ **Key Features**

### **🔬 18 Built-in Estimators**
- **Temporal Methods**: DFA, DMA, Higuchi, R/S (4 estimators)
- **Spectral Methods**: Periodogram, Whittle, GPH (3 estimators)
- **Wavelet Methods**: Log Variance, Variance, Whittle, CWT (4 estimators)
- **Multifractal Methods**: MFDFA, Wavelet Leaders (2 estimators)
- **Machine Learning**: Random Forest, Gradient Boosting, SVR (3 estimators)
- **Neural Networks**: CNN, Transformer (2 estimators)

### **📊 5 Stochastic Data Models**
- **FBMModel**: Fractional Brownian Motion
- **FGNModel**: Fractional Gaussian Noise
- **ARFIMAModel**: AutoRegressive Fractionally Integrated Moving Average
- **MRWModel**: Multifractal Random Walk
- **Neural fSDE**: Neural network-based fractional SDEs

### **⚡ High Performance**
- **JAX Optimization**: GPU acceleration for large-scale computations
- **Numba JIT**: Just-in-time compilation for critical loops
- **Parallel Processing**: Multi-core benchmark execution
- **Memory Efficient**: Optimized data structures and algorithms

### **🎯 Production Ready**
- **Pre-trained Models**: All ML and neural models work immediately
- **No Training Required**: Models ready to use after installation
- **Built-in Analytics**: Usage tracking and performance monitoring
- **Robust Error Handling**: Graceful fallbacks and comprehensive reporting

## 🚀 **Quick Start**

### **Installation**

```bash
pip install lrdbench
```

### **Basic Usage**

```python
import lrdbench

# Generate synthetic data
from lrdbench import FBMModel
fbm = FBMModel(H=0.7, sigma=1.0)
data = fbm.generate(1000)

# Run comprehensive benchmark
from lrdbench import ComprehensiveBenchmark
benchmark = ComprehensiveBenchmark()
results = benchmark.run_comprehensive_benchmark()

# Get analytics summary
summary = lrdbench.get_analytics_summary()
print(summary)
```

### **Advanced Usage**

```python
# Generate data with contamination
from lrdbench import FGNModel
fgn = FGNModel(H=0.6, sigma=1.0)
clean_data = fgn.generate(1000)

# Add noise contamination
contaminated_data = clean_data + 0.1 * np.random.randn(1000)

# Run ML vs Classical comparison
results = benchmark.run_ml_classical_comparison()
```

## 📚 **Documentation**

- **📖 [User Guide](documentation/user_guides/getting_started.md)**: Getting started tutorial
- **🔧 [API Reference](documentation/api_reference/README.md)**: Complete API documentation
- **📊 [Examples](examples/)**: Usage examples and demonstrations
- **🔬 [Model Theory](documentation/technical/model_theory.md)**: Mathematical foundations

## 🧪 **Examples & Demos**

### **Quick Examples**
- **Basic Usage**: `examples/quick_start_demo.py`
- **Comprehensive API**: `examples/comprehensive_api_demo.py`
- **Benchmark Examples**: `examples/benchmark_examples.py`

### **Advanced Demos**
- **CPU-based**: `demos/cpu_based/`
- **GPU-based**: `demos/gpu_based/`
- **Performance Comparison**: `demos/gpu_based/high_performance_comparison_demo.py`

## 📊 **Analytics & Monitoring**

LRDBench includes a built-in analytics system that tracks:
- **Usage Patterns**: Which estimators are used most
- **Performance Metrics**: Execution times and resource usage
- **Error Analysis**: Failure patterns and reliability scores
- **Workflow Insights**: Common usage sequences and patterns

```python
# Enable analytics (enabled by default)
lrdbench.enable_analytics(True, privacy_mode=True)

# Get usage summary
summary = lrdbench.get_analytics_summary()

# Generate comprehensive report
report_path = lrdbench.generate_analytics_report(days=30)
```

## 🔧 **Configuration & Customization**

### **Analytics Settings**
```python
# Disable analytics
lrdbench.enable_analytics(False)

# Configure privacy mode
lrdbench.enable_analytics(True, privacy_mode=True)
```

### **Benchmark Configuration**
```python
# Customize benchmark parameters
benchmark = ComprehensiveBenchmark(
    data_lengths=[500, 1000, 2000],
    contamination_levels=[0.0, 0.1, 0.2],
    estimators=['classical', 'ml', 'neural']
)
```

## 🏆 **Performance Benchmarks**

LRDBench has been extensively tested and optimized:
- **Data Generation**: < 10ms for 1000 points
- **Estimation**: < 100ms for most estimators
- **Memory Usage**: Optimized for large datasets
- **GPU Acceleration**: Available for JAX-based methods

## 🤝 **Contributing**

We welcome contributions! Please see our [Development Guide](DEVELOPMENT.md) for:
- Development setup instructions
- Contributing guidelines
- Testing procedures
- Code review process

## 📄 **License**

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

## 👨‍💻 **Author**

**Davian R. Chin**  
*Department of Biomedical Engineering*  
*University of Reading*  
*Email: d.r.chin@pgr.reading.ac.uk*

## 📚 **References**

### **Core Research Papers**
- Beran, J. (1994). Statistics for Long-Memory Processes.
- Mandelbrot, B. B. (1982). The Fractal Geometry of Nature.
- Abry, P., & Veitch, D. (1998). Wavelet analysis of long-range-dependent traffic.
- Muzy, J. F., Bacry, E., & Arneodo, A. (1991). Wavelets and multifractal formalism for singular signals.

### **Neural Network Innovations**
- Hayashi, K., & Nakagawa, K. (2022). fSDE-Net: Generating Time Series Data with Long-term Memory.
- Nakagawa, K., & Hayashi, K. (2024). Lf-Net: Generating Fractional Time-Series with Latent Fractional-Net.
- Li, Z., et al. (2020). Fourier Neural Operator for Parametric Partial Differential Equations.
- Raissi, M., et al. (2019). Physics-informed neural networks: A deep learning framework for solving forward and inverse problems.

---

**For questions, contributions, or collaboration opportunities, please refer to our comprehensive documentation or create an issue on GitHub.**
