cerr.mri_metrics package

Submodules

cerr.mri_metrics.dce_mri module

cerr.mri_metrics.dce_mri.loadTimeSeq()[source]

Function to extract 4D DCE scan array associated with input structure from planC

Parameters:

  • planC (plan_container.planC) – pyCERR’s plan container object

  • structNum (int) – Index of structure in planC

  • userInputTime (np.array, float) – [optional. default=None, read acquisitionTime] Set to True for user-input acquisition times

Returns:

DCE array (nRows x nCols x nROISlc x nTime) timePtsV (np.array, 1D) : Acquisition times (min) maskSlc3M (np.ndarray, 3D) : Mask of ROI (nRows x nCols x nROISlc) maskSlcV (np.array, 1D) : Indices of slices in the ROI (1 x nROISlc)

Return type:

scanArr4M (np.ndarray, 4D)

cerr.mri_metrics.dce_mri.intToConc(normSigM, concDict)[source]

Converts DCE-MRI signal intensity into contrast agent concentration.

Parameters:

  • normSigM (tuple, float) – Array of normalized intensities (S(t)/S(0))

  • concDict (dict) –

    Dictionary specifying clip_between (float array): Clip normalized intensities (intensity/baseline)

    between specified mon,max values

    T10 (float): Pre-contrast longitudinal relaxation time FA (float): Flip angle (degrees) TR (float): Repetition time (seconds) r1 (float): Relaxivity

Returns:

Concentration (C) in mmol/L and R1 map

Ref.: Heilmann, M. et al. (2006) “Determination of pharmacokinetic parameters in DCE MRI:

consequence of nonlinearity between contrast agent concentration and signal intensity.” Investigative radiology 41.6: 536-543.

cerr.mri_metrics.dce_mri.plotUptake(timePtsV, sigV, blockFlag, savePath=None)[source]

Plot a sample DCE uptake curve for interactive selection of baseline points.

Displays a labeled time-series plot of ROI mean signal intensity with each time-point annotated by its index so the user can identify the start of uptake.

Parameters:

  • timePtsV (np.ndarray) – 1-D array of acquisition time points.

  • sigV (np.ndarray) – 1-D array of ROI mean signal intensities corresponding to each time point in timePtsV.

  • blockFlag (bool) – If True, the plot blocks execution until it is closed; if False, execution continues immediately.

  • savePath (str, optional) – File path at which to save the figure. When provided the figure is saved and closed rather than displayed interactively. Defaults to None.

Returns:

Always returns 0.

Return type:

int

cerr.mri_metrics.dce_mri.getStartofUptake()[source]

Function for interactive selection of baseline points

Parameters:

  • slice3M (np.ndarray, 3D) – 3D array containing time sequence of scan slice (nRows x nCols x nTime)

  • maskM (np.ndarray, 2D) – Mask of ROI slice

Returns:

Time point representing start of uptake

Return type:

basePts (int)

cerr.mri_metrics.dce_mri.normalizeToBaseline()[source]

Function to normalize DCE signal to avg. baseline value

Parameters:

  • scanArr4M (np.ndarray, 4D) – DCE array (nRows x nCols x nROISlc x nTime)

  • mask3M (np.ndarray, 3D) – Mask of ROI (nRows x nCols x nROISlc)

  • timePtsV (np.array, 1D) – Acquisition times (min)

  • basePts (int) – [optional, default:None] Time pt. representing start of uptake. By default, have user input value.

  • imgSmoothDict (dict) – [optional, default:None] Dictionary specifying Gaussian smoothing filter parameters. If specified, keys ‘kernelSize’ and ‘sigma’ must be present.

  • enhThresh (float) – [optional, default: None] Intensity threshold to identify enhancing voxels. Voxels with peak intensity < thresh*baseline are excluded from analysis.

  • method (string) – [optional, default:’RSE’] Convert intensities to relative signal enhancement (‘RSE’) or contrast concentration (CC)

  • concDict (dict) – [optional, default:None] Required if method=’CC’. Dictionary of parameters required to compute contrast agent concentration. Required keys: ‘clip_above’, ‘T10’, ‘flipAngle’, ‘TR’, ‘r1’.

Returns:

DCE array (nRows x nCols x nROISlc x nTime) timePtsV (np.array) : Acquisition times (min) normScan4M(np.ndarray) : Normalized scan array (nRows x nCols x nROISlc x nUptakeTime) uptakeTimeV : Acquisition times for uptake (min) (1 x nUptakeTime)

Return type:

scanArr4M (np.ndarray)

cerr.mri_metrics.dce_mri.locatePeak()[source]

Function to locate peak of uptake curve

Parameters:

  • sigM (np.ndarray, 2D) – Uptake curves (nVox x nUptakeTime)

  • smoothFlag (bool) – [optional; default: False] Filter out noise if True.

Returns:

Indices corresponding to peak of uptake (1 x nVox)

Return type:

peakIdxV (np.array)

cerr.mri_metrics.dce_mri.smoothResample()[source]

Function to process uptake curve prior to feature extraction

Parameters:

  • sigM (np.ndarray, 2D) – Uptake curves (nVox x nUptakeTime)

  • timeV (np.array, 1D) – Acquisition times (1 x nUptakeTime)

  • temporalSmoothFlag (bool) – [optional, default:False] Smooth curves follg. peak using cubic splines.

  • resampFlag (bool) – [optional, default:False] Resample uptake curves to 0.1 min resolution if True.

Returns:

Processed uptake curves (nVox x nResampUptakeTime) timeOutV (np.array, 1D) : Resampled time pts (min) (1 x nResampUptakeTime)

Return type:

resampSigM (np.ndarray, 2D)

cerr.mri_metrics.dce_mri.semiQuantFeatures()[source]

Compute non-parametric features from pre-processed contrast uptake curve. Ref.: Lee, S.H., et al. (2017) “Correlation Between Tumor Metabolism and Semiquantitative Perfusion

MRI Metrics in Non–small Cell Lung Cancer.” IJROBP 99.2:S83-S84.

Parameters:

  • procSlcSigM (np.ndarray, 2D) – Processed uptake curves (nVox x nResampleTime)

  • procTimeV (np.array, 1D) – Acquisition times (1 x nResampleTime) in min.

Returns:

Dictionary of non-parameteric features.

Return type:

featureDict (dict)

cerr.mri_metrics.dce_mri.calcROIuptakeFeatures()[source]

Wrapper to compute non-parametric uptake characteristics for each slice of input ROI.

Parameters:

  • planC (plan_container.planC) – pyCERR’s plan container object

  • structNum (int) – Index of structure in planC

  • timeV (np.array, float) – [optional, default:None] User-input acquisition times

  • basePts (int) – [optional, default:None] Time pt. representing start of uptake. By default, have user input value.

  • imgSmoothDict (dict) – [optional, default:None] Dictionary specifying whether to smooth image & associated filter parameters. Keys: ‘kernelSize’, ‘sigma’.

  • enhThresh (float) – [optional, default:None] Intensity threshold to identify enhancing voxels. Voxels with peak intensity < thresh*baseline are excluded from analysis.

  • sigType (string) – [optional, default:’RSE’] Convert intensities to relative signal enhancement (‘RSE’) or contrast concentration (‘CC’)

  • concDict (dict) – [optional, default:{}] Required if method=’CC’. Dictionary of parameters required to compute contrast agent concentration. Must specify threshold, T10, flipAngle, TR, r1.

  • temporalSmoothFlag (bool) – [optional, default:False] Flag specifying whether to smooth curves follg. peak using cubic splines.

  • resampFlag (bool) – [optional, default:False] Resample uptake curves to 0.1 min resolution if True.

  • plotDict (dict) – [optional, default:{}] Display sample plots showing computed features (interactive)

Returns:

List of dictionaries (one per ROI slice) containing uptake features.

Return type:

featureList

cerr.mri_metrics.dce_mri.plotSampleFeatures()[source]

Function to plot sample uptake curves and indicate extracted features.

Parameters:

  • procSlcSigM (np.ndarray, 2D) – Processed uptake curves (nVox x nResampUptakeTime)

  • sigType (string) – [optional, default:’RSE’] Convert intensities to relative signal enhancement (‘RSE’) or contrast concentration (CC)

  • skipIdxV (int) – Indices of voxels with nan or all-zero signals

  • featureDict (dict) – Dictionary of non-parameteric features

  • numPlots (int) – [optional, default = 1] No. sample plots to display per ROI slice.

cerr.mri_metrics.dce_mri.createFeatureMaps()[source]

Function to generate maps of non-parametric features.

Parameters:

  • featureList – List of dictionaries (one per ROI slice) containing uptake features.

  • structNum (int) – Index of structure in planC.

  • planC (plan_container.planC) – pyCERR’s plan container object

  • importFlag (bool) – [optional, default:False] Import to planC as pseudo-dose.

  • type (str) – [optional, default:’scan’] Import to planC as pseudo-scan (‘scan’) or pseudo-dose (‘dose’).

Returns:

Dictionary of features maps. planC (plan_container.planC): pyCERR’s plan container object

Return type:

mapDict (dict)

cerr.mri_metrics.dce_mri.collectUserInput(saveDir)[source]

Display saved uptake-curve plots sequentially and collect user-entered start-of-uptake values.

Iterates over all PNG files in saveDir, displays each image, prompts the user to enter the start-of-uptake time point for that dataset, and saves all responses to an Excel file (user_inputs.xlsx) in the same directory.

Parameters:

saveDir (str) – Path to a directory containing PNG plot files whose base-names are used as dataset identifiers.

Returns:

Always returns 0.

Return type:

int

cerr.mri_metrics.dce_mri.batchSelectStartOfUptake(baseDir, saveDir)[source]

Batch-process a cohort of DCE-MRI datasets to facilitate interactive start-of-uptake selection.

For each patient directory found under baseDir the function loads the corresponding DICOM data and NIfTI segmentation mask into a pyCERR planC, extracts the DCE time sequence, computes the mean ROI signal curve for the middle ROI slice, saves a PNG plot of that curve to saveDir, and finally invokes collectUserInput() so the user can annotate all saved plots in one pass. Any exceptions encountered during per-patient processing are recorded in exceptions.log inside saveDir.

Parameters:

  • baseDir (str) – Root directory whose immediate sub-directories each correspond to one patient / dataset.

  • saveDir (str) – Directory in which output PNG plots, the collected user_inputs.xlsx, and any exceptions.log are written. Created automatically if it does not exist.

Returns:

The open log-file handle for exceptions.log (or the handle from the last iteration when no exceptions were raised).

Return type:

file

Module contents