Quick Start Guide

This guide will get you started with EPyR Tools in just a few minutes.

Basic Data Loading

EPyR Tools makes it easy to load EPR data from Bruker spectrometers:

import epyr

# Load EPR data (opens file dialog if no path provided)
x, y, params, filepath = epyr.eprload()

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

# Check what you loaded
print(f"Data points: {len(y) if hasattr(y, '__len__') else y.shape}")
print(f"Field range: {x[0].min():.1f} - {x[0].max():.1f} G" if isinstance(x, list) else f"{x.min():.1f} - {x.max():.1f} G")

Supported File Formats

BES3T format: .dsc and .dta file pairs (modern Bruker)
ESP format: .par and .spc file pairs (legacy Bruker)

The function automatically detects the format and returns:

x: Field axis (or list of axes for 2D data)
y: Intensity data (1D array or 2D matrix)
params: Dictionary of experimental parameters
filepath: Path to the loaded file

Baseline Correction

Remove baseline drift and artifacts from your spectra:

from epyr.baseline import baseline_polynomial

# Simple polynomial baseline correction
y_corrected, baseline = baseline_polynomial(y, x_data=x, poly_order=1)

# Advanced correction with signal exclusion
exclude_regions = [(3300, 3400)]  # Exclude peak regions
y_corrected, baseline = baseline_polynomial(
    y, x_data=x, poly_order=2, exclude_regions=exclude_regions
)

Available Methods

Polynomial: Orders 0-5 (constant, linear, quadratic, etc.)
Exponential: Single and stretched exponential decay models
Signal exclusion: Exclude peaks and features from baseline fitting

FAIR Data Conversion

Convert proprietary Bruker files to open, accessible formats:

from epyr.fair import convert_bruker_to_fair

# Convert single file to all formats (CSV, JSON, HDF5)
convert_bruker_to_fair('data.dsc', output_dir='./converted')

# The conversion creates:
# - data.csv: Tabulated data with metadata headers
# - data.json: Complete parameters and measurement info
# - data.h5: Efficient binary format with full metadata

FAIR Benefits

Findable: Standardized metadata and naming
Accessible: No proprietary software needed
Interoperable: Works with Excel, R, Python, MATLAB
Reusable: Complete experimental documentation

Visualization

Create publication-quality EPR plots:

import matplotlib.pyplot as plt

# For 1D spectra
if not isinstance(x, list):
    plt.figure(figsize=(10, 6))
    plt.plot(x, y, 'b-', linewidth=1.5)
    plt.xlabel('Magnetic Field (G)')
    plt.ylabel('EPR Signal (a.u.)')
    plt.grid(True, alpha=0.3)
    plt.show()

# For 2D data, EPyR Tools provides specialized plotting
from epyr.plot import plot_2d_map

if isinstance(x, list) and len(x) > 1:
    # Create 2D color map
    fig, ax = plot_2d_map(x[0], x[1], y, x_unit='G', y_unit='ns')
    plt.show()

Advanced Features

2D spectral maps: Color plots with customizable scales
Interactive plotting: Real-time parameter adjustment
Export options: High-resolution outputs for publications

Complete Example

Here’s a complete workflow from loading to analysis:

import epyr
from epyr.baseline import baseline_polynomial
from epyr.fair import convert_bruker_to_fair
import matplotlib.pyplot as plt
import numpy as np

# 1. Load EPR data
print("Loading EPR data...")
x, y, params, filepath = epyr.eprload('example.dsc')

# 2. Display basic info
if isinstance(x, list):
    print(f"2D data: {y.shape}")
    print(f"Complex data: {np.iscomplexobj(y)}")
else:
    print(f"1D data: {len(y)} points")
    print(f"Field range: {x.min():.1f} - {x.max():.1f} G")

# 3. Apply baseline correction (for 1D data)
if not isinstance(x, list):
    print("Applying baseline correction...")
    y_corrected, baseline = baseline_polynomial(y, x_data=x, poly_order=1)

    # Plot before/after
    plt.figure(figsize=(12, 5))
    plt.subplot(1, 2, 1)
    plt.plot(x, y, 'b-', label='Original')
    plt.plot(x, baseline, 'r--', label='Baseline')
    plt.legend()
    plt.title('Before Correction')

    plt.subplot(1, 2, 2)
    plt.plot(x, y_corrected, 'g-', label='Corrected')
    plt.legend()
    plt.title('After Correction')
    plt.tight_layout()
    plt.show()

# 4. Convert to FAIR formats
print("Converting to FAIR formats...")
convert_bruker_to_fair(filepath, output_dir='./fair_data')
print("✅ Conversion complete!")

# 5. Display key parameters
print("\n📋 Key Parameters:")
key_params = ['MWFQ', 'MWPW', 'HCF', 'HSW', 'AVGS']
for param in key_params:
    if param in params:
        print(f"  {param}: {params[param]}")

Next Steps

Explore Examples: Check examples/notebooks/ for interactive tutorials
Run Scripts: Try the automated scripts in examples/scripts/
Read API Docs: Browse the complete API reference
Join Community: Report issues and contribute on GitHub

Common Workflows

Routine Analysis: Load → Baseline Correct → Plot → Export
Data Conversion: Load → Convert to FAIR → Archive
Batch Processing: Script multiple files → Automated analysis
Research: Interactive notebooks → Custom analysis → Publication plots