neurological-lrd-analysis 0.4.2

Physics-Informed Fractional Operator Learning for Real-Time Neurological Biomarker Detection: A Framework for Memory-Driven EEG Analysis

Neurological LRD Analysis

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: [e-mail]
ORCiD: https://orcid.org/0009-0003-9434-3919

🚀 Quick Start

Installation

# 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

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

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

# 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 - Comprehensive guides and API reference
• Tutorial - Step-by-step tutorial with examples
• API Reference - Complete API documentation
• Configuration Guide - Application-specific configuration
• Benchmarking Guide - Enhanced benchmarking system
• Jupyter Notebooks - Interactive tutorials for demonstration and training
  • 01_Biomedical_Time_Series_Analysis.ipynb - Biomedical data generation and analysis
  • 02_Hurst_Estimator_Creation_and_Validation.ipynb - Estimator development and validation
  • 03_Benchmarking_and_Leaderboards.ipynb - Systematic benchmarking and performance evaluation

🎯 Use Cases

BCI/Real-time Applications

python scripts/run_benchmark.py --success-weight 0.4 --accuracy-weight 0.2 --speed-weight 0.3 --robustness-weight 0.1

Research Applications

python scripts/run_benchmark.py --success-weight 0.2 --accuracy-weight 0.4 --speed-weight 0.1 --robustness-weight 0.3

Biomedical Scenarios

python scripts/run_benchmark.py --biomedical-scenarios eeg_rest,ecg_normal --contaminations none,noise,electrode_pop

Neurological Conditions

python scripts/run_benchmark.py --biomedical-scenarios eeg_parkinsonian,eeg_epileptic --contaminations heavy_tail,neural_avalanche

🧪 Examples and Demos

Classical Methods

# 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

# 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

# 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

# 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 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 file for details.

🙏 Acknowledgments

• Built with JAX for GPU acceleration and physics-informed learning
• Uses NumPyro for Bayesian inference in fractional operators
• Leverages 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:

@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={[e-mail]},
  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 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:

# 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
• Issue Tracker
• PyPI Package
• GitHub Releases
• Research Paper