EPyR Tools: Electron Paramagnetic Resonance (EPR) Tools in Python

    

License	Tests	Documentation	Version

EPyR Tools is a comprehensive Python package for Electron Paramagnetic Resonance (EPR) spectroscopy data analysis. It provides a complete toolkit for loading, processing, analyzing, and visualizing EPR data from Bruker spectrometers, with a focus on FAIR (Findable, Accessible, Interoperable, and Reusable) data principles.

From basic data loading to advanced quantitative analysis, EPyR Tools offers professional-grade capabilities for EPR researchers, with comprehensive documentation and interactive tutorials.

Key Features

Data Loading & Formats

• Bruker File Support: Load BES3T (.dta/.dsc) and ESP/WinEPR (.par/.spc) files seamlessly
• Automatic Format Detection: Smart file format recognition and parameter extraction
• FAIR Data Conversion: Export to CSV, JSON, and HDF5 formats with complete metadata
• Batch Processing: Handle multiple files efficiently with parallel processing
• Plugin Architecture: Extensible system for custom file formats and processing

Advanced Analysis

• Modern Baseline Correction: Streamlined polynomial correction with interactive region selection
• Peak Detection: Automatic identification of EPR spectral features
• g-Factor Calculations: Precise electronic g-factor determination with field calibration
• Hyperfine Analysis: Pattern recognition and coupling constant extraction
• Quantitative Integration: Single and double integration for spin quantification
• Lineshape Analysis: Comprehensive suite of EPR lineshape functions (Gaussian, Lorentzian, Voigt, pseudo-Voigt)

Command Line Interface

• Complete CLI Suite: 9 professional commands for all EPR workflows
• Interactive Plotting: epyr-plot with measurement tools for precise delta x/y analysis
• Batch Processing: epyr-batch-convert for high-throughput data processing
• Data Validation: epyr-validate with FAIR compliance checking
• Configuration Management: epyr-config for system-wide settings
• Interactive Tools: epyr-isotopes GUI and system information display

Performance & Quality

• Memory Optimization: Intelligent caching and memory management for large datasets
• Parallel Processing: Multi-core support for batch operations
• Quality Assurance: Comprehensive testing suite with 90+ tests
• Code Standards: Professional development workflow with pre-commit hooks
• Security: Automated vulnerability scanning and safe defaults

Visualization & Plotting

• Interactive Measurement Tools: Click-to-measure delta x/y distances with real-time feedback
• 2D Spectral Maps: Professional publication-quality EPR plots
• macOS Optimized: Smooth interactive plotting with TkAgg backend
• Customizable Styling: Flexible plot configuration for different EPR experiments
• Export Options: High-resolution outputs for publications

Learning & Documentation

• Interactive Tutorials: 4 comprehensive Jupyter notebooks (beginner → advanced)
• Complete API Documentation: Professional Sphinx-generated docs
• Example Scripts: Ready-to-use Python automation scripts including lineshape analysis
• Best Practices Guide: EPR analysis workflows and quality assessment

EPR-Specific Tools

• Physical Constants: Comprehensive EPR-relevant constants library
• Isotope Database: Nuclear properties and magnetic parameters
• Field-Frequency Conversion: Precise EPR measurement calculations
• Spectrometer Support: Optimized for modern Bruker EPR systems

Professional Documentation

• Complete Documentation: Comprehensive guides and API reference
• User Guide: Step-by-step tutorials and workflows
• CLI Reference: Command-line interface documentation
• System Architecture: Core modules and plugin system

What's New in v0.3.0

EPyR Tools v0.3.0 represents a major code quality enhancement with professional logging infrastructure:

Professional Logging System

• Centralized Logging: Migrated 398 print statements to structured logging (95.7% coverage)

  • Professional logging infrastructure across 18 core modules
  • Hierarchical log levels: DEBUG, INFO, WARNING, ERROR
  • Timestamped messages with module names for better traceability
  • Consistent log format throughout the entire codebase

• Enhanced Debugging: Better production-ready monitoring capabilities

  • Configurable logging levels via standard Python logging
  • Log to files for permanent records
  • Integration with logging frameworks (Sentry, Logstash, etc.)
  • Full call chain tracing with module information

• Backward Compatible: 100% compatible with existing code

  • No breaking changes - all functionality preserved
  • Default logging configured to match previous print() behavior
  • All 100+ tests passing with no regressions
  • Optional custom logging configuration

Modules Updated

Core modules refactored with professional logging:

• Data Loading: eprload, eprplot, cli
• Signal Processing: frequency_analysis, apowin
• Physics: conversions, units, constants
• Baseline Correction: baseline package (4 modules)
• FAIR Conversion: conversion, exporters, data_processing
• Lineshape Analysis: fitting, convspec
• GUI: isotope_gui

Configuration Example

import logging

# Configure EPyR logging (optional)
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    filename='epyr_analysis.log'
)

# Use EPyR Tools normally
from epyr import eprload
x, y, params, filepath = eprload("data.DTA")
# Logging messages written to epyr_analysis.log

Benefits

• Production Ready: Professional logging standards for real-world deployments
• Better Debugging: Detailed trace information with timestamps and module names
• Maintainability: Single logging configuration point, consistent patterns
• Flexibility: Control output verbosity via standard Python logging configuration

See Also:

• RELEASE_NOTES_v0.3.0.md - Complete v0.3.0 details
• RELEASE_NOTES_v0.2.5.md - Enhanced data handling features
• docs/changelog.rst - Full version history

---

Installation

Prerequisites

• Python 3.8 or higher
• NumPy, matplotlib, pandas, h5py (automatically installed)

Quick Install

pip install epyr-tools

Development Installation

# Clone the repository
git clone https://github.com/BertainaS/epyrtools.git
cd epyrtools

# Install with development dependencies
pip install -e ".[dev,docs]"

# Set up pre-commit hooks
pre-commit install

Verification

# Test installation
epyr --help
epyr-info

# Run test suite
make test

Alternative: Manual Dependencies

# Clone the repository
git clone https://github.com/BertainaS/epyrtools.git
cd epyrtools

# Install dependencies manually
pip install -r requirements.txt

# Optional: Install development tools
pip install -r requirements-dev.txt

Quick Test

# Verify installation
python -c "import epyr; print('EPyR Tools successfully installed!')"

Getting Started

Quick Demo: Loading EPR Data

1. Loading Data

The primary function for loading data is epyr.eprload(). It can be called with a file path or without arguments to open a file dialog.

import epyr.eprload as eprload

# Open a file dialog to select a .dta, .dsc, .spc, or .par file
# The script will automatically plot the data.
x, y, params, file_path = eprload.eprload()

# Or, specify a file path directly:
# x, y, params, file_path = eprload.eprload('path/to/your/data.dsc')

2. Converting to FAIR Formats

Use the epyr.fair module to convert your Bruker files into more accessible formats (.csv, .json, .h5).

from epyr.fair import convert_bruker_to_fair

# Opens a file dialog to select an input file and saves the converted
# files in the same directory.
convert_bruker_to_fair()

# You can also specify input and output paths:
# convert_bruker_to_fair('path/to/data.dsc', output_dir='path/to/output')

3. Modern Baseline Correction

The epyr.baseline module provides streamlined functions for correcting EPR baselines with interactive region selection. Compatible with eprload() data format.

import epyr
import numpy as np

# Load EPR data using eprload
x, y, params, filepath = epyr.eprload("data.dsc")

# Simple automatic correction
corrected, baseline = epyr.baseline.baseline_polynomial_1d(x, y, params)

# With manual region exclusion (e.g., exclude signal regions)
signal_regions = [(3340, 3360), (3380, 3400)]  # mT
corrected, baseline = epyr.baseline.baseline_polynomial_1d(
    x, y, params, 
    manual_regions=signal_regions,
    region_mode='exclude',
    order=2
)

# Interactive region selection for complex spectra
corrected, baseline = epyr.baseline.baseline_polynomial_1d(
    x, y, params,
    interactive=True
)

4. Lineshape Analysis

The epyr.lineshapes module provides comprehensive EPR lineshape functions with advanced capabilities including derivatives, phase rotation, and convolution.

from epyr.lineshapes import Lineshape, gaussian, lorentzian, voigtian
import numpy as np
import matplotlib.pyplot as plt

# Create magnetic field range
B = np.linspace(-10, 10, 1000)  # mT

# Method 1: Direct functions with advanced options
gauss = gaussian(B, center=0, width=4.0, derivative=0)  # Absorption
gauss_1st = gaussian(B, center=0, width=4.0, derivative=1)  # 1st derivative
lorentz = lorentzian(B, center=0, width=4.0, phase=0.0)  # Pure absorption

# True Voigt profiles (convolution of Gaussian and Lorentzian)
voigt = voigtian(B, center=0, sigma=2.0, gamma=2.0)

# Method 2: Unified Lineshape class for consistent API
shape = Lineshape('pseudo_voigt', width=4.0, alpha=0.5)  # 50/50 mix
mixed = shape(B, center=0)

# Plot comparison
plt.plot(B, gauss, label='Gaussian')
plt.plot(B, lorentz, label='Lorentzian')  
plt.plot(B, voigt, label='True Voigt')
plt.plot(B, mixed, label='Pseudo-Voigt')
plt.legend()
plt.show()

5. Simple EPR Plotting

The epyr.eprplot module provides simple, direct plotting functions for EPR data from eprload().

import epyr
import matplotlib.pyplot as plt

# Load EPR data
x, y, params, filepath = epyr.eprload("data.dsc")

# Plot 1D spectrum
epyr.eprplot.plot_1d(x, y, params, title="EPR Spectrum")

# Plot 2D data as color map
epyr.eprplot.plot_2d_map(x, y, params, title="2D EPR Map")

# Plot 2D data as waterfall plot
epyr.eprplot.plot_2d_waterfall(x, y, params, title="2D Waterfall", max_traces=30)

plt.show()

6. Interactive Command-Line Plotting

Experience the new interactive plotting with measurement tools:

# Interactive plotting with measurement tools
epyr-plot --interactive --measure

# Load specific file with measurements
epyr-plot spectrum.dsc --interactive --measure

# Quick analysis with scaling and save
epyr-plot data.dta --interactive --measure -s nG --save

Measurement Features:

• Click two points to measure Δx, Δy, and distance
• Real-time visual feedback with annotations
• macOS optimized for smooth performance
• Right-click to clear, 'c' key for quick clear

7. Isotope GUI

Run the interactive isotope GUI to explore nuclear data. Note that this requires the pandas library.

from epyr.isotope_gui import run_gui

# This will launch the Tkinter GUI
run_gui()

Interactive Tutorials

EPyR Tools includes comprehensive Jupyter notebook tutorials for hands-on learning:

Getting Started (Beginner)

cd examples/notebooks
jupyter notebook 01_Getting_Started.ipynb

Learn EPR data loading, visualization, and FAIR data conversion.

Baseline Correction (Intermediate)

jupyter notebook 06_Baseline_Correction_Functions_Complete.ipynb

Master modern polynomial baseline correction with interactive region selection.

Advanced Analysis (Expert)

jupyter notebook 03_Advanced_Analysis.ipynb

Complete EPR analysis: g-factors, hyperfine structure, quantitative integration.

EPR Lineshape Analysis (Professional)

jupyter notebook 04_EPR_Lineshape_Analysis.ipynb

Comprehensive lineshape analysis: Gaussian, Lorentzian, Voigt profiles, derivatives, and convolution techniques.

Example Scripts

Ready-to-use automation scripts in examples/scripts/:

python examples/scripts/01_basic_loading.py
python examples/scripts/02_baseline_correction.py
python examples/scripts/04_lineshape_analysis.py

Project Structure

epyrtools/
├── epyr/                           # Main package
│   ├── eprload.py                 # Core data loading (BES3T, ESP formats)
│   ├── eprplot.py                 # Simple EPR plotting functions
│   ├── baseline_correction.py     # Modern streamlined baseline correction
│   ├── baseline/                  # Compatibility layer for baseline functions
│   │   └── __init__.py           # Imports from baseline_correction
│   ├── fair/                     # FAIR data conversion
│   │   ├── conversion.py         # Format conversion tools
│   │   ├── exporters.py          # CSV, JSON, HDF5 export
│   │   └── parameter_mapping.py  # Metadata standardization
│   ├── lineshapes/               # EPR lineshape analysis
│   │   ├── gaussian.py           # Gaussian profiles with derivatives
│   │   ├── lorentzian.py         # Lorentzian profiles with phase rotation
│   │   ├── voigtian.py           # True Voigt convolution profiles
│   │   ├── lshape.py             # General lineshape functions
│   │   ├── convspec.py           # Spectrum convolution tools
│   │   └── lineshape_class.py    # Unified lineshape interface
│   ├── constants.py              # EPR physical constants
│   ├── plot.py                   # Advanced EPR plotting
│   ├── isotope_gui/             # Interactive isotope database
│   └── sub/                     # Utility modules
│       ├── loadBES3T.py         # BES3T format loader
│       ├── loadESP.py           # ESP format loader
│       └── utils.py             # File handling utilities
├── docs/                        # Sphinx API documentation
├── examples/                    # Comprehensive tutorial system
│   ├── notebooks/               # Interactive Jupyter tutorials
│   │   └── Getting_Started.ipynb    # Complete beginner tutorial
│   ├── scripts/                 # Python automation examples
│   └── data/                    # EPR measurement files
│       ├── *.DSC, *.DTA        # BES3T format files
│       ├── *.par, *.spc        # ESP format files
│       └── processed/          # Analysis results examples
├── tests/                       # Comprehensive test suite (44 tests)
├── requirements.txt             # Core dependencies
├── requirements-dev.txt         # Development tools
└── pyproject.toml              # Modern Python packaging

Contributing & Support

Documentation

• API Reference: docs/ - Complete function documentation
• Tutorials: examples/notebooks/ - Interactive learning
• Examples: examples/scripts/ - Ready-to-use code

Community

• Issues: GitHub Issues
• Discussions: Share EPR analysis workflows and tips
• Contributing: See contribution guidelines for code contributions

Quality Assurance

• 44 passing tests with pytest
• Pre-commit hooks for code quality
• Type hints and comprehensive docstrings
• Professional packaging with modern Python standards

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors

Lead Developer & Maintainer:

• Sylvain Bertaina - [email protected]

Affiliation:

• Magnetism Group (MAG), IM2NP Laboratory
• CNRS (Centre National de la Recherche Scientifique)

---

EPyR Tools - Professional EPR analysis for the Python ecosystem