dce2bids

Turn DCE-MRI scans from the scanner into a tidy, standard folder layout — with an AI assistant doing the fiddly per-scanner setup for you.

What it does

dce2bids converts the scans you need for a DCE-MRI study into BIDS:

• the dynamic DCE series (the 4D contrast scan),
• the VFA flip-angle scans (used for T1 mapping), and
• one structural scan (usually a T1 MPRAGE).

Everything else in the session is left out. Because every scanner labels its scans and parameters a little differently, and every protocol contains different sequences, an AI assistant figures out the right settings once per scanner/protocol and saves them. After that, converting each new participant is a single command — no AI needed.

Requirements

This is written for Linux. It has been tested on Ubuntu 22.04, and Claude Code Opus 4.8 effort high. It may work on Mac and Windows with WSL2, but this is untested.

This tool requires an LLM agent to customize the scripts for your particular data.

It has been designed to work with a paid subscription to one of the following:

• Claude Code
• Codex
• Visual Studio Code with Copilot
• Cursor

Other general-purpose coding agents will likely also work as long as they can read and interpret the SKILL.md file.

One-time setup

git clone https://github.com/petmri/dce2bids.git
cd dce2bids
env/bootstrap.sh        # Optional, installs the conversion tools into a local folder

The env/bootstrap.sh step is optional as the agent will run it for you in the next step. However, running it yourself will let you know if the environment is properly configured before starting. You can run it multiple times; it skips the work if everything's already there.

Using it

A new scanner or protocol (with the AI assistant)

Open the coding agent (e.g. Claude Code) in the dce2bids folder, give it access to your data folder (optional, it will prompt you to provide access if you don't), and put the following request in the chat with the full path to your data:

Convert all the DICOMs in /data/study-1/ to BIDS using dce2bids. The contrast agent [insert contrast agent used] was used for all DCE scans.

Please specify the contrast agent used for your study. If you leave it blank, the script will check the DICOM headers for the contrast agent, but if it is missing, it will raise an error and stop the conversion. If the contrast agent varies by subject/date, describe this to the agent and it will include this customization in the conversion.

A scanner you've already set up (no AI needed)

After the first run, a custom script is saved in the code/ folder for future runs without the agent (for example, if you get more cases). This can be run with:

/data/study-1_bids/code/run_dce2bids.sh

Output

The dce2bids tool will sort the DICOM files, automatically determine which sequences to use, convert the files to NIfTI format, organize them in a BIDS structure, and check the results. By default, the output will be next to the input folder, for example the output will be /data/study-1_bids if the input is /data/study-1/.

study-1_bids/            # the actual BIDS dataset root
├── sourcedata/          # sorted DICOM files
├── dataset_description.json
├── participants.tsv
├── participants.json
├── README
├── CHANGES
├── .bidsignore
├── code/
│   ├── run_dce2bids.sh  # the script to run for future cases
│   ├── selection.tsv    # what sequences were converted and which ones were skipped
│   └── bids_status_report.txt  # the result of the conversion
├── sub-*/               # subject folders with BIDS data
└── derivatives/         # future processing will go here

Did it work?

A full report is saved in code/bids_status_report.txt with the results of the conversion.

To verify the folder again, run:

scripts/verify_bids.py <your-bids-folder>

Green ✓ everywhere and 0 fail means you're good. Any ✗ or ⚠ tells you in plain terms what to look at.

Getting help

Ask the AI assistant — it knows this tool's steps and can run them for you, explain a warning, or set up a new scanner. For the technical design and internals, see DESIGN.md.