petfit-docker

petfit-docker is a lightweight Python wrapper that turns a BIDS-App-like command line into the matching docker run invocation for PETFit. Interactive Shiny mode is the default; use --automatic or --mode automatic to run a non-interactive pipeline.

petfit-docker /path/to/bids /path/to/derivatives participant \
  --app modelling_plasma \
  --blood-dir /path/to/blood \
  --analysis-foldername Primary_Analysis

The command above runs:

docker run --rm -it \
  -p 3838:3838 \
  -v /path/to/bids:/data/bids_dir:ro \
  -v /path/to/derivatives:/data/derivatives_dir:rw \
  -v /path/to/blood:/data/blood_dir:ro \
  mathesong/petfit:latest \
  --func modelling_plasma --mode interactive

Installation

pip install petfit-docker

Run petfit-docker --help at any time to see all available options, including descriptions of each app and analysis folder:

petfit-docker --help

Examples

Launch the default region definition app:

petfit-docker /path/to/bids /path/to/derivatives/petfit participant

The three positional arguments follow the BIDS App convention:

petfit-docker <bids_dir> <output_dir> participant

Launch region definition:

petfit-docker /path/to/bids /path/to/derivatives participant --app regiondef

The positional output_dir can be either the derivatives root or the final PETFit output directory. These are equivalent with the default output folder name:

petfit-docker /path/to/bids /path/to/derivatives/petfit participant
petfit-docker /path/to/bids /path/to/derivatives participant --app regiondef
petfit-docker /path/to/bids /path/to/derivatives/petfit participant --app regiondef

Launch plasma-input modelling:

petfit-docker /path/to/bids /path/to/derivatives participant \
  --app modelling_plasma \
  --blood-dir /path/to/blood

Run plasma-input modelling automatically:

petfit-docker /path/to/bids /path/to/derivatives participant \
  --app modelling_plasma \
  --blood-dir /path/to/blood \
  --automatic

Run modelling from a config file kept outside the dataset:

petfit-docker /path/to/bids /path/to/derivatives participant \
  --app modelling_ref \
  --automatic \
  --analysis-foldername Shared_Settings \
  --config-file /path/to/petfit_config.json

The wrapper bind-mounts that single file into the container, where PETFit copies it into the analysis folder as desc-petfitoptions_config.json before running, so the settings which produced the outputs sit beside them. The analysis folder is created if it does not exist yet, so an external config can start a fresh analysis. The console reports the copy, and says so explicitly when it replaced a config already in that folder.

The region definition app takes an external petfit_regions.tsv the same way:

petfit-docker /path/to/bids /path/to/derivatives participant \
  --app regiondef \
  --automatic \
  --regions-file /path/to/petfit_regions.tsv

Each of the two belongs to one app: --config-file is ignored by regiondef, and --regions-file is ignored by the modelling apps.

Merging runs

Region definition pools a measurement's runs into one measurement by default, for the common case where run-01 and run-02 are two scanning occasions from a single injection. The run entity is then absent from the outputs. Pass --no-merge-runs for datasets where each run is a separate injection:

petfit-docker /path/to/bids /path/to/derivatives participant \
  --app regiondef \
  --automatic \
  --no-merge-runs

The option belongs to regiondef alone, and is ignored by the modelling apps.

Open a shell in the image:

petfit-docker --shell -i mathesong/petfit:latest

Patching a local petfit

Use --patch (or -f) to point the wrapper at a local petfit checkout and test your local changes without rebuilding the image. The wrapper bind-mounts the source into the container, where it is reinstalled from source at startup so it overrides the petfit baked into the image:

petfit-docker /path/to/bids /path/to/derivatives participant \
  --app modelling_ref \
  --patch /path/to/your/petfit/checkout

This mirrors the --patch option of the PETPrep Docker wrapper. Because petfit is an R package it is reinstalled (not run directly from source), so the first few seconds of startup are spent installing the patched package. The patch works with every mode, including --shell.

Apple Silicon

The published PETFit Docker images are currently linux/amd64 only. The wrapper therefore requests --platform linux/amd64 by default, which avoids Docker's platform-mismatch warning on Apple Silicon while running under emulation. If a native or multi-architecture image is published later, override the platform with --platform linux/arm64 or disable the explicit platform with --platform "".