Tutorials and Examples

Learn EPyR Tools through hands-on tutorials and practical examples.

Clean End-to-End Scripts

For users who want short, runnable, copy-pasteable scripts:

These five scripts in examples/clean/ cover loading + plotting, baseline + fitting, FFT windowing, the 2D slicer, and Rabi frequency analysis. They are the recommended starting point.

Interactive Notebooks

Our Jupyter notebooks provide interactive tutorials for learning EPyR Tools:

Location: examples/notebooks/

To run the notebooks:

cd examples/notebooks
jupyter notebook

Basic Loading Tutorial

File: 01_Basic_Loading.ipynb

Learn the fundamentals of EPR data loading:

  • Loading BES3T and ESP format files

  • Understanding 1D vs 2D data structures

  • Handling complex EPR data

  • Basic parameter extraction

  • Simple visualization techniques

  • Data export for external analysis

Prerequisites: Basic Python knowledge Duration: 20-30 minutes

Baseline Correction Tutorial

Coming Soon: 02_Baseline_Correction.ipynb

Master baseline correction techniques:

  • Understanding baseline artifacts

  • Polynomial correction methods

  • Signal region exclusion

  • Advanced exponential models

  • Quality assessment metrics

  • Best practices for different data types

Prerequisites: Basic Loading Tutorial Duration: 30-45 minutes

FAIR Data Conversion Tutorial

Coming Soon: 03_FAIR_Conversion.ipynb

Convert proprietary data to open formats:

  • FAIR data principles

  • CSV export with metadata

  • JSON parameter documentation

  • HDF5 for large datasets

  • Cross-platform compatibility

  • Integration with other tools

Prerequisites: Basic Loading Tutorial Duration: 25-35 minutes

Example Scripts

Ready-to-use Python scripts for common workflows:

Location: examples/scripts/

Basic Loading Script

File: 01_basic_loading.py

Automated EPR data loading and visualization:

python examples/scripts/01_basic_loading.py

Features:

  • Finds all EPR files in data directory

  • Handles both 1D and 2D data automatically

  • Creates publication-quality plots

  • Extracts and displays key parameters

  • Saves plots with descriptive names

Baseline Correction Script

File: 02_baseline_correction.py

Comprehensive baseline correction workflow:

python examples/scripts/02_baseline_correction.py

Features:

  • Multiple correction algorithms

  • Visual comparison of methods

  • Advanced exclusion region handling

  • Quality metrics calculation

  • Automated method selection

FAIR Conversion Script

File: 03_fair_conversion.py

Batch conversion to FAIR formats:

python examples/scripts/03_fair_conversion.py

Features:

  • Processes entire data directories

  • Creates multiple output formats

  • Preserves complete metadata

  • Generates conversion reports

  • Format comparison analysis

Sample Data

The examples/data/ directory contains sample EPR data files:

BES3T Format Files:

  • 130406SB_CaWO4_Er_CW_5K_20.DSC/.DTA - 1D CW-EPR spectrum

  • Rabi2D_GdCaWO4_13dB_3057G.DSC/.DTA - 2D pulsed EPR (Rabi oscillation)

  • Rabi2D_GdCaWO4_6dB_3770G_2.DSC/.DTA - 2D pulsed EPR (different conditions)

ESP Format Files:

  • 2014_03_19_MgO_300K_111_fullrotation33dB.par/.spc - Angular rotation study

Data Characteristics:

  • 1D Data: Single EPR spectra vs magnetic field

  • 2D Data: Parameter-dependent EPR (time, power, angle, etc.)

  • Complex Data: Pulsed EPR experiments with I/Q detection

  • Real Data: CW-EPR and integrated signals

Common Workflows

Routine EPR Analysis

  1. Load Data:

    import epyr
x, y, params, filepath = epyr.eprload('spectrum.dsc')

  2. Check Data Type:

    if isinstance(x, list):
    print(f"2D data: {y.shape}")
else:
    print(f"1D data: {len(y)} points")

  3. Apply Baseline Correction:

    from epyr.baseline import baseline_polynomial
y_corrected, baseline = baseline_polynomial(y, x_data=x, poly_order=1)

  4. Visualize Results:

    import matplotlib.pyplot as plt
plt.plot(x, y_corrected)
plt.xlabel('Magnetic Field (G)')
plt.ylabel('EPR Signal (a.u.)')
plt.show()

  5. Export Data:

    from epyr.fair import convert_bruker_to_fair
convert_bruker_to_fair(filepath, output_dir='./results')

Research Data Management

  1. Batch Processing:

    from pathlib import Path
from epyr.fair import convert_bruker_to_fair

data_dir = Path('raw_data')
for epr_file in data_dir.glob('*.dsc'):
    convert_bruker_to_fair(epr_file, output_dir='fair_data')

  2. Quality Control:

    # Check data integrity
if x is None or y is None:
    print(f"Failed to load {filepath}")
    continue

# Validate parameters
required_params = ['MWFQ', 'HCF', 'HSW']
missing = [p for p in required_params if p not in params]
if missing:
    print(f"Missing parameters: {missing}")

  3. Metadata Documentation:

    # Document experimental conditions
metadata = {
    'sample': params.get('SAMP', 'Unknown'),
    'temperature': params.get('TE', 'Not recorded'),
    'frequency': params.get('MWFQ', 'Not specified'),
    'power': params.get('MWPW', 'Not specified'),
}

Publication Preparation

  1. High-Quality Plots:

    plt.figure(figsize=(8, 6), dpi=300)
plt.plot(x, y_corrected, 'k-', linewidth=2)
plt.xlabel('Magnetic Field (G)', fontsize=14)
plt.ylabel('EPR Signal (a.u.)', fontsize=14)
plt.tick_params(labelsize=12)
plt.tight_layout()
plt.savefig('figure1.png', dpi=300, bbox_inches='tight')

  2. Data Archiving:

    # Create comprehensive archive
archive_dir = Path('publication_data')
archive_dir.mkdir(exist_ok=True)

# Save processed data
np.savetxt(archive_dir / 'processed_spectrum.txt',
           np.column_stack([x, y_corrected]),
           header='Field(G) Intensity(a.u.)')

# Save metadata
import json
with open(archive_dir / 'metadata.json', 'w') as f:
    json.dump(params, f, indent=2)

  3. Reproducible Analysis:

    # Document analysis parameters
analysis_log = {
    'epyr_version': epyr.__version__,
    'baseline_method': 'polynomial',
    'baseline_order': 1,
    'processing_date': datetime.now().isoformat(),
    'input_file': str(filepath),
}

Troubleshooting

Common Issues and Solutions

“No module named ‘epyr’”

  • Check installation: pip list | grep epyr

  • Reinstall: pip install -e . --force-reinstall

  • Verify Python path: sys.path should include project directory

“Failed to load EPR file”

  • Check file pairs: .dsc needs .dta, .par needs .spc

  • Verify file permissions and path

  • Try with different file to isolate issue

“Baseline correction fails”

  • Check if data is 1D: y.ndim == 1

  • Verify field data: len(x) == len(y)

  • Try lower polynomial order first

“Complex data visualization issues”

  • Use magnitude: np.abs(complex_data)

  • Check data shape for 2D: isinstance(x, list)

  • Try different plotting approaches for 2D data

Getting Help

  • Documentation: Check API reference and examples

  • GitHub Issues: Report bugs and ask questions

  • Community: Join discussions and share experiences

  • Email: Contact maintainers for specific problems

Next Steps

After completing these tutorials:

  1. Explore Advanced Features: Try custom analysis scripts

  2. Join Community: Contribute examples and improvements

  3. Apply to Research: Use EPyR Tools in your scientific work

  4. Share Results: Publish reproducible EPR data and analyses