`denoise`#

Module: `denoise.adaptive_soft_matching`#

adaptive_soft_matching(ima, fimau, fimao, sigma)

Adaptive Soft Coefficient Matching

Module: `denoise.denspeed`#

`add_padding_reflection`(arr, padding)
`correspond_indices`(dim_size, padding)
`determine_num_threads`(num_threads)	Determine the effective number of threads to be used for OpenMP calls
`nlmeans_3d`(arr[, mask, sigma, patch_radius, ...])	Non-local means for denoising 3D images
`remove_padding`(arr, padding)

Module: `denoise.enhancement_kernel`#

`EnhancementKernel`
`HemiSphere`([x, y, z, theta, phi, xyz, ...])	Points on the unit sphere.
`Sphere`([x, y, z, theta, phi, xyz, faces, edges])	Points on the unit sphere.
`ceil`(x, /)	Return the ceiling of x as an Integral.
`disperse_charges`(hemi, iters[, const])	Models electrostatic repulsion on the unit sphere
`get_sphere`([name])	provide triangulated spheres
`gettempdir`()	Returns tempfile.tempdir as str.

Module: `denoise.gibbs`#

gibbs_removal(vol[, slice_axis, n_points, ...])

Suppresses Gibbs ringing artefacts of images volumes.

Module: `denoise.localpca`#

`dimensionality_problem_message`(arr, ...)	Message about the number of samples being smaller than one less the
`create_patch_radius_arr`(arr, pr)	Create the patch radius array from the data to be denoised and the patch radius.
`compute_patch_size`(patch_radius)	Compute patch size from the patch radius.
`compute_num_samples`(patch_size)	Compute the number of samples as the dot product of the elements.
`compute_suggested_patch_radius`(arr, patch_size)	Compute the suggested patch radius.
`genpca`(arr[, sigma, mask, patch_radius, ...])	General function to perform PCA-based denoising of diffusion datasets.
`localpca`(arr[, sigma, mask, patch_radius, ...])	Performs local PCA denoising according to Manjon et al. [1]_.
`mppca`(arr[, mask, patch_radius, pca_method, ...])	Performs PCA-based denoising using the Marcenko-Pastur distribution [1]_.

Module: `denoise.nlmeans`#

nlmeans(arr, sigma[, mask, patch_radius, ...])

Non-local means for denoising 3D and 4D images

Module: `denoise.nlmeans_block`#

`firdn`(image, h)	Applies the filter given by the convolution kernel 'h' columnwise to 'image', then subsamples by 2.
`nlmeans_block`(image, mask, patch_radius, ...)	Non-Local Means Denoising Using Blockwise Averaging
`upfir`(image, h)	Upsamples the columns of the input image by 2, then applies the convolution kernel 'h' (again, columnwise).

Module: `denoise.noise_estimate`#

`piesno`(data, N[, alpha, l, itermax, eps, ...])	Probabilistic Identification and Estimation of Noise (PIESNO).
`estimate_sigma`(arr[, ...])	Standard deviation estimation from local patches

Module: `denoise.non_local_means`#

non_local_means(arr, sigma[, mask, ...])

Non-local means for denoising 3D and 4D images, using

Module: `denoise.patch2self`#

patch2self(data, bvals[, patch_radius, ...])

Patch2Self Denoiser.

Module: `denoise.pca_noise_estimate`#

PCA Based Local Noise Estimation#

`pca_noise_estimate`(data, gtab[, ...])	PCA based local noise estimation.
`warn`(message[, category, stacklevel, source])	Issue a warning, or maybe ignore it or raise an exception.

Module: `denoise.shift_twist_convolution`#

`convolve`(odfs_sh, kernel, sh_order_max[, ...])	Perform the shift-twist convolution with the ODF data and the lookup-table of the kernel.
`convolve_sf`(odfs_sf, kernel[, test_mode, ...])	Perform the shift-twist convolution with the ODF data and the lookup-table of the kernel.
`deprecated_params`(old_name[, new_name, ...])	Deprecate a renamed or removed function argument.
`determine_num_threads`(num_threads)	Determine the effective number of threads to be used for OpenMP calls
`sf_to_sh`(sf, sphere[, sh_order_max, ...])	Spherical function to spherical harmonics (SH).
`sh_to_sf`(sh, sphere[, sh_order_max, ...])	Spherical harmonics (SH) to spherical function (SF).

adaptive_soft_matching#

dipy.denoise.adaptive_soft_matching.adaptive_soft_matching(ima, fimau, fimao, sigma)#

Adaptive Soft Coefficient Matching

Combines two filtered 3D-images at different resolutions and the original image. Returns the resulting combined image.

Parameters#

ima : the original (not filtered) image fimau : 3D double array,

filtered image with optimized non-local means using a small block (suggested:3x3), which corresponds to a “high resolution” filter.

fimao3D double array,: filtered image with optimized non-local means using a small block (suggested:5x5), which corresponds to a “low resolution” filter.
sigmathe estimated standard deviation of the Gaussian random variables: that explain the rician noise. Note: In P. Coupe et al. the rician noise was simulated as sqrt((f+x)^2 + (y)^2) where f is the pixel value and x and y are independent realizations of a random variable with Normal distribution, with mean=0 and standard deviation=h

Returns#

fima3D double array: output denoised array which is of the same shape as that of the input

References#

[Coupe11]

Pierrick Coupe, Jose Manjon, Montserrat Robles, Louis Collins. “Multiresolution Non-Local Means Filter for 3D MR Image Denoising” IET Image Processing, Institution of Engineering and Technology, 2011

add_padding_reflection#

dipy.denoise.denspeed.add_padding_reflection(arr, padding)#

correspond_indices#

dipy.denoise.denspeed.correspond_indices(dim_size, padding)#

determine_num_threads#

dipy.denoise.denspeed.determine_num_threads(num_threads)#

Determine the effective number of threads to be used for OpenMP calls

For num_threads = None, - if the OMP_NUM_THREADS environment variable is set, return that value - otherwise, return the maximum number of cores retrieved by openmp.opm_get_num_procs().
For num_threads > 0, return this value.
For num_threads < 0, return the maximal number of threads minus |num_threads + 1|. In particular num_threads = -1 will use as many threads as there are available cores on the machine.
For num_threads = 0 a ValueError is raised.

Parameters#

num_threadsint or None: Desired number of threads to be used.

nlmeans_3d#

dipy.denoise.denspeed.nlmeans_3d(arr, mask=None, sigma=None, patch_radius=1, block_radius=5, rician=True, num_threads=None)#

Non-local means for denoising 3D images

Parameters#

arr3D ndarray: The array to be denoised

mask : 3D ndarray sigma : float or 3D array

standard deviation of the noise estimated from the data

patch_radiusint: patch size is 2 x patch_radius + 1. Default is 1.
block_radiusint: block size is 2 x block_radius + 1. Default is 5.
ricianboolean: If True the noise is estimated as Rician, otherwise Gaussian noise is assumed.
num_threadsint, optional: Number of threads to be used for OpenMP parallelization. If None (default) the value of OMP_NUM_THREADS environment variable is used if it is set, otherwise all available threads are used. If < 0 the maximal number of threads minus |num_threads + 1| is used (enter -1 to use as many threads as possible). 0 raises an error.

Returns#

denoised_arrndarray: the denoised arr which has the same shape as arr.

remove_padding#

dipy.denoise.denspeed.remove_padding(arr, padding)#

`EnhancementKernel`#

class dipy.denoise.enhancement_kernel.EnhancementKernel#

Bases: object

__init__()#

Compute a look-up table for the contextual enhancement kernel

Parameters#

D33float: Spatial diffusion
D44float: Angular diffusion
tfloat: Diffusion time
force_recomputeboolean: Always compute the look-up table even if it is available in cache. Default is False.
orientationsinteger or Sphere object: Specify the number of orientations to be used with electrostatic repulsion, or provide a Sphere object. The default sphere is ‘repulsion100’.
verboseboolean: Enable verbose mode.

References#

[Meesters2016_ISMRM] S. Meesters, G. Sanguinetti, E. Garyfallidis,: J. Portegies, R. Duits. (2016) Fast implementations of contextual PDE’s for HARDI data processing in DIPY. ISMRM 2016 conference.
[DuitsAndFranken_IJCV] R. Duits and E. Franken (2011) Left-invariant diffusions: on the space of positions and orientations and their application to crossing-preserving smoothing of HARDI images. International Journal of Computer Vision, 92:231-264.
[Portegies2015] J. Portegies, G. Sanguinetti, S. Meesters, and R. Duits.: (2015) New Approximation of a Scale Space Kernel on SE(3) and Applications in Neuroimaging. Fifth International Conference on Scale Space and Variational Methods in Computer Vision
[Portegies2015b] J. Portegies, R. Fick, G. Sanguinetti, S. Meesters,: G. Girard, and R. Duits. (2015) Improving Fiber Alignment in HARDI by Combining Contextual PDE flow with Constrained Spherical Deconvolution. PLoS One.

evaluate_kernel(x, y, r, v)#

Evaluate the kernel at position x relative to position y, with orientation r relative to orientation v.

Parameters#

x1D ndarray: Position x
y1D ndarray: Position y
r1D ndarray: Orientation r
v1D ndarray: Orientation v

Returns#

kernel_value : double

get_lookup_table()#: Return the computed look-up table.

get_orientations()#: Return the orientations.

get_sphere()#: Get the sphere corresponding with the orientations

`HemiSphere`#

class dipy.denoise.enhancement_kernel.HemiSphere(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None, tol=1e-05)#

Bases: Sphere

Points on the unit sphere.

A HemiSphere is similar to a Sphere but it takes antipodal symmetry into account. Antipodal symmetry means that point v on a HemiSphere is the same as the point -v. Duplicate points are discarded when constructing a HemiSphere (including antipodal duplicates). edges and faces are remapped to the remaining points as closely as possible.

The HemiSphere can be constructed using one of three conventions:

HemiSphere(x, y, z)
HemiSphere(xyz=xyz)
HemiSphere(theta=theta, phi=phi)

Parameters#

x, y, z1-D array_like: Vertices as x-y-z coordinates.
theta, phi1-D array_like: Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively.
xyz(N, 3) ndarray: Vertices as x-y-z coordinates.
faces(N, 3) ndarray: Indices into vertices that form triangular faces. If unspecified, the faces are computed using a Delaunay triangulation.
edges(N, 2) ndarray: Edges between vertices. If unspecified, the edges are derived from the faces.
tolfloat: Angle in degrees. Vertices that are less than tol degrees apart are treated as duplicates.

`Sphere`#

class dipy.denoise.enhancement_kernel.Sphere(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)#

Bases: object

Points on the unit sphere.

The sphere can be constructed using one of three conventions:

Sphere(x, y, z)
Sphere(xyz=xyz)
Sphere(theta=theta, phi=phi)

Parameters#

x, y, z1-D array_like: Vertices as x-y-z coordinates.
theta, phi1-D array_like: Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively.
xyz(N, 3) ndarray: Vertices as x-y-z coordinates.
faces(N, 3) ndarray: Indices into vertices that form triangular faces. If unspecified, the faces are computed using a Delaunay triangulation.
edges(N, 2) ndarray: Edges between vertices. If unspecified, the edges are derived from the faces.

__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)#

edges()#

faces()#

find_closest(xyz)#

Find the index of the vertex in the Sphere closest to the input vector

Parameters#

xyzarray-like, 3 elements: A unit vector

Returns#

idxint: The index into the Sphere.vertices array that gives the closest vertex (in angle).

subdivide(n=1)#

Subdivides each face of the sphere into four new faces.

New vertices are created at a, b, and c. Then each face [x, y, z] is divided into faces [x, a, c], [y, a, b], [z, b, c], and [a, b, c].

      y
      /\
     /  \
   a/____\b
   /\    /\
  /  \  /  \
 /____\/____\
x      c     z

Parameters#

nint, optional: The number of subdivisions to perform.

Returns#

new_sphereSphere: The subdivided sphere.

vertices()#

property x#

property y#

property z#

ceil#

dipy.denoise.enhancement_kernel.ceil(x, /)#

Return the ceiling of x as an Integral.

This is the smallest integer >= x.

disperse_charges#

dipy.denoise.enhancement_kernel.disperse_charges(hemi, iters, const=0.2)#

Models electrostatic repulsion on the unit sphere

Places charges on a sphere and simulates the repulsive forces felt by each one. Allows the charges to move for some number of iterations and returns their final location as well as the total potential of the system at each step.

Parameters#

hemiHemiSphere: Points on a unit sphere.
itersint: Number of iterations to run.
constfloat: Using a smaller const could provide a more accurate result, but will need more iterations to converge.

Returns#

hemiHemiSphere: Distributed points on a unit sphere.
potentialndarray: The electrostatic potential at each iteration. This can be useful to check if the repulsion converged to a minimum.

Notes#

This function is meant to be used with diffusion imaging so antipodal symmetry is assumed. Therefore, each charge must not only be unique, but if there is a charge at +x, there cannot be a charge at -x. These are treated as the same location and because the distance between the two charges will be zero, the result will be unstable.

get_sphere#

dipy.denoise.enhancement_kernel.get_sphere(name='symmetric362')#

provide triangulated spheres

Parameters#

namestr: which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’

Returns#

sphere : a dipy.core.sphere.Sphere class instance

Examples#

>>> import numpy as np
>>> from dipy.data import get_sphere
>>> sphere = get_sphere('symmetric362')
>>> verts, faces = sphere.vertices, sphere.faces
>>> verts.shape == (362, 3)
True
>>> faces.shape == (720, 3)
True
>>> verts, faces = get_sphere('not a sphere name') 
Traceback (most recent call last):
    ...
DataError: No sphere called "not a sphere name"

gettempdir#

dipy.denoise.enhancement_kernel.gettempdir()#: Returns tempfile.tempdir as str.

gibbs_removal#

dipy.denoise.gibbs.gibbs_removal(vol, slice_axis=2, n_points=3, inplace=True, num_processes=1)#

Suppresses Gibbs ringing artefacts of images volumes.

Parameters#

volndarray ([X, Y]), ([X, Y, Z]) or ([X, Y, Z, g]): Matrix containing one volume (3D) or multiple (4D) volumes of images.
slice_axisint (0, 1, or 2): Data axis corresponding to the number of acquired slices. Default is set to the third axis.
n_pointsint, optional: Number of neighbour points to access local TV (see note). Default is set to 3.
inplacebool, optional: If True, the input data is replaced with results. Otherwise, returns a new array. Default is set to True.
num_processesint or None, optional: Split the calculation to a pool of children processes. This only applies to 3D or 4D data arrays. Default is 1. If < 0 the maximal number of cores minus num_processes + 1 is used (enter -1 to use as many cores as possible). 0 raises an error.

Returns#

volndarray ([X, Y]), ([X, Y, Z]) or ([X, Y, Z, g]): Matrix containing one volume (3D) or multiple (4D) volumes of corrected images.

Notes#

For 4D matrix last element should always correspond to the number of diffusion gradient directions.

References#

Please cite the following articles .. [1] Neto Henriques, R., 2018. Advanced Methods for Diffusion MRI Data

Analysis and their Application to the Healthy Ageing Brain (Doctoral thesis). https://doi.org/10.17863/CAM.29356

dimensionality_problem_message#

dipy.denoise.localpca.dimensionality_problem_message(arr, num_samples, spr)#

Message about the number of samples being smaller than one less the

dimensionality of the data to be denoised.

arrndarray: Data to be denoised.
num_samplesint: Number of samples.
sprint: Suggested patch radius.

.

str: Message.

create_patch_radius_arr#

dipy.denoise.localpca.create_patch_radius_arr(arr, pr)#

Create the patch radius array from the data to be denoised and the patch radius.

Parameters#

arrndarray: Data to be denoised.
print or ndarray: Patch radius.

Returns#

patch_radiusndarray: Number of samples.

compute_patch_size#

dipy.denoise.localpca.compute_patch_size(patch_radius)#

Compute patch size from the patch radius.

it is twice the radius plus one.

Parameters#

patch_radiusndarray: Patch radius.

Returns#

int: Number of samples.

compute_num_samples#

dipy.denoise.localpca.compute_num_samples(patch_size)#

Compute the number of samples as the dot product of the elements.

Parameters#

patch_sizendarray: Patch size.

Returns#

int: Number of samples.

compute_suggested_patch_radius#

dipy.denoise.localpca.compute_suggested_patch_radius(arr, patch_size)#

Compute the suggested patch radius.

Parameters#

arrndarray: Data to be denoised.
patch_sizendarray: Patch size.

Returns#

int: Suggested patch radius.

genpca#

dipy.denoise.localpca.genpca(arr, sigma=None, mask=None, patch_radius=2, pca_method='eig', tau_factor=None, return_sigma=False, out_dtype=None, suppress_warning=False)#

General function to perform PCA-based denoising of diffusion datasets.

Parameters#

arr4D array

Array of data to be denoised. The dimensions are (X, Y, Z, N), where N are the diffusion gradient directions. The first 3 dimension must have size >= 2 * patch_radius + 1 or size = 1.

sigmafloat or 3D array (optional)

Standard deviation of the noise estimated from the data. If no sigma is given, this will be estimated based on random matrix theory [1]_,[2]_

mask3D boolean array (optional)

A mask with voxels that are true inside the brain and false outside of it. The function denoises within the true part and returns zeros outside of those voxels.

patch_radiusint or 1D array (optional)

The radius of the local patch to be taken around each voxel (in voxels). E.g. patch_radius=2 gives 5x5x5 patches.

pca_method‘eig’ or ‘svd’ (optional)

Use either eigenvalue decomposition (eig) or singular value decomposition (svd) for principal component analysis. The default method is ‘eig’ which is faster. However, occasionally ‘svd’ might be more accurate.

tau_factorfloat (optional)

Thresholding of PCA eigenvalues is done by nulling out eigenvalues that are smaller than:

\[\tau = (\tau_{factor} \sigma)^2\]

tau_{factor} can be set to a predefined values (e.g. tau_{factor} = 2.3 [3]_), or automatically calculated using random matrix theory (in case that tau_{factor} is set to None).

return_sigmabool (optional)

If true, the Standard deviation of the noise will be returned.

out_dtypestr or dtype (optional)

The dtype for the output array. Default: output has the same dtype as the input.

suppress_warningbool (optional)

If true, suppress warning caused by patch_size < arr.shape[-1].

Returns#

denoised_arr4D array: This is the denoised array of the same size as that of the input data, clipped to non-negative values.

References#

localpca#

dipy.denoise.localpca.localpca(arr, sigma=None, mask=None, patch_radius=2, gtab=None, patch_radius_sigma=1, pca_method='eig', tau_factor=2.3, return_sigma=False, correct_bias=True, out_dtype=None, suppress_warning=False)#

Performs local PCA denoising according to Manjon et al. [1]_.

Parameters#

arr4D array

Array of data to be denoised. The dimensions are (X, Y, Z, N), where N are the diffusion gradient directions.

sigmafloat or 3D array (optional)

Standard deviation of the noise estimated from the data. If not given, calculate using method in [1]_.

mask3D boolean array (optional)

A mask with voxels that are true inside the brain and false outside of it. The function denoises within the true part and returns zeros outside of those voxels.

patch_radiusint or 1D array (optional)

The radius of the local patch to be taken around each voxel (in voxels). E.g. patch_radius=2 gives 5x5x5 patches.

gtab: gradient table object (optional if sigma is provided)

gradient information for the data gives us the bvals and bvecs of diffusion data, which is needed to calculate noise level if sigma is not provided.

patch_radius_sigmaint (optional)

The radius of the local patch to be taken around each voxel (in voxels) for estimating sigma. E.g. patch_radius_sigma=2 gives 5x5x5 patches.

pca_method‘eig’ or ‘svd’ (optional)

tau_factorfloat (optional)

Thresholding of PCA eigenvalues is done by nulling out eigenvalues that are smaller than:

\[\tau = (\tau_{factor} \sigma)^2\]

tau_{factor} can be change to adjust the relationship between the noise standard deviation and the threshold tau. If tau_{factor} is set to None, it will be automatically calculated using the Marcenko-Pastur distribution [2]_. Default: 2.3 according to [1]_.

return_sigmabool (optional)

If true, a noise standard deviation estimate based on the Marcenko-Pastur distribution is returned [2]_.

correct_biasbool (optional)

Whether to correct for bias due to Rician noise. This is an implementation of equation 8 in [1]_.

out_dtypestr or dtype (optional)

The dtype for the output array. Default: output has the same dtype as the input.

suppress_warningbool (optional)

If true, suppress warning caused by patch_size < arr.shape[-1].

Returns#

denoised_arr4D array: This is the denoised array of the same size as that of the input data, clipped to non-negative values

References#

mppca#

dipy.denoise.localpca.mppca(arr, mask=None, patch_radius=2, pca_method='eig', return_sigma=False, out_dtype=None, suppress_warning=False)#

Performs PCA-based denoising using the Marcenko-Pastur distribution [1]_.

Parameters#

arr4D array: Array of data to be denoised. The dimensions are (X, Y, Z, N), where N are the diffusion gradient directions.
mask3D boolean array (optional): A mask with voxels that are true inside the brain and false outside of it. The function denoises within the true part and returns zeros outside of those voxels.
patch_radiusint or 1D array (optional): The radius of the local patch to be taken around each voxel (in voxels). E.g. patch_radius=2 gives 5x5x5 patches.
pca_method‘eig’ or ‘svd’ (optional): Use either eigenvalue decomposition (eig) or singular value decomposition (svd) for principal component analysis. The default method is ‘eig’ which is faster. However, occasionally ‘svd’ might be more accurate.
return_sigmabool (optional): If true, a noise standard deviation estimate based on the Marcenko-Pastur distribution is returned [2]_.
out_dtypestr or dtype (optional): The dtype for the output array. Default: output has the same dtype as the input.
suppress_warningbool (optional): If true, suppress warning caused by patch_size < arr.shape[-1].

Returns#

denoised_arr4D array: This is the denoised array of the same size as that of the input data, clipped to non-negative values
sigma3D array (when return_sigma=True): Estimate of the spatial varying standard deviation of the noise

References#

nlmeans#

dipy.denoise.nlmeans.nlmeans(arr, sigma, mask=None, patch_radius=1, block_radius=5, rician=True, num_threads=None)#

Non-local means for denoising 3D and 4D images

Parameters#

arr3D or 4D ndarray: The array to be denoised

mask : 3D ndarray sigma : float or 3D array

standard deviation of the noise estimated from the data

patch_radiusint: patch size is 2 x patch_radius + 1. Default is 1.
block_radiusint: block size is 2 x block_radius + 1. Default is 5.
ricianboolean: If True the noise is estimated as Rician, otherwise Gaussian noise is assumed.
num_threadsint, optional: Number of threads to be used for OpenMP parallelization. If None (default) the value of OMP_NUM_THREADS environment variable is used if it is set, otherwise all available threads are used. If < 0 the maximal number of threads minus |num_threads + 1| is used (enter -1 to use as many threads as possible). 0 raises an error.

Returns#

denoised_arrndarray: the denoised arr which has the same shape as arr.

References#

[Descoteaux08]

Descoteaux, Maxime and Wiest-Daesslé, Nicolas and Prima, Sylvain and Barillot, Christian and Deriche, Rachid Impact of Rician Adapted Non-Local Means Filtering on HARDI, MICCAI 2008

firdn#

dipy.denoise.nlmeans_block.firdn(image, h)#

Applies the filter given by the convolution kernel ‘h’ columnwise to ‘image’, then subsamples by 2. This is a special case of the matlab’s ‘upfirdn’ function, ported to python. Returns the filtered image.

Parameters#

image: 2D array of doubles: the input image to be filtered
h: double array: the convolution kernel

nlmeans_block#

dipy.denoise.nlmeans_block.nlmeans_block(image, mask, patch_radius, block_radius, h, rician)#

Non-Local Means Denoising Using Blockwise Averaging

Parameters#

image3D array of doubles: the input image, corrupted with rician noise
mask3D array of doubles: the input mask
patch_radiusint: similar patches in the non-local means are searched for locally, inside a cube of side 2*v+1 centered at each voxel of interest.
block_radiusint: the size of the block to be used (2*f+1)x(2*f+1)x(2*f+1) in the blockwise non-local means implementation (the Coupe’s proposal).
hdouble: the estimated amount of rician noise in the input image: in P. Coupe et al. the rician noise was simulated as sqrt((f+x)^2 + (y)^2) where f is the pixel value and x and y are independent realizations of a random variable with Normal distribution, with mean=0 and standard deviation=h
ricianboolean: If True the noise is estimated as Rician, otherwise Gaussian noise is assumed.

Returns#

fima: 3D double array: the denoised output which has the same shape as input image.

References#

[1] P. Coupe, P. Yger, S. Prima, P. Hellier, C. Kervrann, C. Barillot,: “An Optimized Blockwise Non Local Means Denoising Filter for 3D Magnetic Resonance Images” IEEE Transactions on Medical Imaging, 27(4):425-441, 2008
[2] Pierrick Coupe, Jose Manjon, Montserrat Robles, Louis Collins.: “Multiresolution Non-Local Means Filter for 3D MR Image Denoising” IET Image Processing, Institution of Engineering and Technology, 2011

upfir#

dipy.denoise.nlmeans_block.upfir(image, h)#

Upsamples the columns of the input image by 2, then applies the convolution kernel ‘h’ (again, columnwise). This is a special case of the matlab’s ‘upfirdn’ function, ported to python. Returns the filtered image.

Parameters#

image: 2D array of doubles: the input image to be filtered
h: double array: the convolution kernel

piesno#

dipy.denoise.noise_estimate.piesno(data, N, alpha=0.01, l=100, itermax=100, eps=1e-05, return_mask=False)#

Probabilistic Identification and Estimation of Noise (PIESNO).

Parameters#

datandarray: The magnitude signals to analyse. The last dimension must contain the same realisation of the volume, such as dMRI or fMRI data.
Nint: The number of phase array coils of the MRI scanner. If your scanner does a SENSE reconstruction, ALWAYS use N=1, as the noise profile is always Rician. If your scanner does a GRAPPA reconstruction, set N as the number of phase array coils.
alphafloat: Probabilistic estimation threshold for the gamma function.
lint: number of initial estimates for sigma to try.
itermaxint: Maximum number of iterations to execute if convergence is not reached.
epsfloat: Tolerance for the convergence criterion. Convergence is reached if two subsequent estimates are smaller than eps.
return_maskbool: If True, return a mask identifying all the pure noise voxel that were found.

Returns#

sigmafloat: The estimated standard deviation of the gaussian noise.
maskndarray (optional): A boolean mask indicating the voxels identified as pure noise.

Notes#

This function assumes two things : 1. The data has a noisy, non-masked background and 2. The data is a repetition of the same measurements along the last axis, i.e. dMRI or fMRI data, not structural data like T1/T2.

This function processes the data slice by slice, as originally designed in the paper. Use it to get a slice by slice estimation of the noise, as in spinal cord imaging for example.

References#

“Probabilistic Identification and Estimation of Noise (PIESNO): A self-consistent approach and its applications in MRI.” Journal of Magnetic Resonance 2009; 199: 94-103.

“A signal transformational framework for breaking the noise floor and its applications in MRI.” Journal of Magnetic Resonance 2009; 197: 108-119.

estimate_sigma#

dipy.denoise.noise_estimate.estimate_sigma(arr, disable_background_masking=False, N=0)#

Standard deviation estimation from local patches

Parameters#

arr3D or 4D ndarray: The array to be estimated
disable_background_maskingbool, default False: If True, uses all voxels for the estimation, otherwise, only non-zeros voxels are used. Useful if the background is masked by the scanner.
Nint, default 0: Number of coils of the receiver array. Use N = 1 in case of a SENSE reconstruction (Philips scanners) or the number of coils for a GRAPPA reconstruction (Siemens and GE). Use 0 to disable the correction factor, as for example if the noise is Gaussian distributed. See [1] for more information.

Returns#

sigmandarray: standard deviation of the noise, one estimation per volume.

Notes#

This function is the same as manually taking the standard deviation of the background and gives one value for the whole 3D array. It also includes the coil-dependent correction factor of Koay 2006 (see [1]_, equation 18) with theta = 0. Since this function was introduced in [2]_ for T1 imaging, it is expected to perform ok on diffusion MRI data, but might oversmooth some regions and leave others un-denoised for spatially varying noise profiles. Consider using piesno() to estimate sigma instead if visual inaccuracies are apparent in the denoised result.

References#

scheme for signal extraction from noisy magnitude MR signals. Journal of Magnetic Resonance), 179(2), 317-22.

C., 2008. An optimized blockwise nonlocal means denoising filter for 3-D magnetic resonance images, IEEE Trans. Med. Imaging 27, 425-41.

non_local_means#

dipy.denoise.non_local_means.non_local_means(arr, sigma, mask=None, patch_radius=1, block_radius=5, rician=True)#

Non-local means for denoising 3D and 4D images, using: blockwise averaging approach

Parameters#

arr3D or 4D ndarray: The array to be denoised

mask : 3D ndarray sigma : float

standard deviation of the noise estimated from the data

patch_radiusint: patch size is 2 x patch_radius + 1. Default is 1.
block_radiusint: block size is 2 x block_radius + 1. Default is 5.
ricianboolean: If True the noise is estimated as Rician, otherwise Gaussian noise is assumed.

Returns#

denoised_arrndarray: the denoised arr which has the same shape as arr.

References#

[Coupe08]

P. Coupe, P. Yger, S. Prima, P. Hellier, C. Kervrann, C. Barillot, An Optimized Blockwise Non Local Means Denoising Filter for 3D Magnetic Resonance Images, IEEE Transactions on Medical Imaging, 27(4):425-441, 2008

[Coupe11]

Pierrick Coupe, Jose Manjon, Montserrat Robles, Louis Collins. Adaptive Multiresolution Non-Local Means Filter for 3D MR Image Denoising IET Image Processing, Institution of Engineering and Technology, 2011

patch2self#

dipy.denoise.patch2self.patch2self(data, bvals, patch_radius=(0, 0, 0), model='ols', b0_threshold=50, out_dtype=None, alpha=1.0, verbose=False, b0_denoising=True, clip_negative_vals=False, shift_intensity=True)#

Patch2Self Denoiser.

Parameters#

datandarray: The 4D noisy DWI data to be denoised.
bvals1D array: Array of the bvals from the DWI acquisition
patch_radiusint or 1D array, optional: The radius of the local patch to be taken around each voxel (in voxels). Default: 0 (denoise in blocks of 1x1x1 voxels).
modelstring, or initialized linear model object.: This will determine the algorithm used to solve the set of linear equations underlying this model. If it is a string it needs to be one of the following: {‘ols’, ‘ridge’, ‘lasso’}. Otherwise, it can be an object that inherits from dipy.optimize.SKLearnLinearSolver or an object with a similar interface from Scikit-Learn: sklearn.linear_model.LinearRegression, sklearn.linear_model.Lasso or sklearn.linear_model.Ridge and other objects that inherit from sklearn.base.RegressorMixin. Default: ‘ols’.
b0_thresholdint, optional: Threshold for considering volumes as b0.
out_dtypestr or dtype, optional: The dtype for the output array. Default: output has the same dtype as the input.
alphafloat, optional: Regularization parameter only for ridge regression model.
verbosebool, optional: Show progress of Patch2Self and time taken.
b0_denoisingbool, optional: Skips denoising b0 volumes if set to False.
clip_negative_valsbool, optional: Sets negative values after denoising to 0 using np.clip.
shift_intensitybool, optional: Shifts the distribution of intensities per volume to give non-negative values

Returns#

denoised arrayndarray: This is the denoised array of the same size as that of the input data, clipped to non-negative values.

References#

[Fadnavis20] S. Fadnavis, J. Batson, E. Garyfallidis, Patch2Self:: Denoising Diffusion MRI with Self-supervised Learning, Advances in Neural Information Processing Systems 33 (2020)

pca_noise_estimate#

dipy.denoise.pca_noise_estimate.pca_noise_estimate(data, gtab, patch_radius=1, correct_bias=True, smooth=2, images_as_samples=False)#

PCA based local noise estimation.

Parameters#

data: 4D array: the input dMRI data. The first 3 dimension must have size >= 2 * patch_radius + 1 or size = 1.
gtab: gradient table object: gradient information for the data gives us the bvals and bvecs of diffusion data, which is needed here to select between the noise estimation methods.
patch_radiusint: The radius of the local patch to be taken around each voxel (in voxels). Default: 1 (estimate noise in blocks of 3x3x3 voxels).
correct_biasbool: Whether to correct for bias due to Rician noise. This is an implementation of equation 8 in [1]_.
smoothint: Radius of a Gaussian smoothing filter to apply to the noise estimate before returning. Default: 2.
image_as_samplesbool, optional: Whether to use images as rows (samples) for PCA (algorithm in [1]_) or to use images as columns (features).

Returns#

sigma_corr: 3D array: The local noise standard deviation estimate.

Notes#

In [1]_, images are used as samples, so voxels are features, therefore eigenvectors are image-shaped. However, [1]_ is not clear on how to use these eigenvectors to determine the noise level, so here eigenvalues (variance over samples explained by eigenvectors) are used to scale the eigenvectors. Use images_as_samples=True to use this algorithm. Alternatively, voxels can be used as samples using images_as_samples=False. This is not the canonical algorithm of [1]_.

References#

warn#

dipy.denoise.pca_noise_estimate.warn(message, category=None, stacklevel=1, source=None)#: Issue a warning, or maybe ignore it or raise an exception.

convolve#

dipy.denoise.shift_twist_convolution.convolve(odfs_sh, kernel, sh_order_max, test_mode=False, num_threads=None, normalize=True)#

Perform the shift-twist convolution with the ODF data and the lookup-table of the kernel.

Parameters#

odfsarray of double: The ODF data in spherical harmonics format
kernelarray of double: The 5D lookup table
sh_order_maxinteger: Maximal spherical harmonics order (l)
test_modeboolean: Reduced convolution in one direction only for testing
num_threadsint, optional: Number of threads to be used for OpenMP parallelization. If None (default) the value of OMP_NUM_THREADS environment variable is used if it is set, otherwise all available threads are used. If < 0 the maximal number of threads minus |num_threads + 1| is used (enter -1 to use as many threads as possible). 0 raises an error.
normalizeboolean: Apply max-normalization to the output such that its value range matches the input ODF data.

Returns#

outputarray of double: The ODF data after convolution enhancement in spherical harmonics format

References#

[Meesters2016_ISMRM] S. Meesters, G. Sanguinetti, E. Garyfallidis,: J. Portegies, R. Duits. (2016) Fast implementations of contextual PDE’s for HARDI data processing in DIPY. ISMRM 2016 conference.
[DuitsAndFranken_IJCV] R. Duits and E. Franken (2011) Left-invariant diffusions: on the space of positions and orientations and their application to crossing-preserving smoothing of HARDI images. International Journal of Computer Vision, 92:231-264.
[Portegies2015] J. Portegies, G. Sanguinetti, S. Meesters, and R. Duits.: (2015) New Approximation of a Scale Space Kernel on SE(3) and Applications in Neuroimaging. Fifth International Conference on Scale Space and Variational Methods in Computer Vision
[Portegies2015b] J. Portegies, R. Fick, G. Sanguinetti, S. Meesters, G.Girard,: and R. Duits. (2015) Improving Fiber Alignment in HARDI by Combining Contextual PDE flow with Constrained Spherical Deconvolution. PLoS One.

convolve_sf#

dipy.denoise.shift_twist_convolution.convolve_sf(odfs_sf, kernel, test_mode=False, num_threads=None, normalize=True)#

Perform the shift-twist convolution with the ODF data and the lookup-table of the kernel.

Parameters#

odfsarray of double: The ODF data sampled on a sphere
kernelarray of double: The 5D lookup table
test_modeboolean: Reduced convolution in one direction only for testing
num_threadsint, optional: Number of threads to be used for OpenMP parallelization. If None (default) the value of OMP_NUM_THREADS environment variable is used if it is set, otherwise all available threads are used. If < 0 the maximal number of threads minus |num_threads + 1| is used (enter -1 to use as many threads as possible). 0 raises an error.
normalizeboolean: Apply max-normalization to the output such that its value range matches the input ODF data.

Returns#

outputarray of double: The ODF data after convolution enhancement, sampled on a sphere

deprecated_params#

dipy.denoise.shift_twist_convolution.deprecated_params(old_name, new_name=None, since='', until='', version_comparator=<function cmp_pkg_version>, arg_in_kwargs=False, warn_class=<class 'dipy.utils.deprecator.ArgsDeprecationWarning'>, error_class=<class 'dipy.utils.deprecator.ExpiredDeprecationError'>, alternative='')#

Deprecate a renamed or removed function argument.

The decorator assumes that the argument with the old_name was removed from the function signature and the new_name replaced it at the same position in the signature. If the old_name argument is given when calling the decorated function the decorator will catch it and issue a deprecation warning and pass it on as new_name argument.

Parameters#

old_namestr or list/tuple thereof: The old name of the argument.
new_namestr or list/tuple thereof or None, optional: The new name of the argument. Set this to None to remove the argument old_name instead of renaming it.
sincestr or number or list/tuple thereof, optional: The release at which the old argument became deprecated.
untilstr or number or list/tuple thereof, optional: Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.
version_comparatorcallable: Callable accepting string as argument, and return 1 if string represents a higher version than encoded in the version_comparator, 0 if the version is equal, and -1 if the version is lower. For example, the version_comparator may compare the input version string to the current package version string.
arg_in_kwargsbool or list/tuple thereof, optional: If the argument is not a named argument (for example it was meant to be consumed by **kwargs) set this to True. Otherwise the decorator will throw an Exception if the new_name cannot be found in the signature of the decorated function. Default is False.
warn_classwarning, optional: Warning to be issued.
error_classException, optional: Error to be issued
alternativestr, optional: An alternative function or class name that the user may use in place of the deprecated object if new_name is None. The deprecation warning will tell the user about this alternative if provided.

Raises#

TypeError: If the new argument name cannot be found in the function signature and arg_in_kwargs was False or if it is used to deprecate the name of the *args-, **kwargs-like arguments. At runtime such an Error is raised if both the new_name and old_name were specified when calling the function and “relax=False”.

Notes#

This function is based on the Astropy (major modification). astropy/astropy. See COPYING file distributed along with the astropy package for the copyright and license terms.

Examples#

The deprecation warnings are not shown in the following examples. To deprecate a positional or keyword argument:: >>> from dipy.utils.deprecator import deprecated_params >>> @deprecated_params(‘sig’, ‘sigma’, ‘0.3’) … def test(sigma): … return sigma >>> test(2) 2 >>> test(sigma=2) 2 >>> test(sig=2) # doctest: +SKIP 2

It is also possible to replace multiple arguments. The old_name, new_name and since have to be tuple or list and contain the same number of entries:: >>> @deprecated_params([‘a’, ‘b’], [‘alpha’, ‘beta’], … [‘0.2’, 0.4]) … def test(alpha, beta): … return alpha, beta >>> test(a=2, b=3) # doctest: +SKIP (2, 3)

determine_num_threads#

dipy.denoise.shift_twist_convolution.determine_num_threads(num_threads)#

Determine the effective number of threads to be used for OpenMP calls

For num_threads = None, - if the OMP_NUM_THREADS environment variable is set, return that value - otherwise, return the maximum number of cores retrieved by openmp.opm_get_num_procs().
For num_threads > 0, return this value.
For num_threads < 0, return the maximal number of threads minus |num_threads + 1|. In particular num_threads = -1 will use as many threads as there are available cores on the machine.
For num_threads = 0 a ValueError is raised.

Parameters#

num_threadsint or None: Desired number of threads to be used.

sf_to_sh#

dipy.denoise.shift_twist_convolution.sf_to_sh(sf, sphere, sh_order_max=4, basis_type=None, full_basis=False, legacy=True, smooth=0.0)#

Spherical function to spherical harmonics (SH).

Parameters#

sfndarray: Values of a function on the given sphere.
sphereSphere: The points on which the sf is defined.
sh_order_maxint, optional: Maximum SH order (l) in the SH fit. For sh_order_max, there will be (sh_order_max + 1) * (sh_order_max + 2) / 2 SH coefficients for a symmetric basis and (sh_order_max + 1) * (sh_order_max + 1) coefficients for a full SH basis.
basis_type{None, ‘tournier07’, ‘descoteaux07’}, optional: None for the default DIPY basis, tournier07 for the Tournier 2007 [2]_[3]_ basis, descoteaux07 for the Descoteaux 2007 [1]_ basis, (None defaults to descoteaux07).
full_basis: bool, optional: True for using a SH basis containing even and odd order SH functions. False for using a SH basis consisting only of even order SH functions.
legacy: bool, optional: True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 implementations.
smoothfloat, optional: Lambda-regularization in the SH fit.

Returns#

shndarray: SH coefficients representing the input function.

References#

sh_to_sf#

dipy.denoise.shift_twist_convolution.sh_to_sf(sh, sphere, sh_order_max=4, basis_type=None, full_basis=False, legacy=True)#

Spherical harmonics (SH) to spherical function (SF).

Parameters#

shndarray: SH coefficients representing a spherical function.
sphereSphere: The points on which to sample the spherical function.
sh_order_maxint, optional: Maximum SH order (l) in the SH fit. For sh_order_max, there will be (sh_order_max + 1) * (sh_order_max + 2) / 2 SH coefficients for a symmetric basis and (sh_order_max + 1) * (sh_order_max + 1) coefficients for a full SH basis.
basis_type{None, ‘tournier07’, ‘descoteaux07’}, optional: None for the default DIPY basis, tournier07 for the Tournier 2007 [2]_[3]_ basis, descoteaux07 for the Descoteaux 2007 [1]_ basis, (None defaults to descoteaux07).
full_basis: bool, optional: True to use a SH basis containing even and odd order SH functions. Else, use a SH basis consisting only of even order SH functions.
legacy: bool, optional: True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 implementations.

Returns#

sfndarray: Spherical function values on the sphere.

denoise#

Module: denoise.adaptive_soft_matching#

Module: denoise.denspeed#

Module: denoise.enhancement_kernel#

Module: denoise.gibbs#

Module: denoise.localpca#

Module: denoise.nlmeans#

Module: denoise.nlmeans_block#

Module: denoise.noise_estimate#

Module: denoise.non_local_means#

Module: denoise.patch2self#

Module: denoise.pca_noise_estimate#

PCA Based Local Noise Estimation#

Module: denoise.shift_twist_convolution#

adaptive_soft_matching#

Parameters#

Returns#

References#

add_padding_reflection#

correspond_indices#

determine_num_threads#

Parameters#

nlmeans_3d#

Parameters#

Returns#

remove_padding#

EnhancementKernel#

Parameters#

References#

Parameters#

Returns#

HemiSphere#

Parameters#

See Also#

Parameters#

Returns#

Sphere#

Parameters#

Parameters#

Returns#

Parameters#

Returns#

ceil#

disperse_charges#

Parameters#

Returns#

Notes#

get_sphere#

Parameters#

Returns#

Examples#

gettempdir#

gibbs_removal#

Parameters#

Returns#

Notes#

References#

dimensionality_problem_message#

create_patch_radius_arr#

Parameters#

Returns#

compute_patch_size#

Parameters#

Returns#

compute_num_samples#

Parameters#

Returns#

compute_suggested_patch_radius#

Parameters#

Returns#

genpca#

Parameters#

Returns#

References#

localpca#

Parameters#

Returns#

References#

mppca#

Parameters#

`denoise`#

Module: `denoise.adaptive_soft_matching`#

Module: `denoise.denspeed`#

Module: `denoise.enhancement_kernel`#

Module: `denoise.gibbs`#

Module: `denoise.localpca`#

Module: `denoise.nlmeans`#

Module: `denoise.nlmeans_block`#

Module: `denoise.noise_estimate`#

Module: `denoise.non_local_means`#

Module: `denoise.patch2self`#

Module: `denoise.pca_noise_estimate`#

Module: `denoise.shift_twist_convolution`#

`EnhancementKernel`#

`HemiSphere`#

`Sphere`#