Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rubick65/dcemapper/llms.txt

Use this file to discover all available pages before exploring further.

The Brain Imaging Data Structure (BIDS) is a community standard for organising neuroimaging and MRI datasets into a predictable, self-describing folder hierarchy. By adopting BIDS conventions, research groups can share datasets, run automated pipelines, and reproduce results without writing custom file-discovery logic. DCEMapper supports BIDS-style datasets natively: it can scan a dataset directory to auto-detect all subjects and sessions, load their DCE-MRI NIfTI files in sequence, and write all output parametric maps into a BIDS-compliant derivatives/ folder. It can also convert raw Bruker scanner exports into a BIDS-like NIfTI structure in a single step.

​
Expected Directory Structure

DCEMapper expects a directory layout that follows BIDS subject/session/modality nesting. Both session-level and session-less layouts are supported: 
dataset/
  sub-001/
    ses-baseline/
      func/
        sub-001_ses-baseline_acq-dce_run-1_dce.nii.gz
  sub-002/
    func/
      sub-002_acq-dce_run-1_dce.nii.gz
  derivatives/
Key conventions:
  • Subject folders are prefixed with sub- followed by an alphanumeric identifier.
  • Session folders (optional) are prefixed with ses- and nest directly inside the subject folder.
  • Modality folders (func/, anat/, dwi/, etc.) sit inside the subject or session folder.
  • File names follow the BIDS entity pattern: sub-<label>[_ses-<label>]_acq-<label>_run-<index>_<suffix>.nii.gz.
  • Derivatives are written to a top-level derivatives/ folder, keeping raw and processed data cleanly separated.

​
How DCEMapper Reads BIDS

When you select File → Open → Open BIDS in the application, DCEMapper calls get_files_to_process(), which recursively scans the chosen directory for NIfTI files that match DCE naming conventions. For each file found:
  1. The subject label is extracted from the file path using get_correct_subject(), which parses the sub-<label> component of the path or filename.
  2. All detected files are added to an internal file list, grouped by subject.
  3. The Next and Previous navigation buttons become active, allowing you to step through each subject’s data without reopening the file dialog.
This means that opening a BIDS dataset once is enough to queue every subject in the study for sequential processing — a significant time saving for large cohorts. For more detail on loading files, see Loading Data.

​
Bruker to BIDS Conversion

DCEMapper can convert raw Bruker MRI scanner data — stored as subject parameter files or ZIP archives — directly into a BIDS-like NIfTI structure. The conversion is triggered via File → Open → Bruker Conversion and calls: 
convert_studies_from_bruker(input_dir, output_dir)
The function:
  1. Discovers studies by recursively searching input_dir for folders containing a subject file, or for .zip archives.
  2. Identifies the modality of each scan (DCE, T1, T2, DWI, etc.) by inspecting the acquisition method and echo time parameters.
  3. Normalises subject and session identifiers to BIDS format (sub-<ID>_ses-<session>).
  4. Saves each scan as a matched .nii.gz + .json pair. Timing metadata (RepetitionTime, EchoTime, InversionTime) is automatically converted from milliseconds to seconds to comply with the BIDS specification.
  5. Skips already-processed subjects when skip_existing=True (the default), making the conversion safe to re-run after adding new data.
The output is written under output_dir/sourcedata/: 
output_dir/
  sourcedata/
    sub-B060326_ses-baseline/
      func/
        sub-B060326_ses-baseline_acq-1_run-1_dce.nii.gz
        sub-B060326_ses-baseline_acq-1_run-1_dce.json
Each .json sidecar file contains BIDS-compliant metadata fields extracted from the Bruker parameter files, including SubjectID, SessionID, Date, ReceiverGain, and standard MRI sequence parameters. For DWI scans, corresponding .bvec and .bval files are also exported automatically. If any scans fail conversion (e.g., unrecognised modality or corrupted data), a conversion_report.log file is written to output_dir/ listing each error with its scan identifier — no individual failure aborts the rest of the batch.

​
Derivatives Folder

All outputs produced by DCEMapper’s preprocessing and semi-quantitative mapping pipeline are saved into a derivatives/ subfolder, organised by subject name. This keeps processed files cleanly separated from raw source data and follows standard BIDS derivatives conventions. Typical derivative filenames produced for a single subject:
FileContent
<name>_preproc.nii.gzPreprocessed (denoised / Gibbs-corrected) 4D volume
<name>_rce_process.nii.gz4D Relative Contrast Enhancement map
<name>_rce_max_process.nii.gz3D Maximum RCE map
<name>_tto_rce_max_process.nii.gz3D Time to Peak RCE map (normalised)
These derivative NIfTI files can be reloaded directly in DCEMapper via File → Open → Processed Files for further inspection or overlay with the original data.
Full BIDS compliance requires strictly consistent naming conventions throughout the dataset. DCEMapper recognises the most common BIDS-style patterns, but may not handle all edge cases — for example, unusual subject ID formats, deeply nested session structures, or non-standard suffix labels. If files are not detected automatically, verify that filenames follow the sub-<label>_..._<suffix>.nii.gz pattern and that the BIDS hierarchy is no more than four levels deep.

Build docs developers (and LLMs) love

Get started for freeTalk to us