nifreeze.data.filtering module¶

Filtering data.

nifreeze.data.filtering.BVAL_ATOL = 100.0¶: b-value tolerance value.

nifreeze.data.filtering.DEFAULT_DTYPE = 'int16'¶: The default image’s data type.

nifreeze.data.filtering.advanced_clip(data: ndarray, p_min: float = 35.0, p_max: float = 99.98, nonnegative: bool = True, dtype: str | dtype = 'int16', invert: bool = False, inplace: bool = False) → ndarray | None[source]¶

Clips outliers from an n-dimensional array and scales/casts to a specified data type.

This function removes outliers from both ends of the intensity distribution in an n-dimensional array using percentiles. It optionally enforces non-negative values and scales the data to fit within a specified data type (e.g., uint8 for image registration). To remove outliers more robustly, the function first applies a median filter to the data before calculating clipping thresholds.

Parameters:

data (ndarray) – The input n-dimensional data array.
p_min (float, optional) – The lower percentile threshold for clipping. Values below this percentile are set to the threshold value.
p_max (float, optional) – The upper percentile threshold for clipping. Values above this percentile are set to the threshold value.
nonnegative (bool, optional) – If True, only consider non-negative values when calculating thresholds.
dtype (str or dtype, optional) – The desired data type for the output array. Supported types are “uint8” and “int16”.
invert (bool, optional) – If True, inverts the intensity values after scaling (1.0 - data).
inplace (bool, optional) – If True, the normalization is performed on the original data.

Returns:

The clipped and scaled data array with the specified data type or None if inplace is True.

Return type:

ndarray or None

nifreeze.data.filtering.dwi_select_shells(gradients: ndarray, index: int, atol_low: float | None = None, atol_high: float | None = None) → ndarray[source]¶

Select DWI shells around the given index and lower and upper b-value bounds.

Computes a boolean mask of the DWI shells around the given index with the provided lower and upper bound b-values.

If atol_low and atol_high are both None, the returned shell mask corresponds to the lengths of the diffusion-sensitizing gradients.

Parameters:

gradients (ndarray) – Gradients.
index (int) – Index of the shell data.
atol_low (float, optional) – A lower bound for the b-value.
atol_high (float, optional) – An upper bound for the b-value.

Returns:

shellmask – Shell mask.

Return type:

ndarray

nifreeze.data.filtering.grand_mean_normalization(data: ndarray, mask: ndarray | None = None, center: float = 75, inplace: bool = False) → ndarray | None[source]¶

Robust grand mean normalization.

Regresses out global signal differences so that data are normalized and centered around a given value.

If a mask is provided, only the data within the mask are considered.

Parameters:

data (ndarray) – Data to be normalized.
mask (ndarray, optional) – Mask. If provided, only the data within the mask are considered.
center (float, optional) – Central value around which to normalize the data.
inplace (bool, optional) – If False, the normalization is performed on the original data.

Returns:

data – Normalized data or None if inplace is True.

Return type:

ndarray or None

nifreeze.data.filtering.robust_minmax_normalization(data: ndarray, mask: ndarray | None = None, p_min: float = 5.0, p_max: float = 95.0, inplace: bool = False) → ndarray | None[source]¶

Normalize min-max percentiles of each volume to the grand min-max percentiles.

Robust min/max normalization of the volumes in the dataset following:

\[\text{data}_{\text{normalized}} = \frac{(\text{data} - p_{min}) \cdot p_{\text{mean}}}{p_{\text{range}}} + p_{min}^{\text{mean}}\]

where

\[p_{\text{range}} = p_{max} - p_{min}, \quad p_{\text{mean}} = \frac{1}{N} \sum_{i=1}^N p_{\text{range}_i}, \quad p_{min}^{\text{mean}} = \frac{1}{N} \sum_{i=1}^N p_{5_i}\]

If a mask is provided, only the data within the mask are considered.

Parameters:

data (ndarray) – Data to be normalized.
mask (ndarray, optional) – Mask. If provided, only the data within the mask are considered.
p_min (float, optional) – The lower percentile value for normalization.
p_max (float, optional) – The upper percentile value for normalization.
inplace (bool, optional) – If False, the normalization is performed on the original data.

Returns:

data – Normalized data or None if inplace is True.

Return type:

ndarray or None