bloodstream

The goal of bloodstream is to provide a simplified and automated pipeline for processing BIDS blood data for PET. The bloodstream package is based on functions found in kinfitr, but strings them together into a blood processing pipeline, producing a parameterised report as well as processed blood derivatives.

bloodstream can be used in two ways:

• Interactive Mode: Define configuration files using a graphical user interface through a web browser
• Non-Interactive Mode: Automated pipeline execution using pre-defined configurations

For a short introduction to processing blood data for PET, as well as tutorial for how to use bloodstream, I've recorded an explainer video, which should help you get started.

NOTE: The previous web-based bloodstream configuration file definition tool has been deprecated in favour of running the configuration file definition locally using the package itself.

Installation

bloodstream can be used in two ways:

• R Package Usage: Install and use directly in R
• Docker Usage: Use as a standalone containerized BIDS app without installing R or the package dependencies locally

Usage

Pipeline Workflow Summary

Step	R Usage	Docker Usage
Run without config	bloodstream(bids_dir) → linear interpolation	docker run ... → linear interpolation
Run with config	bloodstream(bids_dir, configpath) → fits models	docker run -v my_config.json:/config.json ... → fits models
Launch config app (standalone)	bloodstream_interactive() → design and download config	docker run -p 3838:3838 ... --mode interactive → design and download config
Launch config app (with data)	bloodstream_interactive(bids_dir = "/path/to/study") → design, run, or linear interpolation	docker run -p 3838:3838 -v /path/to/bids:/data/bids_dir:ro -v /path/to/derivatives:/data/derivatives_dir:rw ... --mode interactive → design, run, or linear interpolation
Run pipeline after config	Use saved config with bloodstream()	Use saved config with Docker run

R Package Usage

Installation

You can install the development version of bloodstream like so:

remotes::install_github("mathesong/bloodstream")

Function Parameters

The bloodstream function accepts several parameters:

• bids_dir: The location of the BIDS data, e.g. ../ds004230 (relative or full paths are allowed).
• configpath: The path to the bloodstream configuration file, which specifies the modelling choices. If left blank or NULL, the blood data will be combined using linear interpolation only.
• derivatives_dir: Path to derivatives directory. If NULL, uses bids_dir/derivatives.
• analysis_foldername: Name for the analysis subfolder (default: "Primary_Analysis").

Pipeline Execution

The pipeline can be called as follows:

library(bloodstream)

# Basic usage with default config (linear interpolation)
bloodstream(bids_dir)

# With custom config
bloodstream(bids_dir, configpath)

# With custom analysis folder name
bloodstream(bids_dir, configpath, analysis_foldername = "my_analysis")

# With separate derivatives directory
bloodstream(bids_dir, configpath, derivatives_dir = "/path/to/derivatives")

Interactive Configuration

You can launch the interactive configuration interface directly from R:

library(bloodstream)

# Standalone config creation (no BIDS data needed)
bloodstream_interactive()

# With BIDS directory (enables pipeline execution, auto-derives derivatives)
bloodstream_interactive(bids_dir = "/path/to/study")

# With separate BIDS and derivatives directories
bloodstream_interactive(bids_dir = "/path/to/study", derivatives_dir = "/path/to/derivatives")

# Load existing config for modification
bloodstream_interactive(bids_dir = "/path/to/study", configpath = "/path/to/config.json")

# Custom analysis folder name
bloodstream_interactive(bids_dir = "/path/to/study", analysis_foldername = "my_analysis")

The interactive app allows you to:

• Create and modify configuration files using a graphical interface
• Load existing configurations for editing
• Download configuration files
• Run the bloodstream pipeline with custom configurations OR with linear interpolation (when BIDS directory is provided)
• Work in standalone mode for config creation only (when no BIDS directory is provided)

It will generate the following outputs:

• A report showing all the code and functions used, as well as plots before and after processing (either modeling or linear interpolation).

... and for all individual PET measurements, the following

• Tabular tsv output (*_inputfunction.tsv) containing the estimated data (either model-fitted or linearly interpolated) which can be used for pharmacokinetic modelling.
• JSON sidecar accompanying the tabular tsv data (*_inputfunction.json).
• Model configuration JSON files, containing the models used and fit parameters if applicable (*_config.json).

Docker

The bloodstream Docker image is available on Docker Hub at mathesong/bloodstream:latest.

You can pull the pre-built image:

docker pull mathesong/bloodstream:latest

Alternatively, you can build the container locally using the file docker/dockerfile:

docker build -f docker/dockerfile -t mathesong/bloodstream:latest . --platform linux/amd64

The bloodstream-docker wrapper

The easiest way to drive the image is the bloodstream-docker command-line wrapper, which turns a BIDS-App-style command into the matching docker run invocation, mapping your directories into the container for you:

pip install bloodstream-docker

# Launch the config app, which can also run the pipeline
bloodstream-docker /path/to/bids /path/to/derivatives participant

# Run the pipeline with a config file
bloodstream-docker /path/to/bids /path/to/derivatives participant \
  --config /path/to/config.json \
  --automatic

Run bloodstream-docker --help to see all options, and --dry-run to print the command it would run. It also generates Apptainer commands, with --apptainer. The raw docker run commands below all remain available.

Docker Usage

The Docker container supports both interactive and non-interactive modes:

Interactive Mode (Configuration Interface)

Standalone Config Creation (no BIDS data needed):

# Create and download configs without any data directories
docker run -p 3838:3838 \
  mathesong/bloodstream:latest --mode interactive

Interactive Mode with BIDS Data (enables pipeline execution):

# Full interactive mode with BIDS data (enables config creation, pipeline with config, or linear interpolation)
# BOTH bids_dir and derivatives_dir are required to enable pipeline execution from the app
docker run -p 3838:3838 \
  -v /path/to/bids/dir:/data/bids_dir:ro \
  -v /path/to/derivatives:/data/derivatives_dir:rw \
  mathesong/bloodstream:latest --mode interactive

Note: With BIDS directory provided, configs are saved to derivatives folder AND available for download.

Load Existing Config:

# Interactive mode with existing config (auto-detected)
docker run -p 3838:3838 \
  -v /path/to/bids/dir:/data/bids_dir:ro \
  -v /path/to/derivatives:/data/derivatives_dir:rw \
  -v /path/to/my_config.json:/config.json:ro \
  mathesong/bloodstream:latest --mode interactive

Then open http://localhost:3838 in your browser to access the configuration interface.

Non-Interactive Mode (Direct Pipeline Execution)

Run the pipeline with default settings (linear interpolation):

# Non-interactive with default config (linear interpolation)
docker run \
  -v /path/to/bids/dir:/data/bids_dir:ro \
  -v /path/to/derivatives:/data/derivatives_dir:rw \
  mathesong/bloodstream:latest

Run with a custom configuration file (fits models):

# Non-interactive with custom config (fits models, auto-detected)
docker run \
  -v /path/to/bids/dir:/data/bids_dir:ro \
  -v /path/to/derivatives:/data/derivatives_dir:rw \
  -v /path/to/my_config.json:/config.json:ro \
  mathesong/bloodstream:latest

Run with custom analysis folder name:

# Non-interactive with custom config and folder name (fits models)
docker run \
  -v /path/to/bids/dir:/data/bids_dir:ro \
  -v /path/to/derivatives:/data/derivatives_dir:rw \
  -v /path/to/my_config.json:/config.json:ro \
  mathesong/bloodstream:latest \
  --analysis_foldername "Model_AIF"

Below are two examples of running the app for a real folder:

# Interactive mode with a custom analysis folder
docker run -p 3838:3838 \
  -v /home/granville/Repositories/OpenNeuro/ds004869/:/data/bids_dir:ro \
  -v /home/granville/Repositories/OpenNeuro/ds004869/derivatives/:/data/derivatives_dir:rw \
  mathesong/bloodstream:latest --mode interactive --analysis_foldername Secondary_Analysis
  
# Non-interactive mode with a custom analysis folder
docker run \
  -v /home/granville/Repositories/OpenNeuro/ds004869/:/data/bids_dir:ro \
  -v /home/granville/Repositories/OpenNeuro/ds004869/derivatives/:/data/derivatives_dir:rw \
  -v /home/granville/Downloads/config_test.json:/config.json:ro \
  mathesong/bloodstream:latest --analysis_foldername Tertiary_Analysis

Docker Command Line Options

• --mode: Execution mode (interactive or non-interactive [default])
• --config: Path to a config file (auto-detected at /config.json if mounted there)
• --analysis_foldername: Custom name for analysis subfolder (overrides config filename)
• --bids_dir / --derivatives_dir: Explicit paths inside the container, instead of the /data/bids_dir and /data/derivatives_dir mount points (useful with Apptainer's home auto-mounts)

Docker File Permissions Note

On Linux systems, if you encounter permission issues where output files are owned by root, you have two options:

1. Add the user flag to run the container with your user ID:

   docker run --user $(id -u):$(id -g) \
     # ... rest of your docker command

2. Fix permissions afterward using chown:

   sudo chown -R $(id -u):$(id -g) /path/to/derivatives

Docker Mount Points

• BIDS Directory (read-only): /data/bids_dir:ro - Your BIDS dataset
• Derivatives Directory (read-write): /data/derivatives_dir:rw - Output location
• Config File (optional, read-only): /config.json:ro - Auto-detected configuration file

Analysis Folder Structure

Outputs are organised in analysis folders within derivatives/bloodstream/:

derivatives/bloodstream/
├── Primary_Analysis/              # Default analysis folder name
├── pf_bpr_mod/                    # Custom named via --analysis_foldername  
└── another_analysis/              # Another custom analysis

The default analysis folder name is "Primary_Analysis". You can customise this using the --analysis_foldername parameter in Docker or the analysis_foldername parameter in R functions.

Once complete, all outputs from the bloodstream analysis will be located in the derivatives/bloodstream/<analysis_folder>/ directory.

Apptainer

bloodstream can also be run using Apptainer (formerly Singularity), which is often preferred on HPC (high-performance computing) systems.
The Apptainer image can be built directly from the existing Docker image, or downloaded and used as-is.

Build or pull the image

To build the container from Docker Hub and save it as a local .sif file:

apptainer build bloodstream.sif docker://mathesong/bloodstream:latest

The bloodstream-docker wrapper generates Apptainer commands as well as Docker ones:

bloodstream-docker /path/to/bids /path/to/derivatives participant \
  --apptainer \
  --config /path/to/config.json \
  --automatic \
  --image bloodstream.sif

The definition file in apptainer/bloodstream.def is there if you need to build the image from source rather than converting the Docker one.

Running bloodstream (no config file)

Bind your BIDS dataset and a writable derivatives directory to the container. If no configuration file is provided, bloodstream will default to using linear interpolation only.

apptainer run \
  --bind /path/to/bids:/data/bids_dir:ro \
  --bind /path/to/derivatives:/data/derivatives_dir:rw \
  bloodstream.sif

All outputs will be stored in /path/to/derivatives/bloodstream/Primary_Analysis/.

Running with a configuration file

To run with model fitting, bind a configuration file to /config.json:

apptainer run \
  --bind /path/to/bids:/data/bids_dir:ro \
  --bind /path/to/derivatives:/data/derivatives_dir:rw \
  --bind /path/to/config.json:/config.json:ro \
  bloodstream.sif

Custom analysis folder name

apptainer run \
  --bind /path/to/bids:/data/bids_dir:ro \
  --bind /path/to/derivatives:/data/derivatives_dir:rw \
  --bind /path/to/config.json:/config.json:ro \
  bloodstream.sif --analysis_foldername "my_analysis"

Citation

Until there is a preprint or publication about bloodstream, please just specify that "bloodstream was used for blood analysis, which is a blood processing pipeline built around kinfitr [REF]".

To cite kinfitr, please cite at least one of the following:

An introduction to the package:

Matheson, G. J. (2019). Kinfitr: Reproducible PET Pharmacokinetic Modelling in R. bioRxiv: 755751. https://doi.org/10.1101/755751

A validation study compared against commercial software:

Tjerkaski, J., Cervenka, S., Farde, L., & Matheson, G. J. (2020). Kinfitr – an open source tool for reproducible PET modelling: Validation and evaluation of test-retest reliability. EJNMMI Res 10, 77 (2020). https://doi.org/10.1186/s13550-020-00664-8