neurological-lrd-analysis 0.4.2
Physics-Informed Fractional Operator Learning for Real-Time Neurological Biomarker Detection: A Framework for Memory-Driven EEG Analysis
License: MIT
Requires Python: >=3.11
Keywords: hurst, long-range-dependence, neurological, time-series, fractal, eeg, ecg, neuroscience, wavelet, multifractal, benchmarking, biomedical, physics-informed, fractional-operators, machine-learning, biomarker-detection, memory-driven, real-time, fractional-calculus

# Neurological LRD Analysis

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/badge/PyPI-neurological--lrd--analysis-green.svg)](https://pypi.org/project/neurological-lrd-analysis/)
[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://neurological-lrd-analysis.readthedocs.io/)

A comprehensive library for estimating Hurst exponents in neurological time series data, featuring multiple estimation methods, realistic data generation, and advanced benchmarking capabilities.

**Developed as part of PhD research in Biomedical Engineering at the University of Reading, UK** by Davian R. Chin, focusing on **Physics-Informed Fractional Operator Learning for Real-Time Neurological Biomarker Detection: A Framework for Memory-Driven EEG Analysis**.

**Author:** Davian R. Chin (PhD Candidate in Biomedical Engineering, University of Reading, UK)  
**Email:** d.r.chin@pgr.reading.ac.uk  
**ORCiD:** [https://orcid.org/0009-0003-9434-3919](https://orcid.org/0009-0003-9434-3919)

## 🚀 Quick Start

### Installation

```bash
# Install from PyPI (recommended)
pip install neurological-lrd-analysis

# Install with GPU support
pip install neurological-lrd-analysis[gpu]

# Install with development dependencies
pip install neurological-lrd-analysis[dev]

# Or install from source
git clone https://github.com/dave2k77/neurological_lrd_analysis.git
cd neurological_lrd_analysis
pip install -e .
```

### Basic Usage

#### Classical Methods
```python
from neurological_lrd_analysis import BiomedicalHurstEstimatorFactory, EstimatorType

# Create factory instance
factory = BiomedicalHurstEstimatorFactory()

# Estimate Hurst exponent using DFA
result = factory.estimate(
    data=your_time_series,
    method=EstimatorType.DFA,
    confidence_method="bootstrap",
    n_bootstrap=100
)

print(f"Hurst exponent: {result.hurst_estimate:.3f}")
print(f"Confidence interval: {result.confidence_interval}")
print(f"Data quality score: {result.data_quality_score:.3f}")
```

#### Machine Learning Methods
```python
from neurological_lrd_analysis import (
    create_pretrained_suite, quick_predict, quick_ensemble_predict,
    ClassicalMLBenchmark, run_comprehensive_benchmark
)

# Create pretrained models (one-time setup)
create_pretrained_suite("pretrained_models", force_retrain=True)

# Fast ML prediction
hurst_ml = quick_predict(your_time_series, "pretrained_models", "random_forest")

# Ensemble prediction (best accuracy)
hurst_ensemble, uncertainty = quick_ensemble_predict(your_time_series, "pretrained_models")

# Comprehensive benchmark comparison
results = run_comprehensive_benchmark()
print(f"Best method: {results['best_method']}")
print(f"Performance: {results['performance_metrics']}")
```

#### Benchmark Results
```python
# Run comprehensive benchmark
benchmark = ClassicalMLBenchmark("pretrained_models")
results = benchmark.run_comprehensive_benchmark()

# Access results
print("Performance Summary:")
for method, metrics in results['summaries'].items():
    print(f"{method}: MAE={metrics.mean_absolute_error:.4f}, "
          f"Time={metrics.mean_computation_time*1000:.1f}ms")
```

## ✨ Features

### 🧮 **Multiple Estimation Methods**
- **Classical Methods**: DFA, R/S Analysis, Higuchi, Generalized Hurst Exponent, Periodogram, GPH, Whittle MLE, DWT, Abry-Veitch, MFDFA
- **ML Methods**: Random Forest, Support Vector Regression, Gradient Boosting, Ensemble approaches
- **Hybrid Approaches**: Classical + ML ensemble methods for optimal performance

### 🤖 **Machine Learning Baselines**
- **Feature Extraction**: 74+ comprehensive features (statistical, spectral, wavelet, fractal, biomedical)
- **Hyperparameter Optimization**: Automated tuning with Optuna
- **Pretrained Models**: Fast inference with pre-trained ML models
- **Ensemble Methods**: Weighted combination of multiple ML models
- **Real-time Inference**: 10-50ms prediction times

### 🏥 **Biomedical Scenarios**
- **EEG**: Rest, eyes closed/open, sleep, seizure patterns
- **ECG**: Normal heart rate, tachycardia, realistic QRS complexes
- **Respiratory**: Breathing patterns, irregular breathing
- **Neurological**: Memory-driven EEG analysis, neurological biomarker detection
- **Artifacts**: Electrode pops, motion, baseline drift, powerline interference
- **Physics-Informed Features**: Fractional operator learning, real-time biomarker detection

### 📊 **Statistical Analysis**
- Bootstrap confidence intervals
- Theoretical confidence intervals
- Uncertainty quantification
- Comprehensive error metrics (bias, MAE, RMSE)
- Cross-validation and model validation

### 🏆 **Comprehensive Benchmarking**
- **Classical vs ML Comparison**: Direct performance comparison between methods
- **Real Benchmark Results**: Actual performance data with CSV exports
- **Visualization System**: Publication-ready plots and analysis
- **Performance Metrics**: MAE, RMSE, correlation, computation time, success rate
- **Method Rankings**: Clear performance and speed rankings

### ⚡ **Performance Optimization**
- JAX GPU acceleration
- Numba CPU optimization
- Intelligent backend selection
- Lazy imports for efficiency
- ML model caching and fast inference

## 📖 Documentation

- **[Complete Documentation](docs/)** - Comprehensive guides and API reference
- **[Tutorial](docs/TUTORIAL.md)** - Step-by-step tutorial with examples
- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation
- **[Configuration Guide](docs/CONFIGURATION_GUIDE.md)** - Application-specific configuration
- **[Benchmarking Guide](docs/BENCHMARKING_GUIDE.md)** - Enhanced benchmarking system
- **[Jupyter Notebooks](notebooks/)** - Interactive tutorials for demonstration and training
  - [01_Biomedical_Time_Series_Analysis.ipynb](notebooks/01_Biomedical_Time_Series_Analysis.ipynb) - Biomedical data generation and analysis
  - [02_Hurst_Estimator_Creation_and_Validation.ipynb](notebooks/02_Hurst_Estimator_Creation_and_Validation.ipynb) - Estimator development and validation
  - [03_Benchmarking_and_Leaderboards.ipynb](notebooks/03_Benchmarking_and_Leaderboards.ipynb) - Systematic benchmarking and performance evaluation

## 🎯 Use Cases

### BCI/Real-time Applications
```bash
python scripts/run_benchmark.py --success-weight 0.4 --accuracy-weight 0.2 --speed-weight 0.3 --robustness-weight 0.1
```

### Research Applications
```bash
python scripts/run_benchmark.py --success-weight 0.2 --accuracy-weight 0.4 --speed-weight 0.1 --robustness-weight 0.3
```

### Biomedical Scenarios
```bash
python scripts/run_benchmark.py --biomedical-scenarios eeg_rest,ecg_normal --contaminations none,noise,electrode_pop
```

### Neurological Conditions
```bash
python scripts/run_benchmark.py --biomedical-scenarios eeg_parkinsonian,eeg_epileptic --contaminations heavy_tail,neural_avalanche
```

## 🧪 Examples and Demos

### Classical Methods
```bash
# Run biomedical scenarios demonstration
python scripts/biomedical_scenarios_demo.py

# Run neurological conditions demonstration
python scripts/neurological_conditions_demo.py

# Run NumPyro integration demonstration
python scripts/numpyro_integration_demo.py

# Run application scoring demonstration
python scripts/application_scoring_demo.py
```

### Machine Learning Methods
```bash
# Run ML baselines demonstration
python scripts/ml_baselines_demo.py

# Run pretrained models demonstration
python scripts/pretrained_models_demo.py

# Run comprehensive benchmark demonstration
python scripts/comprehensive_benchmark_demo.py
```

### Benchmark Results
```bash
# View actual benchmark results
ls results/comprehensive_benchmark/
# - benchmark_results.csv (detailed results)
# - performance_metrics.csv (summary metrics)
# - comprehensive_benchmark_visualization.png
# - detailed_performance_analysis.png
```

## 🧪 Testing

```bash
# Run all tests
python -m pytest tests/ -v

# Run specific test categories
python -m pytest tests/test_accuracy.py -v
python -m pytest tests/test_backends.py -v
python -m pytest tests/test_registry.py -v
```

## 📊 Project Structure

```
neurological_lrd_analysis/
├── neurological_lrd_analysis/     # Main package directory
│   ├── biomedical_hurst_factory.py    # Main library file
│   ├── benchmark_core/                # Core benchmarking functionality
│   ├── benchmark_backends/            # Backend selection and optimization
│   ├── benchmark_registry/            # Estimator registry system
│   └── ml_baselines/                  # Machine learning baselines
│       ├── feature_extraction.py       # 74+ feature extraction
│       ├── ml_estimators.py          # ML model implementations
│       ├── hyperparameter_optimization.py  # Optuna integration
│       ├── pretrained_models.py       # Model management system
│       ├── inference.py              # Fast inference system
│       └── benchmark_comparison.py   # Classical vs ML comparison
├── docs/                         # Documentation
├── notebooks/                    # Interactive Jupyter tutorials
│   ├── 01_Biomedical_Time_Series_Analysis.ipynb
│   ├── 02_Hurst_Estimator_Creation_and_Validation.ipynb
│   ├── 03_Benchmarking_and_Leaderboards.ipynb
│   └── README.md
├── scripts/                      # Demo scripts and utilities
│   ├── ml_baselines_demo.py          # ML baselines demonstration
│   ├── pretrained_models_demo.py     # Pretrained models demo
│   └── comprehensive_benchmark_demo.py # Full benchmark demo
├── tests/                        # Test suite
│   ├── test_ml_baselines.py          # ML baselines tests
│   ├── test_pretrained_models.py     # Pretrained models tests
│   └── test_benchmark_comparison.py  # Benchmark comparison tests
├── examples/                     # Example notebooks and code
├── results/                      # Benchmark results and outputs
│   └── comprehensive_benchmark/       # Actual benchmark results
│       ├── benchmark_results.csv      # Detailed results
│       ├── performance_metrics.csv    # Summary metrics
│       └── *.png                     # Visualizations
├── pyproject.toml               # Package configuration
├── setup.py                     # Setup script
└── requirements.txt             # Dependencies
```

## 🤝 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 some 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 [JAX](https://github.com/google/jax) for GPU acceleration and physics-informed learning
- Uses [NumPyro](https://github.com/pyro-ppl/numpyro) for Bayesian inference in fractional operators
- Leverages [PyWavelets](https://github.com/PyWavelets/pywavelets) for wavelet-based fractional analysis
- Inspired by research in physics-informed machine learning and memory-driven neurological signal processing

## 📚 Citation

If you use this library in your research, please cite:

```bibtex
@software{neurological_lrd_analysis,
  title={Neurological LRD Analysis: A Comprehensive Library for Physics-Informed Fractional Operator Learning and Real-Time Neurological Biomarker Detection},
  author={Davian R. Chin},
  year={2025},
  institution={University of Reading, UK},
  email={d.r.chin@pgr.reading.ac.uk},
  orcid={https://orcid.org/0009-0003-9434-3919},
  note={PhD Research in Biomedical Engineering: A Framework for Memory-Driven EEG Analysis},
  url={https://github.com/dave2k77/neurological_lrd_analysis}
}
```

## 📦 Releases and Versioning

This project follows [Semantic Versioning](https://semver.org/) and uses GitHub Actions for automated releases to PyPI.

### Creating a New Release

1. **Bump version**: `python scripts/bump_version.py 0.4.1`
2. **Commit changes**: `git add . && git commit -m "Bump version to 0.4.1"`
3. **Create tag**: `git tag v0.4.1`
4. **Push to GitHub**: `git push origin main --tags`
5. **GitHub Actions** will automatically:
   - Run tests
   - Build the package
   - Publish to PyPI
   - Create a GitHub release

### Development Releases

For testing, you can publish to TestPyPI:

```bash
# Push to develop branch to trigger TestPyPI publishing
git checkout develop
git push origin develop
```

### Installation Options

- **Stable releases**: `pip install neurological-lrd-analysis`
- **Development versions**: `pip install git+https://github.com/dave2k77/neurological_lrd_analysis.git`
- **Test versions**: `pip install --index-url https://test.pypi.org/simple/ neurological-lrd-analysis`

## 🔗 Links

- [Documentation](https://neurological-lrd-analysis.readthedocs.io/)
- [Issue Tracker](https://github.com/dave2k77/neurological_lrd_analysis/issues)
- [PyPI Package](https://pypi.org/project/neurological-lrd-analysis/)
- [GitHub Releases](https://github.com/dave2k77/neurological_lrd_analysis/releases)
- [Research Paper](docs/comprehensive-lrd-estimators-paper.md)