normalization

normalization ¶

DSC normalization utilities.

This module provides functions for normalizing DSC perfusion parameters to reference regions, particularly white matter normalization. Produces relative perfusion measures (e.g. rCBV, rCBF) by dividing by a reference tissue value.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Boxerman JL et al. (2006). Relative cerebral blood volume maps corrected for contrast agent extravasation significantly correlate with glioma tumor grade, whereas uncorrected maps do not. AJNR 27(4):859-867. .. [3] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101

NormalizationResult `dataclass` ¶

NormalizationResult(
    normalized_map,
    reference_value,
    reference_std,
    reference_mask,
)

Result of perfusion map normalization.

ATTRIBUTE	DESCRIPTION
`normalized_map`	Normalized parameter map (relative values). TYPE: `ParameterMap`
`reference_value`	Mean value of the reference region. TYPE: `float`
`reference_std`	Standard deviation in reference region. TYPE: `float`
`reference_mask`	Mask of reference region voxels used. TYPE: `NDArray[bool_]`

register_normalizer ¶

register_normalizer(name)

Register a normalization method function.

get_normalizer ¶

get_normalizer(name)

Get a normalizer function by name.

list_normalizers ¶

list_normalizers()

List registered normalization methods.

normalize_to_white_matter ¶

normalize_to_white_matter(
    parameter_map,
    white_matter_mask,
    method="mean",
    percentile_range=(25.0, 75.0),
)

Normalize perfusion parameter map to white matter reference.

Divides parameter values by the mean (or median) white matter value to produce relative perfusion measurements. This is particularly important for rCBV in tumor imaging.

PARAMETER	DESCRIPTION
`parameter_map`	Parameter map to normalize (e.g., CBV, CBF). TYPE: `ParameterMap`
`white_matter_mask`	Binary mask defining white matter reference region. Ideally contralateral normal-appearing white matter. TYPE: `NDArray[bool_]`
`method`	Normalization method: "mean", "median", or "robust_mean". "robust_mean" uses values within percentile_range. TYPE: `str` DEFAULT: `'mean'`
`percentile_range`	Percentile range for robust_mean method. TYPE: `tuple[float, float]` DEFAULT: `(25.0, 75.0)`

RETURNS	DESCRIPTION
`NormalizationResult`	Normalized map and reference statistics.

RAISES	DESCRIPTION
`DataValidationError`	If white_matter_mask is empty or shapes don't match.

Notes

For rCBV, typical normal white matter values are used as reference, making the normalized rCBV = 1.0 in normal white matter and elevated (>1.5-2.0) in high-grade tumors.

References

Wetzel SG et al. (2002). Relative cerebral blood volume measurements in intracranial mass lesions. Radiology 224(2):334-341.

Examples:

>>> import numpy as np
>>> from osipy.common.parameter_map import ParameterMap
>>> from osipy.dsc.normalization import normalize_to_white_matter
>>> cbv_values = np.random.rand(64, 64, 20) * 5
>>> cbv_map = ParameterMap(
...     name="CBV", symbol="CBV", units="ml/100g",
...     values=cbv_values, affine=np.eye(4)
... )
>>> wm_mask = np.zeros((64, 64, 20), dtype=bool)
>>> wm_mask[10:20, 10:20, 5:15] = True
>>> result = normalize_to_white_matter(cbv_map, wm_mask)

compute_relative_cbv ¶

compute_relative_cbv(cbv_map, white_matter_mask)

Compute relative CBV (rCBV) normalized to white matter.

Convenience function for the most common normalization use case.

PARAMETER	DESCRIPTION
`cbv_map`	Absolute CBV map. TYPE: `ParameterMap`
`white_matter_mask`	White matter reference region mask. TYPE: `NDArray[bool_]`

RETURNS	DESCRIPTION
`ParameterMap`	Relative CBV map (rCBV).