utils

Utility functions for analysis of MRS data.

bi_square

MRS.utils.bi_square(xx, idx=None)

The bi-square weight function calculated over values of xx

Parameters:xx: float array :

Notes

This is the first equation on page 831 of [Cleveland79].

detect_outliers

MRS.utils.detect_outliers(in_arr, thresh=3.0)

Detects outliers more than X standard deviations from mean.

Parameters:

in_list: ndarray :

An array of measures for which outliers need to be detected.

thresh: float (optional) :

Threshold number of standard deviations before a measure is considered an outlier. Default = 3.0

Returns:

outlier_idx: ndarray of boolean :

An array indicating if a measure is an outlier (True) or not (False).

do_kernel

MRS.utils.do_kernel(x0, x, l=1.0, kernel=<function epanechnikov at 0x1091f3230>)

Calculate a kernel function on x in the neighborhood of x0

Parameters:

x: float array :

All values of x

x0: float :

The value of x around which we evaluate the kernel

l: float or float array (with shape = x.shape) :

Width parameter (metric window size)

epanechnikov

MRS.utils.epanechnikov(xx, idx=None)

The Epanechnikov kernel estimated for xx values at indices idx (zero elsewhere)

Parameters:

xx: float array :

Values of the function on which the kernel is computed. Typically, these are Euclidean distances from some point x0 (see do_kernel)

idx: tuple :

An indexing tuple pointing to the coordinates in xx for which the kernel value is estimated. Default: None (all points are used!)

Notes

This is equation 6.4 in FHT chapter 6

freq_to_ppm

MRS.utils.freq_to_ppm(f, water_hz=0.0, water_ppm=4.7, hz_per_ppm=127.68)

Convert a set of numbers from frequenxy in hertz to chemical shift in ppm

gaussian

MRS.utils.gaussian(freq, freq0, sigma, amp, offset, drift)

A Gaussian function with flexible offset, drift and amplitude

l2_norm

MRS.utils.l2_norm(arr)

The l2 norm of an array is is defined as: sqrt(||x||), where ||x|| is the dot product of the vector.

line_broadening

MRS.utils.line_broadening(ts, width)

Apply line-broadening to a time-series

Parameters:

ts : a nitime.TimeSeries class instance

width : float

The exponential decay time-constant (in seconds)

Returns:

A nitime.TimeSeries class instance with windowed data :

Notes

For details, see page 92 of Keeler2005.

[Keeler2005]

Keeler, J (2005). Understanding NMR spectroscopy, second edition. Wiley (West Sussex, UK).

lorentzian

MRS.utils.lorentzian(freq, freq0, area, hwhm, phase, offset, drift)

Lorentzian line-shape function

Parameters:

freq : float or float array

The frequencies for which the function is evaluated

freq0 : float

The center frequency of the function

area : float

hwhm: float :

Half-width at half-max

lowess

MRS.utils.lowess(x, w, x0, kernel=<function epanechnikov at 0x1091f3230>, l=1, robust=False)

Locally linear regression with the LOWESS algorithm.

Parameters:

x: float n-d array :

Values of x for which f(x) is known (e.g. measured). The shape of this is (n, j), where n is the number the dimensions of the and j is the number of distinct coordinates sampled.

w: float array :

The known values of f(x) at these points. This has shape (j,)

x0: float or float array. :

Values of x for which we estimate the value of f(x). This is either a single scalar value (only possible for the 1d case, in which case f(x0) is estimated for just that one value of x), or an array of shape (n, k).

kernel: callable :

A kernel function. {‘epanechnikov’, ‘tri_cube’}

l: float or float array with shape = x.shape :

The metric window size for the kernel

robust: bool :

Whether to apply the robustification procedure from [Cleveland79], page 831

Returns:

The function estimated at x0. :

Notes

The solution to this problem is given by equation 6.8 in Friedman, Hastie and Tibshirani (2008). The Elements of Statistical Learning (Chapter 6).

make_idx

MRS.utils.make_idx(f, lb, ub)

This is a little utility function to replace an oft-called set of operations

Parameters:

f : 1d array

A frequency axis along which we want to slice

lb : float

Defines the upper bound of slicing

ub : float

Defines the lower bound of slicing

Returns:

idx : a slice object

ols_matrix

MRS.utils.ols_matrix(A, norm_func=None)

Generate the matrix used to solve OLS regression.

Parameters:

A: float array :

The design matrix

norm: callable, optional

A normalization function to apply to the matrix, before extracting the OLS matrix.

See also

http

//en.wikipedia.org/wiki/Ordinary_least_squares#Estimation

is given by:

..math

\hat{eta} = (A' x A)^{-1} A' y

phase_correct_first

MRS.utils.phase_correct_first(spec, freq, k)

First order phase correction.

Parameters:

spec : float array

The spectrum to be corrected.

freq : float array

The frequency axis.

k : float

The slope of the phase correction as a function of frequency.

Returns:

The phase-corrected spectrum. :

Notes

[Keeler2005] Keeler, J (2005). Understanding NMR Spectroscopy, 2nd

edition. Wiley. Page 88

phase_correct_zero

MRS.utils.phase_correct_zero(spec, phi)

Correct the phases of a spectrum by phi radians

Parameters:

spec : float array of complex dtype

The spectrum to be corrected.

phi : float

Returns:

spec : float array

The phase corrected spectrum

Notes

[Keeler2005] Keeler, J (2005). Understanding NMR Spectroscopy, 2nd

edition. Wiley. Page 88.

ppm_idx

MRS.utils.ppm_idx(f_ppm, lb, ub)

Create a slice object according to the ppm scale

Parameters:

f_ppm : float array

The frequency bins (in the ppm scale). Assumed to be descending

lb,ub : float

The lower/upper bounds for indexing

Returns:

idx : slice object which can be used to index

ppm_to_freq

MRS.utils.ppm_to_freq(ppm, water_hz=0.0, water_ppm=4.7, hz_per_ppm=127.68)

Convert an array from chemical shift to Hz

rmse

MRS.utils.rmse(arr1, arr2)

The root of the mean of the squared error between arr1 and arr2

Parameters:

arr1, arr2 : ndarray

The two arrays to compare

Returns:

RMSE : float

Notes

The RMSE will be summarized in one number. That is, even if the two arrays are multi-dimensional, the error between them will be averaged over the entire array and then the sqrt will be derived.

tri_cube

MRS.utils.tri_cube(xx, idx)

The tri-cube kernel estimated for xx values at indices idx (zero elsewhere)

Parameters:

xx: float array :

Values of the function on which the kernel is computed. Typically, these are Euclidean distances from some point x0 (see do_kernel)

idx: tuple :

An indexing tuple pointing to the coordinates in xx for which the kernel value is estimated. Default: None (all points are used!)

Notes

This is equation 6.6 in FHT chapter 6

two_gaussian

MRS.utils.two_gaussian(freq, freq0_1, freq0_2, sigma1, sigma2, amp1, amp2, offset, drift)

A two-Gaussian model.

This is simply the sum of two gaussian functions in some part of the spectrum. Each individual gaussian has its own peak frequency, sigma, and amp, but they share common offset and drift parameters.

two_lorentzian

MRS.utils.two_lorentzian(freq, freq0_1, freq0_2, area1, area2, hwhm1, hwhm2, phase1, phase2, offset, drift)

A two-Lorentzian model.

This is simply the sum of two lorentzian functions in some part of the spectrum. Each individual Lorentzian has its own peak frequency, area, hwhm and phase, but they share common offset and drift parameters.

unit_vector

MRS.utils.unit_vector(arr, norm_func=<function l2_norm at 0x1091f3500>)

Normalize the array by a norm function (defaults to the l2_norm)

Parameters:

arr: ndarray :

norm_func: callable :

A function that is used here to normalize the array.

zero_pad

MRS.utils.zero_pad(ts, n_zeros)

Pad a nitime.TimeSeries class instance with n_zeros before and after the data

Parameters:ts : a nitime.TimeSeries class instance