Functions

Reference to all SpinLab functions.

Constants

mrProperties

spinlab.constants.mrProperties.mr_properties(nucleus, *args)

Return magnetic resonance property of specified isotope.

This function is modeled after the Matlab function gmr written by Mirko Hrovat: https://www.mathworks.com/matlabcentral/fileexchange/12078-gmr-m-nmr-mri-properties

Also see: R.K.Harris et. al., Pure and Applied Chemistry, 2001, 73:1795-1818. Electron value comes from 1998 CODATA values, http://physics.nist.gov/cuu/Constants, or https://physics.nist.gov/cuu/Constants/index.html. Xenon gyromagnetic ratio was calculated from 27.661 MHz value from Bruker's web site.

Parameters:

  • nucleus (str) -- '0e', '1H', '2H', '6Li', '13C', 14N', etc.

  • B0 (float) -- (optional) B0 field in (mT)

  • flags (Additional) -- gamma: Return Gyromagnetic Ratio (Hz/T) spin: Return spin number of selected nucleus qmom: Return quadrupole moment [fm^2] (100 barns) natAbundance: Return natural abundance (%) relSensitivity: Return relative sensitivity with respect to 1H at constant B0 moment: Return magnetic dipole moment, abs(u)/uN = abs(gamma)*hbar[I(I + 1)]^1/2/uN qlw: Return quadrupolar line-width factor, Qlw = Q^2(2I + 3)/[I^2(2I + 1)]

Examples

sl.slTools.mr_Properties('1H') = 26.7522128 # 1H Gyromagnetic Ratio (10^7r/Ts)

sl.slTools.mr_Properties('1H', 0.35) = 14902114.17018196 # 1H Larmor Freq at .35 T (Hz)

sl.slTools.mr_Properties('2H', 'qmom') = 0.286 # Nuclear Quadrupole Moment (fm^2)

sl.slTools.mr_Properties('6Li', 'natAbundance') = 7.59 # % Natural Abundance

sl.slTools.mr_Properties('6Li', 'relSensitivity') = 0.000645 # Relative sensitivity

radicalProperties

spinlab.constants.radicalProperties.radical_properties(name)

Return properties of different radicals. At the minimum the g value is returned. If available, large hyperfine couplings to a nucleus are returned. Add new properties or new radicals to radicalProperties.py

arg

returns

"gfree"

2.00231930436153

"tempo1"

[[2.00980, 2.00622, 2.00220], "14N", [16.8, 20.5, 95.9]]

"tempo2"

[[2.00909, 2.00621, 2.00222], "14N", [20.2, 20.2, 102.1]]

"bdpa"

[[2.00263, 2.00260, 2.00257], "1H", [50.2, 34.5, 13.0]]

"ddph_neat"

2.0036
Parameters:

name (str) -- Name of the radical

Returns:

Principle g values and hyperfine coupling tensor

Return type:

radicalProperties (dict)

Examples

Return g value of a free electron

>>> radical_properties("gfree")
spinlab.constants.radicalProperties.show_sl_properties(radical, mwFrequency, slNucleus)

Calculate Spin Properties for a given radical

Parameters:

  • radical (str) -- Radical name, see mrProperties.py for radicals that are currently implemented

  • mwFrequency (float) -- Microwave frequency in (Hz)

  • slNucleus (str) -- Nucleus for Spin-NMR experiments

Returns:

Function returns a table of Spin parameters to the screen

Examples

>>> sl.show_sl_poperties('gfree', 9.45e9, '1H')

IO

Bes3t (Bruker)

Functions to import Bruker EPR data

spinlab.io.bes3t.import_bes3t(path)

Import Bruker BES3T data and return sldata object

Parameters:

path (str) -- Path to either .DSC or .DTA file

Returns:

SpinData object containing Bruker BES3T data

Return type:

bes3t_data (object)

spinlab.io.bes3t.load_dsc(path)

Import contents of .DSC file

Parameters:

path (str) -- Path to .DSC file

Returns:

dictionary of parameters

Return type:

attrs (dict)

spinlab.io.bes3t.load_dta(path_dta, path_xgf=None, path_ygf=None, path_zgf=None, attrs={})

Import data from .DTA file. Uses .DSC and .XGF, .YGF, or .ZGF files if they exists

Parameters:

  • path_dta (str) -- Path to .DTA file

  • path_xgf (str) -- path to .XGF file for 1D data with nonlinear axis, "none" otherwise

  • path_ygf (str) -- path to .YGF file for 2D data, "none" if 1D or linear y axis

  • path_zgf (str) -- path to .ZGF file for 3D data, "none" if 1D/2D or linear z axis

  • attrs (dict) -- dictionary of parameters

Returns:

Spectrum for 1D or spectra for 2D dims (list) : dimensions coords (ndarray) : coordinates for spectrum or spectra attrs (dict) : updated dictionary of parameters

Return type:

values (ndarray)

spinlab.io.bes3t.load_gf_files(path, axis_type='', axis_format='', axis_points=1, axis_min=1, axis_width=1, endian='')

Import data from .XGF, .YGF, or .ZGF files

Parameters:

  • path (str) -- Path to ._GF file

  • axis_type (str) -- linear or nonlinear

  • axis_format (str) -- format of file data

  • axis_points (int) -- number of points in axis

  • axis_min (float) -- minimum value of axis

  • axis_width (float) -- total width of axis

  • endian (float) -- endian of data

Returns:

axis coordinates

Return type:

coords (ndarray)

Delta (JEOL)

spinlab.io.delta.import_delta(path, verbose=False)

Import Delta data and return SpinData object

Currently only 1D and 2D data sets are supported.

Parameters:

path (str) -- Path to .jdf file

Returns:

SpinData object containing Delta data

Return type:

sldata (SpinData)

spinlab.io.delta.import_delta_data(path, params={}, verbose=False)

Import spectrum or spectra of Delta data

Currently only 1D and 2D data sets are supported.

Parameters:

  • path (str) -- Path to .jdf file

  • params (dict) -- dictionary of parameters

Returns:

spectrum or spectra if >1D abscissa (list) : coordinates of axes dims (list) : axes names params (dict) : updated dictionary of parameters

Return type:

y_data (ndarray)

spinlab.io.delta.import_delta_pars(path, context_start)

Import parameter fields of Delta data

Parameters:

  • path (str) -- Path to .jdf file

  • context_start (int) -- the index where the context starts

Returns:

dictionary of parameter fields and values

Return type:

params (dict)

Prospa (Magritek)

spinlab.io.prospa.import_csv(path, return_raw=False, is_complex=True)

Import Kea csv file

Parameters:

path (str) -- Path to csv file

Returns:

x(numpy.array): axes if return_raw = False data(numpy.array): Data in csv file

Return type:

tuple

spinlab.io.prospa.import_nd(path)

Import Kea binary 1d, 2d, 3d, 4d files

Parameters:

path (str) -- Path to file

Returns:

x (None, numpy.array): Axes if included in binary file, None otherwise data (numpy.array): Numpy array of data

Return type:

tuple

spinlab.io.prospa.import_par(path)

Import Kea parameters .par file

Parameters:

path (str) -- Path to parameters file

Returns:

Dictionary of Kea Parameters

Return type:

dict

spinlab.io.prospa.import_prospa(path, parameters_filename=None, experiment=None, verbose=False)

Import Kea data

Parameters:

  • path (str) -- Path to data

  • parameters_filename (str)

  • experiment (str) -- Prospa experiment, used when calculating coords from parameters

  • verbose (bool) -- If true, prints additional information for troubleshooting

Returns:

sldata object with Kea data

spinlab.io.prospa.prospa_coords(attrs, data_shape, experiment)

Generate coords from prospa acquisition parameters

Parameters:

  • attrs (dict) -- Dictionary of prospa acqusition parameters

  • data_shape (tuple) -- Shape of data

Returns:

dims and coords

Return type:

tuple

SpecMan (FeMi)

spinlab.io.specman.analyze_attrs(attrs)

Analyze the attrs and add some important attrs to existing dictionary

Parameters:

attrs (dict) -- Dictionary of specman acqusition parameters

Returns:

The dictionary of specman acqusition parameters and added parameters

Return type:

attrs (dict)

spinlab.io.specman.calculate_specman_coords(attrs, old_coords, dims=None)

Generate coords from specman acquisition parameters

Parameters:

  • attrs (dict) -- Dictionary of specman acqusition parameters

  • dims (list) -- (Optional) a list of dims

Returns:

a calculated coords

Return type:

coords (list)

spinlab.io.specman.generate_dims(attrs)

Generate dims from specman acquisition parameters

Parameters:

attrs (dict) -- Dictionary of specman acqusition parameters

Returns:

a new dims

Return type:

dims (list)

spinlab.io.specman.import_specman(path, autodetect_coords: bool = True, autodetect_dims: bool = True, make_complex: bool = True, complex_dim: str = 'x')

Import SpecMan data and return SpinData object

SpinLab function to import SpecMan4EPR data (https://specman4epr.com/). The function returns a Spindata object with the spectral data.

The structure of the Spindata object can be complex and the variables saved by SpecMan depend on the individual spectrometer configuration. Therefore, the import function returns a numpy array with the dimension "x0", "x1", "x2", "x3", "x4". In any case, the dimension "x0" corresponds to the variables stored in the data file. The spectroscopic data is stored in "x1" to "x4", depending on how many dimensions were recorded. The import function will require a parser script to properly assign the spectroscopic data and proper coordinates.

Parameters:

  • path (str) -- Path to either .exp file

  • autodetect_coords (bool) -- Autodetect coords based on attrs

  • autodetect_dims (bool) -- Autodetect dims based on attrs

  • make_complex (bool) -- If True, will create a complex SpinData object if the data is complex

  • complex_dim (str) -- The dimension to use for complex data (default: 'x')

Returns:

SpinData object containing SpecMan EPR data

Return type:

data (SpinData)

spinlab.io.specman.load_specman_d01(path, attrs, verbose=False)

Import SpecMan d01 data file

SpinLab function to import the SpecMan d01 data file. The format of the SpecMan data file is described here:

Parameters:

path (str) -- Path to either .d01 or .exp file

Returns:

SpecMan data as numpy array params (dict): Dictionary with import updated parameters dictionary

Return type:

data (ndarray)

spinlab.io.specman.load_specman_exp(path)

Import SpecMan parameters

SpinLab function to read and import the SpecMan exp file. The .exp file is a text file that stores the experimental data, the pulse program, and other spectrometer configuration files.

Parameters:

path (str) -- Path to either .d01 or .exp file

Returns:

Dictionary of parameter fields and values (SpinLab attributes)

Return type:

attrs (dict)

TopSpin (Bruker)

spinlab.io.topspin.find_group_delay(attrs_dict)

Determine group delay from tables

Parameters:

attrs_dict (dict) -- dictionary of topspin acquisition parameters

Returns:

Group delay. Number of points FID is shifted by DSP. The ceiling of this number (group delay rounded up) is the number of points should be removed from the start of the FID.

Return type:

float

spinlab.io.topspin.import_topspin(path, assign_vdlist=False, remove_digital_filter=False, read_offset=False, verbose=False, **kwargs)

Import topspin data and return sldata object

Parameters:

  • path (str) -- Directory of data

  • assign_vdlist -- False, or the name of dimension to assign topspin vdlist

  • remove_digital_filter (bool) -- Option to remove group delay (see note below)

  • verbose (bool) -- Print additional output for troubleshooting

Note

The group delay is a consequence of the oversampling and digital filtering in Bruker spectrometers. For more details see these blog posts https://nmr-analysis.blogspot.com/2010/05/bruker-smiles.html and https://nmr-analysis.blogspot.com/2010/05/bruker-smiles.html

Returns:

topspin data

Return type:

sldata

spinlab.io.topspin.load_acqu(path, required_params=None, verbose=False)

Import topspin acqu or proc files

Parameters:

  • path (str) -- directory of acqu or proc file

  • required_params (list) -- Only return parameters given

  • verbose (bool) -- If true, print output for troubleshooting

Returns:

Dictionary of acqusition parameters

Return type:

dict

spinlab.io.topspin.load_bin(path, dtype='>i4')

Import Topspin Ser file

Parameters:

  • path (str) -- Directory of data

  • dtype (str) -- data format for import

Returns:

Data from ser file

Return type:

raw (np.ndarray)

spinlab.io.topspin.load_pdata(path, verbose=False)

Import prospa processed data

Parameters:

  • path (str) -- Directory of pdata

  • verbose (bool) -- If true, print output for troubleshooting

Returns:

Topspin processed data

Return type:

SpinData

spinlab.io.topspin.load_ser(path, dtype='>i4')

Depreciated. Use load bin. Import Topspin Ser file

Parameters:

  • path (str) -- Directory of data

  • dtype (str) -- data format for import

Returns:

Data from ser file

Return type:

raw (np.ndarray)

spinlab.io.topspin.load_title(path='1', title_path='pdata/1', title_filename='title')

Import Topspin Experiment Title File

Parameters:

  • path (str) -- Directory of title

  • title_path (str) -- Path within experiment of title

  • title_filename (str) -- filename of title

Returns:

Contents of experiment title file

Return type:

str

spinlab.io.topspin.load_topspin_jcamp_dx(path, verbose=False)

Return the contents of topspin JCAMP-DX file as dictionary

Parameters:

  • path (str) -- Path to file

  • verbose (bool) -- If true, print output for troubleshooting

Returns:

Dictionary of JCAMP-DX file parameters

Return type:

dict

spinlab.io.topspin.topspin_vdlist(path)

Return topspin vdlist

Parameters:

path (str) -- Directory of data

Returns:

vdlist as numpy array

Return type:

numpy.ndarray

VnmrJ (Varian/Agilent)

spinlab.io.vnmrj.array_coords(attrs)

Return array dimension coords from parameters dictionary

Parameters:

attrs (dict) -- Dictionary of procpar parameters

Returns:

dim and coord for array

Return type:

tuple

spinlab.io.vnmrj.import_fid(path, filename='fid')

Import VnmrJ fid file

Parameters:

  • path (str) -- Directory of fid file

  • filename (str) -- Name of fid file. "fid" by default

Returns:

Array of data

Return type:

numpy.ndarray

spinlab.io.vnmrj.import_procpar(path, filename='procpar')

Import VnmrJ procpar parameters file

Parameters:

path (str) -- Directory of file

Returns:

Dictionary of procpar parameters

Return type:

dict

spinlab.io.vnmrj.import_vnmrj(path, fidFilename='fid', paramFilename='procpar')

Import VnmrJ Data

Parameters:

  • path (str) -- path to experiment folder

  • fidFilename (str) -- FID file name

  • paramFilename (str) -- process parameter filename

Returns:

data in sldata object

Return type:

sldata

WinEPR (Bruker)

spinlab.io.winepr.import_winepr(path)

Import Bruker par/spc data and return SpinData object

Parameters:

path (str) -- Path to either .par or .spc file

Returns:

SpinData object containing Bruker par/spc data

Return type:

parspc_data (object)

spinlab.io.winepr.load_par(path)

Import contents of .par file

Parameters:

path (str) -- Path to .par file

Returns:

dictionary of parameters

Return type:

attrs (dict)

spinlab.io.winepr.load_spc(path, attrs)

Import data and axes of .spc file

Parameters:

path (str) -- Path to .spc file

Returns:

coordinates for spectrum or spectra values (ndarray) : data values attrs (dict) : updated dictionary of parameters dims (list) : dimension labels

Return type:

coords (ndarray)

Math

Lineshape

spinlab.math.lineshape.gaussian(x, x0, sigma, integral=1.0)

Gaussian distribution.

Parameters:

  • x (array_like) -- input x

  • x0 (float) -- Center of distribution

  • sigma (float) -- Standard deviation of Gaussian distribution

  • integral (float) -- Integral of distribution

Returns:

Gaussian distribution

Return type:

ndarray

The Gaussian distribution is defined as:

\[f(x; x_0, \sigma) = \frac{1}{\sigma \sqrt{2 \pi}} \exp{\left(\frac{(x-x_0)^2}{2 \sigma^2}\right)}\]
spinlab.math.lineshape.lorentzian(x, x0, gamma, integral=1.0, deriv=False)

Lorentzian Distribution.

Parameters:

  • x (array_like) -- input x

  • x0 (float) -- Center of distribution

  • gamma (float) -- Lorentzian width. 2*gamma is full width at half maximum (FWHM)

  • integral (float) -- Integral of distribution

  • deriv (boolean) -- Derivative of a Lorentzian Distribution (Imaginary part of a phased spectrum)

Returns:

Lorentzian distribution

Return type:

ndarray

The Lorentzian distribution is defined as:

\[f(x) = \frac{1}{\pi \gamma} \left[\frac{\gamma^2}{(x-x_0)^2 + \gamma^2}\right]\]

Derivative:

\[f(x) = \frac{1}{\pi \gamma} \left[\frac{- 2\gamma^2 (x-x_0)}{\left( (x-x_0)^2 + \gamma^2 \right)^2}\right]\]
spinlab.math.lineshape.voigtian(x, x0, sigma, gamma, integral=1.0, deriv=False)

Voigtian distribution. Lineshape given by a convolution of Gaussian and Lorentzian distributions.

Parameters:

  • x (array_like) -- input x

  • x0 (float) -- center of distribution

  • sigma (float) -- Gaussian Linewidth. Standard deviation of Gaussian distribution.

  • gamma (float) -- Lorentzian linewidth. 2*gamma is the full width at half maximum (FWHM)

  • integral (float) -- Integral of distribution

  • deriv (boolean) -- Derivative of a Voigtian distribution (Gaussian broadened imaginary part of a phased spectrum).

Returns:

Voigtian distribution

Return type:

ndarray

The Voigtian distribution is defined as:

\[f(x; x_0, \sigma, \gamma) = \frac{\operatorname{Re}[w(z)]}{\sigma \sqrt{2 \pi}}\]

with

\[z = \frac{x + i\gamma}{\sigma \sqrt{2}}\]

Derivative: .. math:

f(x) = \frac{1}{\sigma^3 \sqrt{2 \pi}} \left[ \gamma \operatorname{Im}[w(z)] - \left(x - x0\right) \operatorname{Re}[w(z)] \right]

with

\[z = \frac{\left( \left( x - x0 \right) + 1j \gamma \right)}{\sigma \sqrt{2}}\]

Relaxation

spinlab.math.relaxation.buildup_function(p, E_max, p_half)

Calculate asymptotic buildup curve

Parameters:

  • p (array) -- power series

  • E_max (float) -- maximum enhancement

  • p_half (float) -- power at half saturation

Returns:

buildup curve

Return type:

ndarray

\[f(p) = 1 + E_{max} * p / (p_{1/2} + p)\]
spinlab.math.relaxation.general_biexp(t, C1, C2, tau1, C3, tau2)

Calculate bi-exponential curve

Parameters:

  • t (array_like) -- time series

  • C1 (float) -- see equation

  • C2 (float) -- see equation

  • C3 (float) -- see equation

  • tau1 (float) -- see equation

  • tau2 (float) -- see equation

Returns:

bi-exponential curve

Return type:

ndarray

\[f(t) = C1 + C2 e^{-t/tau1} + C3 e^{-t/tau2}\]
spinlab.math.relaxation.general_exp(t, C1, C2, tau)

Calculate mono-exponential curve

Parameters:

  • t (array_like) -- time series

  • C1 (float) -- see equation

  • C2 (float) -- see equation

  • tau (float) -- see equation

Returns:

mono-exponential curve

Return type:

ndarray

\[f(t) = C1 + C2 e^{-t/tau}\]
spinlab.math.relaxation.ksigma_smax(p, E_max, p_half)

Calculate asymptotic buildup curve

Parameters:

  • p (array) -- power series

  • E_max (float) -- maximum enhancement

  • p_half (float) -- power at half saturation

Returns:

buildup curve

Return type:

ndarray

\[f(p) = E_{max} * p / (p_{1/2} + p)\]
spinlab.math.relaxation.logistic(x, c, x0, L, k)

Not Implemented. Placeholder for calculating asymptotic buildup curve

Parameters:

  • x (array) -- x values

  • c (float) -- offset

  • x0 (float) -- x-value of sigmoid's midpoint

  • L (float) -- maximum value

  • k (float) -- logistic growth steepness

Returns:

buildup curve

Return type:

ndarray

spinlab.math.relaxation.t1(t, T1, M_0, M_inf)

Exponential recovery for inversion recovery and saturation recovery T1 Measurements

Parameters:

  • t (array_like) -- time series

  • T_1 (float) -- T1 value

  • M_0 (float) -- see equation

  • M_inf (float) -- see equation

Returns:

T1 curve

Return type:

ndarray

\[f(t) = M_{\infty} - (M_{\infty} - M_0) e^{-t/T_1}\]
spinlab.math.relaxation.t2(t, M_0, T2, p=1.0)

Calculate stretched or un-stretched (p=1) exponential T2 curve

Parameters:

  • t (array_like) -- time series

  • M_0 (float) -- see equation

  • T_2 (float) -- T2 value

  • p (float) -- see equation

Returns:

T2 curve

Return type:

ndarray

\[f(t) = M_{0} e^{(-(t/T_{2})^{p}}\]

Window

spinlab.math.window.exponential(x, lw)

Calculate exponential window function

Parameters:

  • x (array_like) -- Vector of points

  • lw (int or float) -- linewidth

Returns:

exponential window function

Return type:

array

\[\mathrm{exponential} = e^{-\pi * x * lw}\]
spinlab.math.window.gaussian(x, lw)

Calculate gaussian window function

Parameters:

  • x (array_like) -- vector of points

  • lw (float) -- Standard deviation of gaussian window

Returns:

gaussian window function

Return type:

array

\[\mathrm{gaussian} = e^{(\sigma * x^{2})}\]
spinlab.math.window.hamming(x)

Calculate hamming window function

Parameters:

  • x (array_like) -- vector of points

  • N (int) -- number of points to return in window function

Returns:

hamming window function

Return type:

ndarray

\[\mathrm{hamming} = 0.53836 + 0.46164\cos(\pi * n / (N-1))\]
spinlab.math.window.hann(x)

Calculate hann window function

Parameters:

  • x (array_like) -- vector of points

  • N (int) -- number of points to return in window function

Returns:

hann window function

Return type:

ndarray

\[\mathrm{hann} = 0.5 + 0.5\cos(\pi * n / (N-1))\]
spinlab.math.window.lorentz_gauss(x, lw, gauss_lw, gaussian_max=0)

Calculate lorentz-gauss window function

Parameters:

  • x (array_like) -- vector of points

  • N (int) -- number of points to return in window function

  • lw (int or float) -- exponential linewidth

  • gauss_lw (int or float) -- gaussian linewidth

  • gaussian_max (int) -- location of maximum in gaussian window

Returns:

gauss_lorentz window function

Return type:

array

\[ \begin{align}\begin{aligned}\mathrm{lorentz\_gauss} &= \exp(L - G^{2}) &\\ L(t) &= \pi * \mathrm{linewidth[0]} * t &\\ G(t) &= 0.6\pi * \mathrm{linewidth[1]} * (\mathrm{gaussian\_max} * (N - 1) - t) &\end{aligned}\end{align} \]
spinlab.math.window.sin2(x)

Calculate sin-squared window function

Parameters:

  • x (array_like) -- vector of points

  • N (int) -- number of points to return in window function

Returns:

sin-squared window function

Return type:

array

\[\sin^{2} = \cos((-0.5\pi * n / (N - 1)) + \pi)^{2}\]
spinlab.math.window.traf(x, lw)

Calculate traf window function

Parameters:

  • x (array_like) -- vector of points

  • lw (str) -- linewidth of traficant window

Returns:

traf window function

Return type:

ndarray

\[ \begin{align}\begin{aligned}\mathrm{traf} &= (f1 * (f1 + f2)) / (f1^{2} + f2^{2}) &\\ f1(t) &= \exp(-t * \pi * \mathrm{linewidth[0]}) &\\ f2(t) &= \exp((t - T) * \pi * \mathrm{linewidth[1]}) &\end{aligned}\end{align} \]

Plotting

Processing