nlsam.smoothing

Attributes

logger

Functions

`sh_smooth`(data, bvals, bvecs[, sh_order, ...])	Smooth the raw diffusion signal with spherical harmonics.
`_local_standard_deviation`(arr[, current_slice])	Standard deviation estimation from local patches.
`local_standard_deviation`(arr[, n_cores, verbose])	Standard deviation estimation from local patches.
`cart2sphere`(x, y, z)	Return angles for Cartesian 3D coordinates x, y, and z
`sph_harm_ind_list`(sh_order_max)	Returns the order (`l`) and phase_factor (`m`) of all the symmetric
`real_sh_descoteaux_from_index`(m_values, l_values, ...)	Compute real spherical harmonics.
`smooth_pinv`(B, L)	Regularized pseudo-inverse

Module Contents

nlsam.smoothing.logger

nlsam.smoothing.sh_smooth(data, bvals, bvecs, sh_order=4, b0_threshold=1.0, similarity_threshold=50, regul=0.006)

Smooth the raw diffusion signal with spherical harmonics.

datandarray: The diffusion data to smooth.
gtabgradient table object: Corresponding gradients table object to data.
b0_thresholdfloat, default 1.0: Threshold to consider this bval as a b=0 image.
sh_orderint, default 4: Order of the spherical harmonics to fit.
similarity_thresholdint, default 50: All bvalues such that |b_1 - b_2| < similarity_threshold will be considered as identical for smoothing purpose. Must be lower than 200.
regulfloat, default 0.006: Amount of regularization to apply to sh coefficients computation.

Returns:: pred_sig – The smoothed diffusion data, fitted through spherical harmonics.
Return type:: ndarray

nlsam.smoothing._local_standard_deviation(arr, current_slice=None)

Standard deviation estimation from local patches.

Estimates the local variance on patches by using convolutions to estimate the mean. This is the multiprocessed function.

Parameters:

arr (3D or 4D ndarray) – The array to be estimated
current_slice (numpy slice object) – current slice to evaluate if we are running in parallel

Returns:

sigma – Map of standard deviation of the noise.

Return type:

ndarray

nlsam.smoothing.local_standard_deviation(arr, n_cores=-1, verbose=False)

Standard deviation estimation from local patches.

The noise field is estimated by subtracting the data from it’s low pass filtered version, from which we then compute the variance on a local neighborhood basis.

Parameters:

arr (3D or 4D ndarray) – The array to be estimated
n_cores (int) – Number of cores to use for multiprocessing, default : all of them
verbose (int) – If True, prints progress information. A higher number prints more often

Returns:

sigma – Map of standard deviation of the noise.

Return type:

ndarray

nlsam.smoothing.cart2sphere(x, y, z)

Return angles for Cartesian 3D coordinates x, y, and z

This is the standard physics convention where theta is the inclination (polar) angle, and phi is the azimuth angle.

$0lethetamathrm{(theta)}lepi$ and $-pilephimathrm{(phi)}lepi$

Parameters:

x (array_like) – x coordinate in Cartesian space
y (array_like) – y coordinate in Cartesian space
z (array_like) – z coordinate

Returns:

r (array) – radius
theta (array) – inclination (polar) angle
phi (array) – azimuth angle

nlsam.smoothing.sph_harm_ind_list(sh_order_max)

Returns the order (l) and phase_factor (m) of all the symmetric spherical harmonics of order less then or equal to sh_order_max. The results, m_list and l_list are kx1 arrays, where k depends on sh_order_max.

Parameters:

sh_order_max (int) – The maximum order ($l$) of the spherical harmonic basis. Even int > 0, max order to return

Returns:

m_list (array of int) – phase factors ($m$) of even spherical harmonics
l_list (array of int) – orders ($l$) of even spherical harmonics

nlsam.smoothing.real_sh_descoteaux_from_index(m_values, l_values, theta, phi)

Compute real spherical harmonics.

The definition adopted here follows Descoteaux2007 where the real harmonic $Y_l^m$ is defined to be:

Y_l^m = \begin{cases} \sqrt{2} * \Im(Y_l^m) \; if m > 0 \\ Y^0_l \; if m = 0 \\ \sqrt{2} * \Re(Y_l^m) \; if m < 0 \\ \end{cases}

This may take scalar or array arguments. The inputs will be broadcast against each other.

Parameters:

m_values (array of int |m| <= l) – The phase factors ($m$) of the harmonics.
l_values (array of int l >= 0) – The orders ($l$) of the harmonics.
theta (float [0, pi]) – The polar (colatitudinal) coordinate.
phi (float [0, 2*pi]) – The azimuthal (longitudinal) coordinate.

Returns:

real_sh – The real harmonic $Y_l^m$ sampled at theta and phi.

Return type:

real float

nlsam.smoothing.smooth_pinv(B, L)

Regularized pseudo-inverse

Computes a regularized least square inverse of B

Parameters:

B (array_like (n, m)) – Matrix to be inverted
L (array_like (m,))

Returns:

inv – regularized least square inverse of B

Return type:

ndarray (m, n)

Notes

In the literature this inverse is often written $(B^{T}B+L^{2})^{-1}B^{T}$. However here this inverse is implemented using the pseudo-inverse because it is more numerically stable than the direct implementation of the matrix product.