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. MRM 2024. doi:10.1002/mrm.30101

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",
    bounds_override=None,
    aif_detection_method="multi_criteria",
    initial_guess_override=None,
    max_iterations=None,
    tolerance=None,
    r2_threshold=None,
)

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. 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`

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.