parameter_map

parameter_map

ParameterMap container for computed perfusion parameters.

This module provides the data container for storing computed parameter maps with associated metadata, uncertainty estimates, and quality masks.

The ParameterMap.name and ParameterMap.symbol fields use the OSIPI CAPLEX naming convention where applicable (e.g. "Ktrans", "ve", "CBF"). Units are stored as ASCII strings using caret notation for exponents (e.g. "mm^2/s", "min^-1").

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101

ParameterMap dataclass

ParameterMap(
    name,
    symbol,
    units,
    values,
    affine,
    uncertainty=None,
    uncertainty_type=None,
    quality_mask=(lambda: array([], dtype=bool))(),
    failure_reasons=None,
    model_name="",
    fitting_method="",
    literature_reference="",
)

Container for a single computed parameter map.

This dataclass holds a 3D parameter map along with metadata about the parameter, uncertainty estimates, and quality indicators.

ATTRIBUTE	DESCRIPTION
name	OSIPI lexicon parameter name (e.g., 'Ktrans', 'CBF', 'D'). TYPE: str
symbol	Display symbol for visualization (e.g., 'Kᵗʳᵃⁿˢ', 'CBF'). TYPE: str
units	Units string (e.g., 'min⁻¹', 'ml/100g/min', 'mm²/s'). TYPE: str
values	3D parameter map array with shape (x, y, z). TYPE: NDArray[floating]
affine	4x4 affine transformation matrix. TYPE: NDArray[floating]
uncertainty	Uncertainty estimate (standard error or confidence interval width). TYPE: NDArray[floating] | None
uncertainty_type	Type of uncertainty ('std_error', 'ci_95', 'ci_99'). TYPE: str | None
quality_mask	Boolean mask where True indicates valid/reliable estimate. TYPE: NDArray[bool_]
failure_reasons	String array with failure codes for invalid voxels. TYPE: NDArray[object_] | None
model_name	Name of the model used to compute this parameter. TYPE: str
fitting_method	Fitting algorithm used (e.g., 'levenberg_marquardt', 'bayesian'). TYPE: str
literature_reference	Citation for the algorithm/model. TYPE: str

Examples:

>>> import numpy as np
>>> from osipy.common.parameter_map import ParameterMap
>>> values = np.random.rand(64, 64, 20) * 0.5  # Ktrans values
>>> affine = np.eye(4)
>>> quality_mask = values > 0.01  # Exclude very low values
>>> ktrans_map = ParameterMap(
...     name="Ktrans",
...     symbol="Kᵗʳᵃⁿˢ",
...     units="min⁻¹",
...     values=values,
...     affine=affine,
...     quality_mask=quality_mask,
...     model_name="ExtendedTofts",
...     fitting_method="levenberg_marquardt",
...     literature_reference="Tofts PS et al. (1999). JMRI.",
... )

References

OSIPI CAPLEX Lexicon: https://osipi.github.io/OSIPI_CAPLEX/

shape property

shape

Return the shape of the parameter map.

valid_fraction property

valid_fraction

Return fraction of voxels with valid estimates.

n_valid property

n_valid

Return number of voxels with valid estimates.

n_failed property

n_failed

Return number of voxels with failed estimates.

__post_init__

__post_init__()

Validate parameter map after initialization.

masked_values

masked_values()

Return values array with invalid voxels set to NaN.

RETURNS	DESCRIPTION
NDArray[floating]	Copy of values with NaN where quality_mask is False.

statistics

statistics()

Compute summary statistics for valid voxels.

RETURNS	DESCRIPTION
dict[str, float]	Dictionary with mean, std, min, max, median for valid voxels.

from_uniform classmethod

from_uniform(value, shape, affine, name, units, symbol='')

Create a uniform parameter map with constant value.

This is useful when a measured parameter map is unavailable and a literature value must be assumed.

PARAMETER	DESCRIPTION
value	Uniform value to fill the map. TYPE: float
shape	Shape of the 3D parameter map (x, y, z). TYPE: tuple[int, int, int]
affine	4x4 affine transformation matrix. TYPE: NDArray[floating]
name	Parameter name (e.g., 'T1', 'T2'). TYPE: str
units	Units string (e.g., 'ms', 's'). TYPE: str
symbol	Display symbol, defaults to name. TYPE: str DEFAULT: ''

RETURNS	DESCRIPTION
ParameterMap	Parameter map with uniform value.

Examples:

>>> import numpy as np
>>> from osipy.common.parameter_map import ParameterMap
>>> # Create uniform T1 map with assumed value
>>> t1_map = ParameterMap.from_uniform(
...     value=1400.0,  # Breast tissue at 3T
...     shape=(320, 320, 128),
...     affine=np.eye(4),
...     name="T1",
...     units="ms",
... )

create_uniform_t1_map

create_uniform_t1_map(t1_ms, shape, affine)

Create a uniform T1 map with assumed value.

This function creates a ParameterMap representing pre-contrast T1 relaxation times when measured T1 mapping data is unavailable. Common use case: datasets without VFA or Look-Locker T1 mapping.

PARAMETER	DESCRIPTION
t1_ms	Assumed T1 value in milliseconds. Typical values at 3T: - Breast tissue: ~1400 ms - Breast cancer: ~1200-1500 ms - Brain white matter: ~800 ms - Brain gray matter: ~1200 ms - Blood: ~1600 ms - Muscle: ~1400 ms TYPE: float
shape	Shape of the 3D T1 map (x, y, z), matching DCE signal dimensions. TYPE: tuple[int, int, int]
affine	4x4 affine transformation matrix from DCE dataset. TYPE: NDArray[floating]

RETURNS	DESCRIPTION
ParameterMap	T1 parameter map with uniform assumed value.

Examples:

>>> import numpy as np
>>> from osipy.common.parameter_map import create_uniform_t1_map
>>> # Assume T1 = 1400 ms for breast tissue at 3T
>>> t1_map = create_uniform_t1_map(
...     t1_ms=1400.0,
...     shape=(320, 320, 128),
...     affine=np.eye(4),
... )
>>> # Use with signal_to_concentration
>>> from osipy.dce import signal_to_concentration
>>> concentration = signal_to_concentration(
...     signal=dce_data,
...     t1_map=t1_map,
...     acquisition_params=params,
... )

Notes

Using an assumed uniform T1 value introduces quantification bias because T1 varies across tissues. This is acceptable when: - T1 mapping data is unavailable (common in clinical datasets) - Relative comparisons are more important than absolute values - The tissue of interest has relatively uniform T1

For more accurate quantification, measure T1 using VFA or Look-Locker sequences when possible.

References

de Bazelaire CM et al. (2004). MR imaging relaxation times of abdominal and pelvic tissues. Radiology.