screamlab.utils module

Spectral Analysis/Fitting Module

This module provides tools for fitting spectral data and analyzing buildup behaviors using the lmfit package. It includes several classes designed for spectral deconvolution and dynamic nuclear polarization (DNP) buildup kinetic analysis.

Classes:
Spectral Fitting/Deconvolution Classes:
  • Fitter: The base class for fitting spectral data.

    • Prefitter: A specialized fitter that fits a preselected spectrum.

    • GlobalFitter: A fitter that applies parameter constraints across multiple spectra.

    • IndependentFitter: A simple extension of Fitter with no additional functionality.

DNP Buildup Kinetic Fitting Classes:
  • BuildupFitter: The parent class for fitting DNP buildup kinetics.

    • ExpFitter: A fitter for single-exponential buildup behavior.

    • ExpFitterWithOffset: A variant of ExpFitter with an additional offset parameter.

    • BiexpFitter: A fitter for biexponential buildup behavior.

    • BiexpFitterWithOffset: A variant of BiexpFitter with an additional offset parameter.

    • StretchedExponentialFitter: A fitter for stretched exponential buildup behavior.

    • ExponentialDecayFitter: A fitter for exponential decay behaviour.

    • StretchedExponentialDecayFitter: A fitter for stretched exponential decay behaviour.

    • BiexponentialDecayFitter: A fitter for biexponential decay behaviour

class screamlab.utils.Fitter(dataset)

Bases: object

Base class for spectral fitting using lmfit.

This class handles parameter initialization and spectral fitting for a dataset.

dataset

Containing spectra and peak information.

Type:

screamlab.ds.Dataset

fit()

Performs spectral fitting using the lmfit.minimize function.

Returns:

The result of the fitting process.

Return type:

lmfit.MinimizerResult

class screamlab.utils.Prefitter(dataset)

Bases: Fitter

A subclass of Fitter that performs a preliminary fit on a preselected spectrum.

By fitting the spectrum first, it estimates optimal parameters, particularly for linewidths, and narrows down the parameter intervals. The pre-fit parameters define bounds (±10%) for the linewidths. These refined intervals are then used in the global fit, significantly reducing computational time by limiting the parameter range.

class screamlab.utils.NumericalIntegration(dataset)

Bases: Fitter

Subclass of Fitter that calculates spectral signal intensities via numerical integration.

This class is designed for applications where the area under a curve in a given spectral window is of interest, such as quantifying peak intensities in spectroscopy or other analytical measurements. By integrating over a defined region, it provides a robust measure of signal strength that accounts for variations in peak shape and baseline fluctuations.

fit()

Performs spectral numerical integration using numpy trapz or trapezoid function.

Returns:

The result of the integration process.

Return type:

dict

class screamlab.utils.GlobalFitter(dataset)

Bases: Fitter

Global fit over all spectra at different polarization times.

For SCREAM-DNP data, it can be assumed that the line broadening did not vary over all polarization times in cases where a homogeneous polarization buildup on protons exists.

Same goes for the center of each peak since the chemical shift is not depending on the polarization time. For this, it is recommended to carefully reference all spectra during post-processing. With this, the number of fitting parameters can drastically be reduced, yielding a shorter calculation time. In this case, all spectra from a SCREAM-DNP buildup series can be described by two lineshape parameters (sigma and gamma), one variable for the peak center (µ), and n amplitude variables per resonance, where n stands for the number of spectra within one series.

class screamlab.utils.IndependentFitter(dataset)

Bases: Fitter

Fit of each spectrum with individual parameter set.

In some cases it might be necessary to simulate each spectrum from one series with its own parameter set.

This option is also provided. Each resonance in each spectrum will be fitted to two lineshape parameters, an amplitude and a globally determined peak center. Note that this yields higher run times. A prefit can be combined with this case to save time. However, it must be ensured that all spectra can be fitted by conditions given in point two.

class screamlab.utils.BuildupFitter(dataset)

Bases: object

Base class for fitting buildup data using lmfit.

This class is responsible for performing a fitting procedure on a ds of peaks with time-dependent intensities.

dataset

intensity and polarization time information.

Type:

screamlab.ds.Dataset containing peak

perform_fit()

Perform the fitting procedure on the ds’s peak list.

Returns:

List of best fit results for each peak.

class screamlab.utils.BiexpFitter(dataset)

Bases: BuildupFitter

Class for fitting biexponential models to buildup data.

The biexponential model fits buildup curves using two exponential terms characterized by amplitudes (Af, As) and time constants (tf, ts).

The model function is defined as:

I(t) = Af * (1 - exp(-t_pol / tf)) + As * (1 - exp(-t_pol / ts))

where:

  • Af, As : amplitudes of the exponential components

  • tf, ts : time constants of the exponential components (tf, ts > 0)

  • t_pol : polarization time (independent variable)

  • I(t_pol) : peak intensity at polarization time t_pol

class screamlab.utils.StretchedExponentialDecayFitter(dataset)

Bases: BuildupFitter

Class for fitting streched exponential decay data.

This fits buildup curves using an streched exponential term characterized by amplitude (Af), time constant (tf), and stretching factor (beta)..

The model function is defined as:

I(t) = Af * exp(-(t_pol / tf)^beta))

where:

  • Af : amplitudes of the exponential components

  • tf : time constants of the exponential components (tf > 0)

  • beta : stretching factor (beta > 0, controls deviation from a simple exponential)

  • t_pol : polarization time (independent variable)

  • I(t_pol): peak intensity at polarization time t_pol

class screamlab.utils.BiexponentialDecayFitter(dataset)

Bases: BuildupFitter

Class for fitting biexponential decay data.

The biexponential model fits buildup curves using two exponential terms characterized by amplitudes (Af, As) and time constants (tf, ts).

The model function is defined as:

I(t) = Af * exp(-t_pol / tf)) + As * exp(-t_pol / ts))

where:

  • Af, As : amplitudes of the exponential components

  • tf, ts : time constants of the exponential components (tf, ts > 0)

  • t_pol : polarization time (independent variable)

  • I(t_pol) : peak intensity at polarization time t_pol

class screamlab.utils.ExpDecayFitter(dataset)

Bases: BuildupFitter

Class for fitting exponential decay models to experimental data.

The exponential decay model fits decay curves using one exponential term characterized by an amplitude (A) and a time constants (t).

The model function is defined as:

I(t_pol) = A * exp(-t_pol / t)

where:

  • A : amplitudes of the exponential components

  • t : time constants of the exponential components (t > 0)

  • t_pol : polarization time (independent variable)

  • I(t_pol) : peak intensity at polarization time t_pol

class screamlab.utils.ExpDecayFitterWithOffset(dataset)

Bases: BuildupFitter

Class for fitting exponential decay models to experimental data.

The exponential decay model fits decay curves using one exponential term characterized by an amplitude (A), an intensity offset (I0) and a time constants (t).

The model function is defined as:

I(t_pol) = I0 + A * exp(-t_pol / t)

where:

  • A : amplitudes of the exponential components

  • t : time constants of the exponential components (t > 0)

  • t_pol : polarization time (independent variable)

  • I0 : Intensity offset

  • I(t_pol) : peak intensity at polarization time t_pol

class screamlab.utils.BiexpFitterWithOffset(dataset)

Bases: BuildupFitter

Class for fitting biexponential models with offset to buildup data.

This fits buildup curves using two exponential terms characterized by amplitudes (Af, As), time constants (tf, ts) and offset (t_off).

The model function is defined as:

I(t) = Af * (1 - exp(-(t_pol-t_off) / tf)) + As * (1 - exp(-(t_pol-t_off) / ts))

where:

  • Af, As : amplitudes of the exponential components

  • tf, ts : time constants of the exponential components (tf, ts > 0)

  • t_off : offset in polarization time

  • t_pol : polarization time (independent variable)

  • I(t_pol) : peak intensity at polarization time t_pol

class screamlab.utils.ExpFitter(dataset)

Bases: BuildupFitter

Class for fitting exponential models to buildup data.

This fits buildup curves using an exponential term characterized by amplitude (Af) and time constant (tf).

The model function is defined as:

I(t) = Af * (1 - exp(-t_pol / tf))

where:

  • Af : amplitudes of the exponential components

  • tf : time constants of the exponential components (tf > 0)

  • t_pol : polarization time (independent variable)

  • I(t_pol) : peak intensity at polarization time t_pol

class screamlab.utils.ExpFitterWithOffset(dataset)

Bases: BuildupFitter

Class for fitting exponential models with offset to buildup data.

This fits buildup curves using an exponential term characterized by amplitude (Af), time constant (tf) and offset (t_off).

The model function is defined as:

I(t) = Af * (1 - exp(-(t_pol-t_off) / tf))

where:

  • Af : amplitudes of the exponential components

  • tf : time constants of the exponential components (tf > 0)

  • t_off : offset in polarization time

  • t_pol : polarization time (independent variable)

  • I(t_pol) : peak intensity at polarization time t_pol

class screamlab.utils.StretchedExponentialFitter(dataset)

Bases: BuildupFitter

Class for fitting streched exponential models to buildup data.

This fits buildup curves using an streched exponential term characterized by amplitude (Af), time constant (tf), and stretching factor (beta)..

The model function is defined as:

I(t) = Af * (1 - exp(-(t_pol / tf)^beta))

where:

  • Af : amplitudes of the exponential components

  • tf : time constants of the exponential components (tf > 0)

  • beta : stretching factor (beta > 0, controls deviation from a simple exponential)

  • t_pol : polarization time (independent variable)

  • I(t_pol): peak intensity at polarization time t_pol