parametric_scripts¶

parametric_scripts fits quantitative MRI maps voxel by voxel — T1 by variable flip angle, inversion recovery or variable TR; T2 and T2*; and ADC (apparent diffusion coefficient for DWI data).

It exists in two forms: the original MATLAB scripts, which cover all supported fit types, and a Python pipeline inside ROCKETSHIP. Future development will focus only on the Python version, but it currently only supports variable flip angle T1 only.

Repository ROCKETSHIP docs

Where this fits¶

parametric_scripts covers step 4. The full DCEasy pipeline:

Citation¶

parametric_scripts ships as part of ROCKETSHIP. If it contributes to published work, please cite:

Ng, T.S.C., et al. ROCKETSHIP: a flexible and modular software tool for the planning, processing and analysis of dynamic MRI studies. BMC Medical Imaging, 15, 19 (2015). PMID: 26076957

Two implementations¶

There are two, and which one you want depends entirely on what you are mapping.

The MATLAB scripts are the original and have more fitting options: T1 three different ways, T2, T2*, ADC, and a hook for a model you write yourself. They are maintained, but are feature-frozen: no new models or features are going into them.

The Python pipeline is where all future work happens. It lives inside ROCKETSHIP rather than in this repository, and today it fits T1 from variable flip angle and nothing else. It does have some features the Matlab version lacks — B1 correction, BIDS sidecars, GPU acceleration and QC figures, but the other maps have not been ported yet.

The Python pipeline¶

Fits T1 and the equilibrium magnetization ρ voxel by voxel from a variable flip angle series — several spoiled gradient echo images acquired at different flip angles. The pre-contrast T1 map is what converts DCE signal to concentration.

Install¶

It comes with ROCKETSHIP, whose installer sets up the environment and the acceleration libraries:

git clone -b dev https://github.com/petmri/ROCKETSHIP.git
cd ROCKETSHIP
python3 install.py

No MATLAB license is required for the Python implementation.

Run it¶

The installer writes a launcher for the GUI:

./rocketship_parametric.sh

Or there is a command line tool that uses a run configuration:

source .venv/bin/activate
python run_parametric_python_cli.py --config python/parametric_run_example.json

run_parametric_bids_batch.py can be used to process all datasets in a BIDS folder. It applies the same configuration across a BIDS dataset.

Configuration¶

Two files configure files are used. python/parametric_defaults.json holds every default and preference — edit it to change behavior across all runs. A seperate run configuration file (see python/parametric_run_example.json) names only the data and whatever that run overrides, one of these will be needed for every run (the GUI generates one automatically based on user input).

All required settings can be configured through these files without editing the python code. Relative paths in a run configuration resolve against the configuration file's own directory, so a config and its data move together.

The prefered method is to read tr_ms and flip_angles_deg from the JSON sidecar generated with each VFA image. dce2bids will write these automatically. If this is not available they can be specified in the run configuration file.

What it writes¶

Into output_dir: the T1 map as <output_basename>_<fit_type>_<output_label>.nii.gz, an Rsquared_... map, optionally the ρ map, and QC figures. Voxels failing rsquared_threshold — 0.6 by default — are written as -1 rather than dropped, so a failed fit stays visible.

Going deeper¶

• Parametric walkthrough — a worked run from images to maps
• Parametric options — every key, with units and resolution order

The MATLAB scripts¶

The broader toolbox, for anything other than VFA T1.

t2_exponential_plus_c adds a constant offset — Wood's model — for signal that does not decay to zero. The linear_fast variants trade confidence intervals for speed on large volumes.

Requirements¶

• MATLAB, with the Curve Fitting, Image Processing, Statistics and Parallel toolboxes
• The NIfTI toolbox on the MATLAB path

Input images are NIfTI (.nii) or Analyze (.hdr / .img). DICOM is not read.

addpath(genpath('/path/to/ROCKETSHIP'))
fitting_gui

Load the image series, enter the parameter for each — echo time, flip angle, inversion time or b-value — pick the fit type and run. The GUI also builds and saves batch jobs, so a configuration worked out interactively replays later without re-entering it.

Scripted fitting¶

fitting_script.m is a template — copy it, edit the block at the top, run it:

file_list       = {'echo1.nii';'echo2.nii';'echo3.nii'};  % one file per parameter value
parameter_list  = [10 20 30]';        % ms or degrees, matching file_list
fit_type        = 't2_exponential';   % see the table above
tr              = 20;                 % ms — only used by the T1 FA fits
rsquared_threshold = 0.2;             % fits below this are written as -1
data_order      = 'xyzfile';          % or 'xynz', 'xyzn' for a single 4D file
number_cpus     = 4;
roi_list        = '';                 % restrict the fit to ROIs instead of every voxel
xy_smooth_size  = 0;                  % in-plane smoothing before fitting, in voxels
odd_echoes      = 0;                  % fit only odd-numbered parameters

Get data_order right first: xyzfile means one 3D file per parameter value, while xynz and xyzn describe a single file holding the whole series, differing in whether the parameter dimension precedes or follows the slice dimension.

Restricting to roi_list is worth doing on large volumes — whole-brain voxelwise fitting with confidence intervals is the slow path.

What it writes¶

Beside the input, named from output_basename and the fit:

Batch processing¶

calculateMap_batch.m runs a list of jobs unattended; makeNewbatch.m and load_batch.m build and reload them. Jobs saved from the GUI reload the same way, which is the intended route from one worked case to a whole study. parallelFit.m distributes fitting across the cores set by number_cpus.