denoise

Module: denoise.adaptive_soft_matching

adaptive_soft_matching(ima, fimau, fimao, sigma)

Adaptive Soft Coefficient Matching

Module: denoise.gibbs

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

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 dimensionality of the data to be denoised.
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, ...])	Performs local PCA denoising.
mppca(arr, *[, mask, patch_radius, ...])	Performs PCA-based denoising using the Marcenko-Pastur distribution.

Module: denoise.nlmeans

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

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

Module: denoise.noise_estimate

piesno(data, N, *[, alpha, step, itermax, ...])	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 blockwise averaging approach.

Module: denoise.patch2self

vol_denoise(data_dict, b0_idx, dwi_idx, ...)	Denoise a single 3D volume using train and test phase.
patch2self(data, bvals, *[, patch_radius, ...])	Patch2Self Denoiser.

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:

imandarray

Original (unfiltered) image

fimau3D 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 [1] 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

[1] (1,2)

Pierrick Coupé, José V. Manjón, Montserrat Robles, and Louis D. Collins. Adaptive Multiresolution Non-Local Means Filter for 3D MR Image Denoising. IET Image Processing, 6(5):558–568, July 2012. URL: https://doi.org/10.1049/iet-ipr.2011.0161, doi:10.1049/iet-ipr.2011.0161.

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.

See [2] and [3] for further details about the method.

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.

n_pointsint, optional

Number of neighbour points to access local TV (see note).

inplacebool, optional

If True, the input data is replaced with results. Otherwise, returns a new array.

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

[2]

Elias Kellner, Bibek Dhital, Valerij G. Kiselev, and Marco Reisert. Gibbs-ringing artifact removal based on local subvoxel-shifts. Magnetic Resonance in Medicine, 76(5):1574–1581, 2016. URL: https://doi.org/10.1002/mrm.26054, doi:10.1002/mrm.26054.

[3]

Rafael Neto Henriques. Advanced Methods for Diffusion MRI Data Analysis and their Application to the Healthy Ageing Brain. PhD thesis, Cambridge University, Cambridge, United Kingdom, 2018. URL: https://doi.org/10.17863/CAM.29356, doi: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.

Parameters:

arrndarray

Data to be denoised.

num_samplesint

Number of samples.

sprint

Suggested patch radius.

Returns:

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 [4], [5].

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\) [6]), 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

[4] (1,2)

Jelle Veraart, Els Fieremans, and Dmitry S. Novikov. Diffusion MRI noise mapping using random matrix theory. Magnetic Resonance in Medicine, 76(5):1582–1593, November 2016. URL: https://doi.org/10.1002/mrm.26059, doi:10.1002/mrm.26059.

[5] (1,2,3,4)

Jelle Veraart, Dmitry S. Novikov, Daan Christiaens, Benjamin Ades-aron, Jan Sijbers, and Els Fieremans. Denoising of diffusion MRI using random matrix theory. NeuroImage, 142:394–406, November 2016. URL: https://doi.org/10.1016/j.neuroimage.2016.08.016, doi:10.1016/j.neuroimage.2016.08.016.

[6] (1,2,3,4,5)

José V. Manjón, Pierrick Coupé, Luis Concha, Antonio Buades, D. Louis Collins, and Montserrat Robles. Diffusion Weighted Image Denoising Using Overcomplete Local PCA. PLOS ONE, 8(9):e73021, 2013. URL: https://doi.org/10.1371/journal.pone.0073021, doi:10.1371/journal.pone.0073021.

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.

The method follows the algorithm in Manjón et al.[6].

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 Manjón et al.[6].

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

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 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 [5]. Default: 2.3 according to Manjón et al.[6].

return_sigmabool, optional

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

correct_biasbool, optional

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

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.

See [5] for further details about the method.

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 [4].

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.

See :footcite:p:Descoteaux2008a` for further details about the method.

Parameters:

arr3D or 4D ndarray

The array to be denoised

mask3D ndarray

sigmafloat 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

piesno

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

Probabilistic Identification and Estimation of Noise (PIESNO).

See [7] and [8] for further details about the method.

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.

stepint

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

[7]

Cheng Guan Koay, Evren Özarslan, and Peter J. Basser. A signal transformational framework for breaking the noise floor and its applications in MRI. Journal of Magnetic Resonance, 197(2):108–119, April 2009. URL: https://doi.org/10.1016/j.jmr.2008.11.015, doi:10.1016/j.jmr.2008.11.015.

[8]

Cheng Guan Koay, Evren Özarslan, and Carlo Pierpaoli. Probabilistic Identification and Estimation of Noise (PIESNO): A self-consistent approach and its applications in MRI. Journal of Magnetic Resonance, 199(1):94–103, July 2009. URL: https://doi.org/10.1016/j.jmr.2009.03.005, doi:10.1016/j.jmr.2009.03.005.

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, optional

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, optional

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 [9] 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 from Koay and Basser[9] (see equation 18 in [9]) with theta = 0. Since this function was introduced in [10] 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

[9] (1,2,3)

Cheng Guan Koay and Peter J. Basser. Analytically exact correction scheme for signal extraction from noisy magnitude MR signals. Journal of Magnetic Resonance, 179(2):317–322, April 2006. URL: https://doi.org/10.1016/j.jmr.2006.01.016, doi:10.1016/j.jmr.2006.01.016.

[10] (1,2)

Pierrick Coupé, Pierre Yger, Sylvain Prima, Pierre Hellier, Charles Kervrann, and Christian Barillot. An Optimized Blockwise Nonlocal Means Denoising Filter for 3-D Magnetic Resonance Images. IEEE Transactions on Medical Imaging, 27(4):425–441, 2008. URL: https://doi.org/10.1109/TMI.2008.2008967, doi:10.1109/TMI.2007.906087.

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.

See [10] and [1] for further details about the method.

Parameters:

arr3D or 4D ndarray

The array to be denoised

mask3D ndarray

Mask on data where the non-local means will be applied.

sigmafloat or ndarray

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

vol_denoise

dipy.denoise.patch2self.vol_denoise(data_dict, b0_idx, dwi_idx, model, alpha, b0_denoising, verbose, tmp_dir)

Denoise a single 3D volume using train and test phase.

Parameters:

data_dictdict

Dictionary containing the following:

data_namestr

The name of the memmap file containing the memmaped data.

data_dtypedtype

The dtype of the data.

data_shapetuple

The shape of the data.

data_b0sndarray

Array of all 3D patches flattened out to be 2D for b0 volumes.

data_dwindarray

Array of all 3D patches flattened out to be 2D for dwi volumes.

b0_idxndarray

The indices of the b0 volumes.

dwi_idxndarray

The indices of the dwi volumes.

modelsklearn.base.RegressorMixin

This is the model that is initialized from the _fit_denoising_model function.

alphafloat

Regularization parameter only for ridge and lasso regression models.

b0_denoisingbool

Skips denoising b0 volumes if set to False.

verbosebool

Show progress of Patch2Self and time taken.

tmp_dirstr

The directory to save the temporary files.

Returns:

denoised_arr.namestr

The name of the memmap file containing the denoised array.

denoised_arr.dtypedtype

The dtype of the denoised array.

denoised_arr.shapetuple

The shape of the denoised array.

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, tmp_dir=None, version=3)

Patch2Self Denoiser.

See [11] for further details about the method. See [12] for further details about the new method.

Parameters:

datandarray

The 4D noisy DWI data to be denoised.

bvalsarray of shape (N,)

Array of the bvals from the DWI acquisition

patch_radiusint or array of shape (3,), 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 sklearn.base.RegressorMixin

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.

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.

tmp_dirstr, optional

The directory to save the temporary files. If None, the temporary files are saved in the system’s default temporary directory. Default: None.

versionint, optional

Version 1 or 3 of Patch2Self to use. Default: 3

Returns:

denoised arrayndarray

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

References

[11]

Shreyas Fadnavis, Joshua Batson, and Eleftherios Garyfallidis. Patch2Self: Denoising Diffusion MRI with Self-Supervised Learning. In Hugo Larochelle, Marc’Aurelio Ranzato, Raia Hadsell, Maria-Florina Balcan, and Hsuan-Tien Lin, editors, Advances in Neural Information Processing Systems, volume 33, 16293–16303. Curran Associates, Inc., 2020. URL: https://proceedings.neurips.cc/paper_files/paper/2020/file/bc047286b224b7bfa73d4cb02de1238d-Paper.pdf.

[12]

Shreyas Fadnavis, Agniva Chowdhury, Joshua Batson, Petros Drineas, and Eleftherios Garyfallidis. Patch2Self2: Self-supervised Denoising on Coresets via Matrix Sketching. In Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition, volume, 27641–27651. 2024. URL: https://openaccess.thecvf.com/content/CVPR2024/papers/Fadnavis_Patch2Self2_Self-supervised_Denoising_on_Coresets_via_Matrix_Sketching_CVPR_2024_paper.pdf.