Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rubick65/dcemapper/llms.txt

Use this file to discover all available pages before exploring further.

The src.processing module computes semi-quantitative parametric maps from 4D DCE-MRI signal data. Starting from raw signal intensities, the pipeline derives three output maps — relative contrast enhancement (RCE), maximum RCE, and time-to-peak — each saved as a NIfTI file in the derivatives folder. All functions operate on numpy.ndarray objects and are designed to work together in sequence.

​
semi_quantitative(data, img, folders, semi_quantitative_data=None)

Top-level orchestrator for the semi-quantitative pipeline. Calls calculate_reference_value, calculate_rce, get_rce_max_value, and get_ttp_rce_max_value in order, then saves all three resulting maps to disk. When semi_quantitative_data is None (interactive / GUI mode), the function opens a parameter dialog so the user can set frame_ini_contrast and frame_period visually.
​
data
numpy.ndarray
required
4D signal intensity array of shape (X, Y, Z, T) as returned by load_nifti.
​
img
nibabel.Nifti1Image
required
NiBabel image object used to preserve the affine transformation when saving output NIfTI files.
​
folders
tuple
required
A two-element tuple (output_folder, nifti_file_path). output_folder is the directory where the three output files will be written; nifti_file_path is the source file path used to derive output filenames.
​
semi_quantitative_data
tuple
default:"None"
Optional (frame_ini_contrast, frame_period) tuple that bypasses the interactive prompt. Pass this argument when calling from a script or test. If None, a GUI parameter dialog is shown.
Returns tuple — (rce_path, rce_max_path, tto_rce_max_path), each a str with the absolute path of the saved NIfTI file.
Output file suffixContent
_rce_process.nii.gz4D relative contrast enhancement map
_rce_max_process.nii.gz3D maximum RCE map
_tto_rce_max_process.nii.gz3D time-to-peak map (normalised to [0, 1])
from src.processing.Semi_Quantitative import semi_quantitative
from src.io.nifti_io import load_nifti

data, img = load_nifti("dce_preproc.nii.gz")
rce, rce_max, ttp = semi_quantitative(
    data, img,
    folders=("derivatives/sub-001/", "dce_preproc.nii.gz"),
    semi_quantitative_data=(10, 12.8)  # frame_ini_contrast=10, frame_period=12.8s
)
print(rce)      # derivatives/sub-001/dce_preproc_rce_process.nii.gz
print(rce_max)  # derivatives/sub-001/dce_preproc_rce_max_process.nii.gz
print(ttp)      # derivatives/sub-001/dce_preproc_tto_rce_max_process.nii.gz

​
calculate_reference_value(data, frame_ini_contrast)

Computes the pre-contrast baseline signal S₀ by averaging the first frame_ini_contrast time frames for every voxel.
​
data
numpy.ndarray
required
4D signal array of shape (X, Y, Z, T).
​
frame_ini_contrast
int
required
Number of pre-contrast frames to average. For example, if contrast agent arrives at frame 10, pass frame_ini_contrast=10 to average frames 0..9.
Returns numpy.ndarray of shape (X, Y, Z) — the voxel-wise S₀ baseline. 
from src.processing.Semi_Quantitative import calculate_reference_value

S0 = calculate_reference_value(data, frame_ini_contrast=10)
print(S0.shape)  # (X, Y, Z)

​
calculate_rce(data, reference_value)

Computes the Relative Contrast Enhancement (RCE) at every voxel and time point as: 
RCE(x, y, z, t) = ( S(x,y,z,t) − S0(x,y,z) ) / S0(x,y,z) × 100
A tissue mask is derived internally: voxels whose S₀ exceeds 80 % of the mean S₀ are considered tissue. Voxels outside the mask are set to 0. The result is clipped to the range [0, 500] percent.
​
data
numpy.ndarray
required
4D signal array (X, Y, Z, T), cast internally to float32.
​
reference_value
numpy.ndarray
required
3D baseline array (X, Y, Z) as returned by calculate_reference_value.
Returns numpy.ndarray of shape (X, Y, Z, T) with RCE values in percent, clipped to [0, 500]. 
from src.processing.Semi_Quantitative import calculate_rce, calculate_reference_value

S0  = calculate_reference_value(data, frame_ini_contrast=10)
rce = calculate_rce(data, S0)
print(rce.shape)   # (X, Y, Z, T)
print(rce.max())   # ≤ 500.0

​
get_rce_max_value(rce)

Returns the peak RCE at each voxel, collapsed along the temporal axis.
​
rce
numpy.ndarray
required
4D RCE array of shape (X, Y, Z, T) as returned by calculate_rce.
Returns numpy.ndarray of shape (X, Y, Z) — maximum RCE value across all time frames. 
from src.processing.Semi_Quantitative import get_rce_max_value

rce_max = get_rce_max_value(rce)
print(rce_max.shape)  # (X, Y, Z)

​
get_ttp_rce_max_value(rce, frame_period)

Computes the time-to-peak (TTP) — the time elapsed from acquisition start to the frame with maximum RCE — for each voxel. The map is masked by the tissue ROI computed inside calculate_rce and then normalised to [0, 1].
​
rce
numpy.ndarray
required
4D RCE array of shape (X, Y, Z, T).
​
frame_period
float
required
Duration between consecutive frames in seconds (e.g. 12.8). TTP is calculated as argmax(rce, axis=3) × frame_period.
Returns numpy.ndarray of shape (X, Y, Z) — time-to-peak in seconds, masked to tissue, normalised to the range [0, 1]. 
from src.processing.Semi_Quantitative import get_ttp_rce_max_value

ttp = get_ttp_rce_max_value(rce, frame_period=12.8)
print(ttp.min(), ttp.max())  # 0.0, 1.0
get_ttp_rce_max_value depends on the module-level tissue mask created by the most recent call to calculate_rce. Always call calculate_rce before calling get_ttp_rce_max_value within the same Python session.

Build docs developers (and LLMs) love

Get started for freeTalk to us