# `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:
    ima ndarray

      Original (unfiltered) 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.

    fimao 3D double array,

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

    sigma the 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:
    fima 3D 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:
    vol ndarray ([X, Y]), ([X, Y, Z]) or ([X, Y, Z, g])

      Matrix containing one volume (3D) or multiple (4D) volumes of images.

    slice_axis int (0, 1, or 2)

      Data axis corresponding to the number of acquired slices.

    n_points int, optional

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

    inplace bool, optional

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

    num_processes int 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:
    vol ndarray ([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:
    arr ndarray

      Data to be denoised.

    num_samples int

      Number of samples.

    spr int

      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:
    arr ndarray

      Data to be denoised.

    pr int or ndarray

      Patch radius.

  Returns:
    patch_radius ndarray

      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_radius ndarray

      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_size ndarray

      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:
    arr ndarray

      Data to be denoised.

    patch_size ndarray

      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:
    arr 4D 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.

    sigma float 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].

    mask 3D 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_radius int 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_factor float, 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_sigma bool, optional

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

    out_dtype str or dtype, optional

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

    suppress_warning bool, optional

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

  Returns:
    denoised_arr 4D 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:
    arr 4D array

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

    sigma float 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].

    mask 3D 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_radius int 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_sigma int, 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_factor float, 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_sigma bool, optional

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

    correct_bias bool, optional

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

    out_dtype str or dtype, optional

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

    suppress_warning bool, optional

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

  Returns:
    denoised_arr 4D 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:
    arr 4D array

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

    mask 3D 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_radius int 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_sigma bool, optional

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

    out_dtype str or dtype, optional

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

    suppress_warning bool, optional

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

  Returns:
    denoised_arr 4D array

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

    sigma 3D 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:
    arr 3D 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_radius int

      patch size is `2 x patch_radius + 1`. Default is 1.

    block_radius int

      block size is `2 x block_radius + 1`. Default is 5.

    rician boolean

      If True the noise is estimated as Rician, otherwise Gaussian noise is assumed.

    num_threads int, 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_arr ndarray

      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:
    data ndarray

      The magnitude signals to analyse. The last dimension must contain the same realisation of the volume, such as dMRI or fMRI data.

    N int

      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.

    alpha float

      Probabilistic estimation threshold for the gamma function.

    step int

      number of initial estimates for sigma to try.

    itermax int

      Maximum number of iterations to execute if convergence is not reached.

    eps float

      Tolerance for the convergence criterion. Convergence is reached if two subsequent estimates are smaller than eps.

    return_mask bool

      If True, return a mask identifying all the pure noise voxel that were found.

  Returns:
    sigma float

      The estimated standard deviation of the gaussian noise.

    mask ndarray, 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:
    arr 3D or 4D ndarray

      The array to be estimated

    disable_background_masking bool, 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.

    N int, 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:
    sigma ndarray

      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:
    arr 3D or 4D ndarray

      The array to be denoised

    mask 3D ndarray

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

    sigma float or ndarray

      standard deviation of the noise estimated from the data

    patch_radius int

      patch size is `2 x patch_radius + 1`. Default is 1.

    block_radius int

      block size is `2 x block_radius + 1`. Default is 5.

    rician boolean

      If True the noise is estimated as Rician, otherwise Gaussian noise is assumed.

  Returns:
    denoised_arr ndarray

      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_dict dict
      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_idx ndarray

      The indices of the b0 volumes.

    dwi_idx ndarray

      The indices of the dwi volumes.

    model sklearn.base.RegressorMixin

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

    alpha float

      Regularization parameter only for ridge and lasso regression models.

    b0_denoising bool

      Skips denoising b0 volumes if set to False.

    verbose bool

      Show progress of Patch2Self and time taken.

    tmp_dir str

      The directory to save the temporary files.

  Returns:
    denoised_arr.name str

      The name of the memmap file containing the denoised array.

    denoised_arr.dtype dtype

      The dtype of the denoised array.

    denoised_arr.shape tuple

      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:
    data ndarray

      The 4D noisy DWI data to be denoised.

    bvals array of shape (N,)

      Array of the bvals from the DWI acquisition

    patch_radius int 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).

    model string, 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_threshold int, optional

      Threshold for considering volumes as b0.

    out_dtype str or dtype, optional

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

    alpha float, optional

      Regularization parameter only for ridge regression model.

    verbose bool, optional

      Show progress of Patch2Self and time taken.

    b0_denoising bool, optional

      Skips denoising b0 volumes if set to False.

    clip_negative_vals bool, optional

      Sets negative values after denoising to 0 using np.clip.

    shift_intensity bool, optional

      Shifts the distribution of intensities per volume to give non-negative values.

    tmp_dir str, optional

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

    version int, optional

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

  Returns:
    denoised array ndarray

      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.