Python Walkthrough¶

This guide covers running the Python implementation of ROCKETSHIP, which is the recommended interface for new work. It describes environment setup, the command line and graphical interfaces for DCE and parametric analysis, and the outputs each produces.

All commands are run from the repository root.

Available interfaces¶

1. Environment setup¶

The installer creates a virtual environment, installs dependencies, and adds the optional acceleration libraries for your platform:

python3 install.py

It also writes rocketship_dce.sh and rocketship_parametric.sh (.bat on Windows) into the repository root, each a wrapper that activates the virtual environment and launches a GUI:

./rocketship_dce.sh          # DCE GUI
./rocketship_parametric.sh   # parametric T1 GUI

MATLAB is optional. If it is not on PATH, the installer warns that the MATLAB MEX files could not be verified and finishes successfully; the Python interfaces are unaffected.

See GPU and CPU Acceleration for platform support and installer options.

To set up the environment manually, without acceleration:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip setuptools wheel
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip install -r requirements_gui.txt

The requirements_gui.txt file is needed only for the graphical interfaces.

2. DCE analysis from the command line¶

Run with the built-in example configuration:

.venv/bin/python run_dce_python_cli.py

Run with your own configuration file:

.venv/bin/python run_dce_python_cli.py --config my_study_config.json

Individual settings can be overridden at run time without editing the configuration file. Each --set argument takes one key=value pair:

.venv/bin/python run_dce_python_cli.py --config my_study_config.json --set blood_t1_ms=1600

Every available option is documented in the DCE Options reference.

Outputs¶

Stage checkpoint files are written when a checkpoint directory is configured, allowing a run to be resumed or a later stage to be repeated without recomputing the earlier ones.

3. Parametric \(T_1\) mapping from the command line¶

.venv/bin/python run_parametric_python_cli.py

Outputs are a run record (parametric_t1_run.json), an event log (parametric_t1_events.jsonl), the \(T_1\) map, and a map of the coefficient of determination for the fit at each voxel.

A \(T_1\) map is required input for DCE analysis, so this step normally comes first.

4. Graphical interfaces¶

Activate the environment, then launch either interface:

source .venv/bin/activate
python run_dce_python_gui.py

source .venv/bin/activate
python run_parametric_python_gui.py

The DCE interface is organized into four tabs:

• Inputs — select images, masks and maps, and set acquisition and fitting options.
• CLI Output — the run log as it is produced.
• QC Figures — the quality control figures described above.
• Results — a slice viewer for the resulting parameter maps and dynamic series.

Configurations built in the interface can be saved and reused from the command line, which is the usual route from exploratory analysis to batch processing.

5. Working with BIDS datasets¶

To enumerate the sessions available in a BIDS dataset and write a manifest:

.venv/bin/python run_bids_discovery.py \
  --bids-root /path/to/bids_dataset \
  --output-json out/bids_manifest.json \
  --print-json

The manifest can then be used to drive batch processing across the dataset with run_dce_bids_batch.py.

6. Acquisition metadata¶

DCE analysis requires the repetition time, flip angle and temporal resolution of the dynamic series. These are read from the JSON sidecar accompanying the images wherever one is present, which is the recommended arrangement.

Where no sidecar is available, all three must be supplied manually, through the tr_ms, fa_deg and time_resolution_sec options. Supplying only some of them alongside a sidecar is rejected: set all three, or none.

Contrast agent relaxivity and haematocrit follow the opposite precedence, since they describe the scan rather than the analysis. A value in the image sidecar takes priority over the run configuration. Relaxivity has no default and must be supplied; see Signal to Concentration.

7. Running the test suite¶

.venv/bin/python -m pytest tests/python -q

Further reading¶

• DCE Options reference — every configuration option
• Pharmacokinetic models — model equations and selection
• Signal to Concentration — the conversion and its inputs
• GPU and CPU Acceleration — installation and backend selection