vfa

vfa

Variable Flip Angle (VFA) T1 mapping (OSIPI: P.NR2.002).

This module implements T1 mapping from spoiled gradient echo (SPGR) acquisitions at multiple flip angles.

Estimates native longitudinal relaxation rate R1 (OSIPI: Q.EL1.001) and pre-contrast R1 (OSIPI: Q.EL1.002) via the VFA method (OSIPI: P.NR1.001 / P.NR2.002).

GPU/CPU agnostic using the xp array module pattern. Nonlinear fitting uses the shared LevenbergMarquardtFitter.

When input data is on GPU (CuPy array), computations are GPU-accelerated.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Deoni SCL et al. MRM 2003;49(3):515-526.

T1MappingResult dataclass

T1MappingResult(t1_map, m0_map=None, quality_mask=None)

Result of T1 mapping computation.

ATTRIBUTE	DESCRIPTION
t1_map	T1 relaxation time map in milliseconds. TYPE: ParameterMap
m0_map	Equilibrium magnetization map (optional). TYPE: ParameterMap | None
quality_mask	Mask of successfully fitted voxels. TYPE: NDArray[bool_]

compute_t1_vfa

compute_t1_vfa(
    dataset=None,
    method="linear",
    *,
    signal=None,
    flip_angles=None,
    tr=None,
    mask=None,
)

Compute T1 map from Variable Flip Angle data (OSIPI: P.NR2.002).

Estimates native R1 (OSIPI: Q.EL1.001) and equilibrium signal S0 (OSIPI: Q.MS1.010) via VFA method (OSIPI: P.NR1.001).

This function supports two calling conventions: 1. With a PerfusionDataset: compute_t1_vfa(dataset) 2. With individual arrays: compute_t1_vfa(signal=..., flip_angles=..., tr=...)

This function supports GPU acceleration. When the input data is a CuPy array, the computation is performed entirely on GPU.

PARAMETER	DESCRIPTION
dataset	Dataset with images acquired at multiple flip angles. The acquisition_params must be DCEAcquisitionParams with flip_angles (OSIPI: Q.MS1.007) specified. TYPE: PerfusionDataset DEFAULT: None
method	Fitting method: 'linear' (fast) or 'nonlinear' (more accurate). TYPE: str DEFAULT: "linear"
signal	VFA signal data, shape (nx, ny, nz, n_flip_angles). Required if dataset is not provided. TYPE: NDArray DEFAULT: None
flip_angles	Flip angles (OSIPI: Q.MS1.007) in degrees. Required if dataset is not provided. TYPE: NDArray or list DEFAULT: None
tr	Repetition time (OSIPI: Q.MS1.006) in milliseconds. Required if dataset is not provided. TYPE: float DEFAULT: None
mask	Brain/tissue mask. If None, all voxels are processed. TYPE: NDArray DEFAULT: None

RETURNS	DESCRIPTION
T1MappingResult	Result containing T1 map, M0 map, and quality mask.

RAISES	DESCRIPTION
DataValidationError	If input is invalid or incomplete.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Deoni SCL et al. MRM 2003;49(3):515-526.

Examples:

>>> from osipy.dce.t1_mapping.vfa import compute_t1_vfa
>>> result = compute_t1_vfa(dataset)
>>> print(f"Mean T1: {result.t1_map.statistics()['mean']:.0f} ms")

>>> # Or with individual arrays:
>>> result = compute_t1_vfa(signal=vfa_data, flip_angles=[2,5,10,15,20], tr=5.0)