Preprocessing API Reference: Denoising and Gibbs Removal

The src.preprocessing module provides two families of operations applied to NIfTI data before quantitative analysis: spatial denoising via multiple filter algorithms, and Gibbs ringing suppression. Both steps produce _preproc.nii.gz output files in the derivatives folder and can be run independently or in sequence through the GUI or the API.

Denoising

`denoise_init_one_file(nifti_filename, study_acq_derivatives_dir, selected_filter)`

High-level entry point for denoising a single NIfTI file. Applies the chosen filter with default parameters (no interactive prompts) and writes the result to study_acq_derivatives_dir.

nifti_filename

string

required

Path to the input NIfTI file (.nii.gz).

study_acq_derivatives_dir

string

required

Output directory for the preprocessed file. The function creates the file <basename>_preproc.nii.gz inside this directory.

selected_filter

string

required

Filter selection string. Routing is performed by get_selected_filter: if the string contains "dipy", the Dipy NLM filter is used; otherwise the second character (index [1:2], lowercased) determines the algorithm. The GUI passes menu labels prefixed with & (e.g. "&Non local means skimage"), which naturally places the identifying letter at position 1. When calling the API directly, use any string whose second character matches the table below:

Second character (`[1:2]`)	Algorithm	Example `selected_filter`
`"n"`	Non-Local Means (skimage)	`"&Non local means skimage"`
`"d"` (or `"dipy"` in string)	Non-Local Means (Dipy)	`"&Non local means skimage dipy's"`
`"a"`	ASCM	`"&Adaptative Soft Coefficient Matching"`
`"m"`	Marchenko–Pastur PCA	`"&mppca"`
`"l"`	Local PCA	`"&lpca"`
`"p"`	Patch2Self	`"&patch2self"`

Returns str — path to the output _preproc.nii.gz file.

from src.preprocessing.denoise.denoise_filter import denoise_init_one_file

output_path = denoise_init_one_file(
    nifti_filename="dce_data.nii.gz",
    study_acq_derivatives_dir="derivatives/sub-001/",
    selected_filter="&Non local means skimage"
)
print(output_path)  # derivatives/sub-001/dce_data_preproc.nii.gz

Gibbs Ringing Removal

`gibbs_remove(processing_filenames_list)`

Applies Gibbs ringing suppression (via dipy.denoise.gibbs.gibbs_removal) to the first file in the list. If a _preproc tag is not already present in the filename, the output is saved as <basename>_preproc.nii.gz. Subsequent files in the list (if any) are processed with the same settings.

processing_filenames_list

list[str]

required

List of NIfTI file paths to process. The primary file is processing_filenames_list[0]; additional entries are processed without interactive confirmation.

Returns str — path to the Gibbs-corrected output file (the updated value of processing_filenames_list[0]).

from src.preprocessing.gibbs_removal.gibbs_removal import gibbs_remove

corrected_path = gibbs_remove(["dce_data_preproc.nii.gz"])
print(corrected_path)  # dce_data_preproc.nii.gz  (updated in-place if already _preproc)

Denoising filter parameters

Each filter function shares the signature (image, params, check_params) and returns (denoised_image, params_used). When params is None and check_params is False, factory defaults are applied automatically — this is the behaviour used by denoise_init_one_file.

Non-Local Means (skimage) — non_local_means_denoising

Implements slice-wise NLM denoising using skimage.restoration.denoise_nl_means. Supports both 3D and 4D inputs; 4D volumes are processed slice-by-slice per time frame.

Parameter	Type	Default	Description
`patch_size`	`int`	`3`	Side length of the square patches used for comparison.
`patch_distance`	`int`	`7`	Maximum search radius (in pixels) for similar patches.
`h`	`float`	`4.5`	Cut-off distance in gray-level units. Higher values produce stronger smoothing.

from src.preprocessing.denoise.denoise_filter import non_local_means_denoising
import numpy as np

image = np.random.rand(64, 64, 10, 20).astype(np.float32)
denoised, used_params = non_local_means_denoising(image, params=None, check_params=False)
# used_params == {"patch_size": 3, "patch_distance": 7, "h": 4.5}

Non-Local Means (Dipy) — non_local_means_2_denoising

Uses dipy.denoise.nlmeans.nlmeans with Rician noise modelling. Sigma is estimated automatically via dipy.denoise.noise_estimate.estimate_sigma.

Parameter	Type	Default	Description
`N_sigma`	`int`	`0`	Number of receiver coils, used for sigma estimation. Set to `0` for a single-channel acquisition.
`patch_radius`	`int`	`1`	Radius of the patch neighbourhood.
`block_radius`	`int`	`2`	Radius of the search block.
`rician`	`bool`	`True`	If `True`, the filter assumes Rician (magnitude MRI) noise statistics.

from src.preprocessing.denoise.denoise_filter import non_local_means_2_denoising

denoised, used_params = non_local_means_2_denoising(image, params=None, check_params=False)

ASCM — ascm_denoising

Adaptive Soft Coefficient Matching: runs NLM twice (small and large patch radii) and combines the results via dipy.denoise.adaptive_soft_matching.adaptive_soft_matching. For 4D images, each volume is processed independently.

Parameter	Type	Default	Description
`N_sigma`	`int`	`0`	Number of receiver coils for sigma estimation.
`patch_radius_small`	`int`	`1`	Patch radius for the first (fine) NLM pass.
`patch_radius_large`	`int`	`2`	Patch radius for the second (coarse) NLM pass.
`block_radius`	`int`	`2`	Search block radius for both NLM passes.
`rician`	`bool`	`True`	Assumes Rician noise statistics when `True`.

from src.preprocessing.denoise.denoise_filter import ascm_denoising

denoised, used_params = ascm_denoising(image, params=None, check_params=False)

MP-PCA — mp_pca_denoising

Marchenko–Pastur PCA denoising via dipy.denoise.localpca.mppca. Suitable for 4D DCE data where temporal redundancy can be exploited. This filter is not exposed in the GUI and must be invoked via the API. This is the simplest filter to configure.

Parameter	Type	Default	Description
`patch_radius`	`int`	`2`	Radius of the local cubic patch over which PCA is performed. Larger values capture more spatial context but increase computation time.

from src.preprocessing.denoise.denoise_filter import mp_pca_denoising

denoised, used_params = mp_pca_denoising(image, params=None, check_params=False)

Local PCA — local_pca_denoising

Local PCA denoising via dipy.denoise.localpca.localpca. Requires a gradient table (gtab) built from the acquisition’s b-values and b-vectors. Noise level is estimated using dipy.denoise.pca_noise_estimate.pca_noise_estimate. This filter is not exposed in the GUI and must be invoked via the API.

Parameter	Type	Default	Description
`correct_bias`	`bool`	`True`	Whether to apply bias correction during sigma estimation.
`smooth`	`int`	`3`	Smoothing parameter for sigma estimation.
`tau_factor`	`float`	`2.3`	Threshold factor applied to the estimated noise level.
`patch_radius`	`int`	`2`	Radius of the local patch over which PCA is performed.

from src.preprocessing.denoise.denoise_filter import local_pca_denoising
from dipy.core.gradients import gradient_table
import numpy as np

bvals = np.loadtxt("dce_data.bval")
bvecs = np.loadtxt("dce_data.bvec")
gtab = gradient_table(bvals, bvecs)

denoised, used_params = local_pca_denoising(image, gtab, params=None, check_params=False)

Patch2Self — patch2self_denoising

Self-supervised denoising via dipy.denoise.patch2self.patch2self. Requires only the b-values array (no b-vectors needed). This filter is not exposed in the GUI and must be invoked via the API.

Parameter	Type	Default	Description
`model`	`str`	`"ols"`	Regression model used for self-supervised learning (`"ols"` for ordinary least squares).
`shift_intensity`	`bool`	`True`	If `True`, shifts the intensity of the denoised image.
`clip_negative_vals`	`bool`	`False`	If `True`, negative values in the output are clipped to zero.
`b0_threshold`	`int`	`50`	B-value threshold below which a volume is considered a b0 image.

from src.preprocessing.denoise.denoise_filter import patch2self_denoising
import numpy as np

bvals = np.loadtxt("dce_data.bval")
denoised, used_params = patch2self_denoising(image, bvals, params=None, check_params=False)

API Reference

Configuration

Preprocessing API Reference: Denoising and Gibbs Removal

Denoising

`denoise_init_one_file(nifti_filename, study_acq_derivatives_dir, selected_filter)`

Gibbs Ringing Removal

`gibbs_remove(processing_filenames_list)`

Denoising filter parameters

Build docs developers (and LLMs) love

API Reference

Configuration

Documentation Index

​Denoising

​denoise_init_one_file(nifti_filename, study_acq_derivatives_dir, selected_filter)

​Gibbs Ringing Removal

​gibbs_remove(processing_filenames_list)

​Denoising filter parameters

​Related pages

Build docs developers (and LLMs) love

Denoising

`denoise_init_one_file(nifti_filename, study_acq_derivatives_dir, selected_filter)`

Gibbs Ringing Removal

`gibbs_remove(processing_filenames_list)`

Denoising filter parameters

Related pages