dce_pipeline

dce_pipeline ¶

DCE-MRI analysis pipeline.

This module provides an end-to-end DCE-MRI analysis pipeline, integrating T1 mapping, signal-to-concentration conversion, AIF handling, and pharmacokinetic model fitting.

The pipeline produces OSIPI CAPLEX-compliant parameter maps (Ktrans, ve, vp, kep) and supports population AIFs from the CAPLEX model registry (M.IC2.001 Parker, M.IC2.002 Georgiou).

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Dickie BR et al. A community-endorsed open-source lexicon for contrast agent-based perfusion MRI: A consensus guidelines report from the ISMRM Open Science Initiative for Perfusion Imaging (OSIPI). MRM 2024;91(5):1761-1773. doi:10.1002/mrm.29840

DCEPipelineConfig `dataclass` ¶

DCEPipelineConfig(t1_mapping_method='vfa', model='extended_tofts', aif_source='population', population_aif='parker', acquisition_params=None, output_dir=None, save_intermediate=False, fitter=None, concentration_method='spgr', vfa_fit_method='linear', bounds_override=None, aif_detection_method='multi_criteria', initial_guess_override=None, max_iterations=None, tolerance=None, r2_threshold=None, fit_delay=False)

Configuration for DCE-MRI pipeline.

ATTRIBUTE	DESCRIPTION
`t1_mapping_method`	T1 mapping method: 'vfa' or 'look_locker'. TYPE: `str`
`model`	Pharmacokinetic model: 'tofts', 'extended_tofts', 'patlak', '2cxm'. TYPE: `str`
`aif_source`	AIF source: 'population' (Parker), 'detect', or 'manual'. TYPE: `str`
`population_aif`	Population AIF type if aif_source='population'. TYPE: `str`
`acquisition_params`	Acquisition parameters for signal conversion. TYPE: `DCEAcquisitionParams \| None`
`output_dir`	Output directory for results. TYPE: `Path \| None`
`save_intermediate`	Whether to save intermediate results. TYPE: `bool`
`fitter`	Fitter registry name (e.g., 'lm', 'bayesian'). TYPE: `str \| None`
`concentration_method`	Signal-to-concentration conversion method ('spgr' or 'linear'). TYPE: `str`
`vfa_fit_method`	VFA T1 fit when t1_mapping_method='vfa': 'linear' or 'nonlinear'. TYPE: `str`
`bounds_override`	Per-parameter bound overrides for fitting. TYPE: `dict[str, tuple[float, float]] \| None`
`aif_detection_method`	AIF detection method when aif_source='detect'. TYPE: `str`
`initial_guess_override`	Per-parameter initial guess overrides for fitting. TYPE: `dict[str, float] \| None`
`max_iterations`	Maximum number of fitting iterations. TYPE: `int \| None`
`tolerance`	Convergence tolerance for fitting. TYPE: `float \| None`
`r2_threshold`	R-squared threshold for valid fitting results. TYPE: `float \| None`
`fit_delay`	If True, jointly fit an arterial delay parameter with the DCE model (adds one parameter per voxel). Defaults to False. TYPE: `bool`

Notes

Selection points (model, T1 method, concentration model, population AIF) are registry-driven: their names map to :class:MethodConfig models in :mod:osipy.dce.config, and the pipeline builds each component from a validated config via :func:construct_from_config. The string fields here are normalized to those configs in :meth:__post_init__, so callers may pass either a name (e.g. model="tofts") or a MethodConfig instance.

__post_init__ ¶

__post_init__()

Normalize name/MethodConfig fields into validated config objects.

Each selection point accepts either a registry name (str) or an already-validated :class:MethodConfig. Names are looked up in the corresponding *_CONFIGS map; the VFA fit_method knob is folded into the VFA config so the nonlinear path is selectable via the flat vfa_fit_method field as well as a nested config.

DCEPipelineResult `dataclass` ¶

DCEPipelineResult(fit_result, t1_map, aif, concentration, config)

Result of DCE pipeline.

ATTRIBUTE	DESCRIPTION
`fit_result`	Model fitting results. TYPE: `DCEFitResult`
`t1_map`	T1 map (if computed). TYPE: `ParameterMap \| None`
`aif`	AIF used for analysis. TYPE: `ArterialInputFunction`
`concentration`	Concentration data. TYPE: `NDArray \| None`
`config`	Pipeline configuration used. TYPE: `DCEPipelineConfig`

DCEPipeline ¶

DCEPipeline(config=None)

End-to-end DCE-MRI analysis pipeline.

This pipeline performs: 1. T1 mapping (if VFA/LL data provided) 2. Signal-to-concentration conversion 3. AIF extraction or population AIF generation 4. Pharmacokinetic model fitting 5. Parameter map generation

Examples:

>>> from osipy.pipeline import DCEPipeline, DCEPipelineConfig
>>> config = DCEPipelineConfig(model='extended_tofts')
>>> pipeline = DCEPipeline(config)
>>> result = pipeline.run(dce_data, time, t1_data=vfa_data)

Initialize DCE pipeline.

PARAMETER	DESCRIPTION
`config`	Pipeline configuration. TYPE: `DCEPipelineConfig \| None` DEFAULT: `None`

run ¶

run(dce_data, time, t1_data=None, t1_map=None, aif=None, mask=None, flip_angles=None, tr=None, progress_callback=None)

Run DCE-MRI analysis pipeline.

PARAMETER	DESCRIPTION
`dce_data`	DCE-MRI signal data, shape (..., n_timepoints). TYPE: `PerfusionDataset or NDArray`
`time`	Time points in seconds. TYPE: `NDArray`
`t1_data`	T1 mapping data (VFA or Look-Locker). TYPE: `PerfusionDataset or NDArray` DEFAULT: `None`
`t1_map`	Pre-computed T1 map. If provided, skips T1 mapping. TYPE: `ParameterMap` DEFAULT: `None`
`aif`	Custom AIF. If None, uses config.aif_source. TYPE: `ArterialInputFunction or NDArray` DEFAULT: `None`
`mask`	Brain/tissue mask. TYPE: `NDArray` DEFAULT: `None`
`flip_angles`	Flip angles for VFA T1 mapping (degrees). TYPE: `NDArray` DEFAULT: `None`
`tr`	TR for T1 mapping (ms). TYPE: `float` DEFAULT: `None`
`progress_callback`	Callback for progress updates (step_name, progress). TYPE: `Callable` DEFAULT: `None`

RETURNS	DESCRIPTION
`DCEPipelineResult`	Pipeline results.