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:

• Clean End-to-End Examples

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

Interactive Notebooks

An eight-notebook tutorial series in examples/notebooks/ walks through the public API on the bundled datasets. Notebooks are committed without cell outputs; run them to generate figures.

• Basic Loading Tutorial

To run the series:

cd examples/notebooks
jupyter lab 00_Tutorial_Series_Index.ipynb   # index and navigation

Notebook	Topic
00_Tutorial_Series_Index.ipynb	Overview, environment check, dataset list
01_Loading_and_Plotting.ipynb	eprload, parameter inspection, 1D/2D plots
02_Baseline_Correction.ipynb	Polynomial, automatic, exponential baselines
03_Lineshape_Analysis_and_Fitting.ipynb	Gaussian/Lorentzian/Voigt, derivatives, fitting
04_Relaxation_Fitting.ipynb	T1/T2 decay/recovery models (new in v0.4.0)
05_Signal_Processing_and_FFT.ipynb	Frequency analysis of Rabi data, apodization
06_FAIR_Conversion_and_Export.ipynb	CSV/JSON/HDF5 export and validation
07_Physics_Units_and_Constants.ipynb	CODATA constants, field/frequency conversions

Superseded notebooks are archived under examples/notebooks/_legacy/.

Example Scripts

Ready-to-use Python scripts for common workflows:

• Example Scripts

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_1d
   y_corrected, baseline = baseline_polynomial_1d(x, y, params, 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