MyBids

MyBids is a comprehensive toolkit and example repository for working with neuroimaging data in the Brain Imaging Data Structure (BIDS) format. It bundles a demonstration BIDS dataset together with command‑line utilities and pipeline scripts so you can convert raw DICOM files, organize data, and run end‑to‑end analyses — all from a single, unified environment. There are two main components:

1. MyBidsApp – a collection of Python packages providing command line tools for BIDS data (bidscomatic-cli, dicomatic-cli, cbrain-cli, and the bids umbrella). These packages live in code/MyBidsApp/. See the detailed MyBidsApp README for installation and usage instructions for each tool.
2. Shell scripts – helper scripts for preprocessing and analysing neuroimaging data with FSL, FreeSurfer and related utilities. Scripts reside in code/scripts/ and work with the BIDS dataset stored at the repository root. See the Shell Scripts README for usage details.

Key Features

Category	Description
DICOM → BIDS Conversion	bidscomatic-cli delivers end-to-end DICOM study orchestration — extraction, conversion, curation, preprocessing, QC & validation — so raw scans land in a polished, BIDS-compliant layout.
DICOM Archive Querying	dicomatic-cli connects to PACS/XNAT archives, letting you search and download series by patient, study, or accession number.
CBRAIN Pipeline Launcher	cbrain-cli submits and monitors jobs on the CBRAIN HPC platform (e.g. HippUnfold), handles upload/download, and writes outputs back into derivatives/ following BIDS.
Unified Command Hub	A single bids umbrella command re‑exports the three tools above, providing bids bidscomatic …, bids dicomatic …, and bids cbrain … for shell‑completion convenience.
fMRI Processing Scripts	Bash helpers under code/scripts/ run local preprocessing (skull‑stripping, TOPUP, ICA‑AROMA) and FSL FEAT first‑, second‑, and third‑level stats.
Project Initialisation	init_bids_project.sh spins up a clean project folder, virtual environment, and dataset_description.json skeleton in one command.
Templates & Configs	Ready‑made FEAT design files (design_files/) and YAML configs (config/) offer sensible defaults you can tweak.

Uploads from the derivatives/ tree behave like regular BIDS uploads—the leading derivatives/ component is stripped so files appear alongside the rest of the dataset on the remote SFTP server.

Technology Stack

• Python ≥ 3.9 — CLI tools (packaged in MyBidsApp)
• Bash — helper scripts (macOS 12+, Ubuntu 22.04, or WSL 2)
• BIDS Validator (Node.js) — compliance checking
• dcm2niix — DICOM ➜ NIfTI conversion
• FSL (BET, TOPUP, FEAT, fslmaths, etc.)
• FreeSurfer (SynthStrip optional skull‑strip)
• ICA‑AROMA — motion artefact removal (Docker image supplied)
• Docker — optional containerised pipelines
• CBRAIN — external HPC processing
• PACS / XNAT — remote DICOM archives

1 — Clone the repository

git clone https://github.com/rgabiazo/MyBids.git
cd MyBids

2 — Create & activate a virtual environment

python -m venv .venv
source .venv/bin/activate

3 — Install the tools or start a new project

Choose one of the following setups:

Option A — Install in this repository

./code/MyBidsApp/dev_install.sh    # installs umbrella `bids` command

Verify:

bids --version
bids --help

Need only one sub‑tool? Install it in editable mode, e.g.:

pip install -e code/bidscomatic

Note: FSL, Node.js (for the validator), and other externals must already be on your $PATH.

Option B — Bootstrap a new BIDS project

./code/MyBidsApp/init_bids_project.sh --name "My Study" --author "Alice Example"

The helper renames the folder, creates .venv with all tools installed and writes dataset_description.json before dropping you into an activated shell.

Usage Overview

The bids umbrella command exposes three sub‑commands, all of which accept --help:

Command	Purpose
bids bidscomatic <dicom_src> <bids_dst>	Run the end-to-end DICOM orchestration toolkit to extract, convert, curate, preprocess, QC and validate a study into BIDS.
bids dicomatic fetch --patient-id <ID> --series "<pattern>" <outdir>	Query & download from PACS/XNAT.
bids cbrain --launch-tool hippunfold …	Submit CBRAIN jobs and retrieve outputs (e.g. HippUnfold or fMRIPrep).

Example end‑to‑end workflow

# 1 Pull DICOM series by Study UID
bids dicomatic fetch --study-uid <UID> ./scratch/dicoms

# 2 Convert to BIDS format
bids bidscomatic ./scratch/dicoms /data/MyStudy

# 3 Launch HippUnfold on CBRAIN for subject sub-001
bids cbrain-cli \
--launch-tool hippunfold \
--tool-param modality=T1w \
--launch-tool-batch-group MyStudy \
--launch-tool-batch-type BidsSubject \
--launch-tool-bourreau-id 56 \
--launch-tool-results-dp-id 51 

# 4 Download the derivatives
bids cbrain --download-tool hippunfold --group-id MyStudy --flatten

Local analysis scripts

# Preprocess fMRI
./code/scripts/fmri_preprocessing.sh

# First‑level stats
./code/scripts/feat_first_level_analysis.sh

# Second‑ & third‑level group stats
./code/scripts/second_level_analysis.sh
./code/scripts/third_level_analysis.sh

All scripts display a usage prompt when run without arguments.

Contributing

Pull requests are welcome! Please file an issue first for major changes. Ensure any new dependencies are documented and that pipelines still produce BIDS‑valid output.

License

This project is released under the MIT License. See LICENSE for details.

Acknowledgements & Citations

If you use MyBids or the bundled scripts, please cite the original tool authors. Key references include:

• DeepPrep — Ren J et al. Nat Methods 22(3), 473–476 (2025)
• SynthStrip — Hoopes A et al. NeuroImage 260, 119474 (2022)
• HippUnfold — de Kraker L et al. eLife 11, e77945 (2022)
• fMRIPrep — Esteban O et al. Nat Methods 16(1), 111–116 (2019)
• Boutiques — Glatard T et al. GigaScience 7(5), giy016 (2018)
• BIDS — Gorgolewski KJ et al. Sci Data 3, 160044 (2016)
• dcm2niix — Li X et al. Front. Neuroinform. 10, 30 (2016)
• ICA-AROMA — Pruim RHR et al. NeuroImage 112, 267–277 (2015)
• CBRAIN — Sherif T et al. Front. Neuroinform. 8, 54 (2014)
• FSL — Jenkinson M et al. NeuroImage 62(2), 782–790 (2012)
• FreeSurfer — Fischl B. NeuroImage 62(2), 774–781 (2012)

Special thanks to Dr. Lindsay Nagamatsu and the Exercise, Mobility, and Brain Health Lab at Western University for their feedback and computing resources.