bidspm

This is a Matlab / Octave toolbox to perform MRI data analysis on a BIDS data set using SPM12.

Installation

From docker hub

docker pull cpplab/bidspm:latest

From the source

In a terminal or a git bash prompt, type:

git clone --recurse-submodules https://github.com/cpp-lln-lab/bidspm.git

To start using bidspm, you just need to initialize it for this MATLAB / Octave session with:

bidspm()

Please see our documentation for more info.

Installing the Command line Interface (CLI)

If you want to use the BIDS app python based CLI of bidspm.

You need to

python3
pip

If you are using MATLAB, you need to edit the file src/matlab.py, so that it returns the fullpath to the MATLAB executable on your computer.

You can then install the bidspm CLI from within the bidspm folder with:

pip install .

You can then type the following to see which command you have access to:

bidspm --help

BIDS validation

After installing bidspm python package, you can get access to extra validation options.

BIDS stats model validation

Please see the documentation

BIDS dataset validation

To run the bids-validator when running bidspm, you will need:

node.js and npm
the bidspm python CLI (see above)

You can then install:

the bids validator

by running from the command line in the root folder of the repository:

make install

or

npm install -g bids-validator

Usage

For some of its functionality bidspm has a BIDS app like API.

See this page for more information.

But in brief they are of the form:

bidspm(bids_dir, output_dir, ...
        'analysis_level', ...
        'action', 'what_to_do')

Creating a default BIDS statistical model

Use a MATLAB / Octave script with:

% path to your raw BIDS dataset
bids_dir = path_of_raw_bids_dataset;

% where you want to save the model
output_dir = path_where_the_output_should_go;

tasks_to_include_in_model = {'task1', 'task2', 'task3'};

% for example 'MNI152NLin2009cAsym'
space_to_include_in_model = {'spaceName'};

bidspm(bids_dir, output_dir, 'dataset', ...
        'action', 'default_model', ...
        'task', tasks_to_include_in_model, ...
        'space', space_to_include_in_model)

GLM

Use a MATLAB / Octave script with:

% path to your raw BIDS dataset
bids_dir = path_of_raw_bids_dataset;

% where you want to save the model
output_dir = path_where_the_output_should_go;

preproc_dir = path_to_preprocessed_dataset; % for example fmriprep output

model_file = path_to_bids_stats_model_json_file;

subject_label = '01';

bidspm(bids_dir, output_dir, 'subject', ...
        'participant_label', {subject_label}, ...
        'action', 'stats', ...
        'preproc_dir', preproc_dir, ...
        'model_file', model_file)

Preprocessing

bids_dir = path_to_raw_bids_dataset;
output_dir = path_to_where_the_output_should_go;

subject_label = '01';

bidspm(bids_dir, output_dir, 'subject', ...
        'participant_label', {subject_label}, ...
        'action', 'preprocess', ...
        'task', {'yourTask'})

Features

Statistics

The model specification are set up using the BIDS stats model and can be used to perform:

whole GLM at the subject level
whole brain GLM at the group level à la SPM (meaning using a summary statistics approach).
ROI based GLM (using marsbar)
model selection (with the MACS toolbox)

Preprocessing

If your data is fairly “typical” (for example whole brain coverage functional data with one associated anatomical scan for each subject), you might be better off running fmriprep on your data.

If you have more exotic data that cannot be handled well by fmriprep then bidspm has some automated workflows to perform amongst other things:

remove dummies
slice timing correction
spatial preprocessing:
- realignment OR realignm and unwarp
- coregistration func to anat,
- anat segmentation and skull stripping
- (optional) normalization to SPM’s MNI space
smoothing
fieldmaps processing and voxel displacement map creation (work in progress)

All (well almost all) preprocessed outputs are saved as BIDS derivatives with BIDS compliant filenames.

Quality control:

anatomical data (work in progress)
functional data (work in progress)
GLM auto-correlation check

Please see our documentation for more info.

Citation

@software{bidspm,
  author = {Gau, Rémi and Barilari, Marco and Battal, Ceren and Rezk, Mohamed and Collignon, Olivier and Gurtubay, Ane and Falagiarda, Federica and MacLean, Michèle and Cerpelloni, Filippo and Shahzad, Iqra and Nunes, Márcia and Caron-Guyon, Jeanne and Chouinard-Leclaire, Christine and Yang, Ying and Mattioni, Stefania and Van Audenhaege, Alice and Matuszewski, Jacek},
  license = {GPL-3.0},
  title = {{bidspm}},
  url = {https://github.com/cpp-lln-lab/bidspm},
  version = {3.1.0}
}

Posters

OHBM 2023

Contributors

Thanks goes to these wonderful people (emoji key):

_{Alice Van Audenhaege} 🐛 📓	_{Ane Gurtubay} 💻 🎨	_{Ceren Battal} 🐛 🖋 📖 💻 👀 📓	_{Christine Chouinard-Leclaire} 🤔 🐛	_{Federica Falagiarda} 🐛 📓	_{Filippo Cerpelloni} 🐛 ⚠️ 📓	_{Iqra Shahzad} 🐛 📖 💬 👀 📓
_{Jacek Matuszewski} 🐛 📓	_{Jeanne Caron-Guyon} 🐛 💡 📓 💬 ✅	_{Manon Chateaux} 🐛	_{Marco Barilari} 💻 🎨 👀 📖 ⚠️ 🐛 📓 🤔	_{Michèle MacLean} 💻 🤔 📓 🐛	_{Mohamed Rezk} 💻 👀 🎨	_{Monique Denissen} 🐛
_{Márcia Nunes} 🐛	_{Olivier Collignon} 💻 🎨 📖 💵 🔍	_{Remi Gau} 💻 📖 🤔 🚇 🎨 👀 🐛 ⚠️ 🖋 🎨 ✅ 🚧	_{Stefania Mattioni} 🐛 📓	_{Ying Yang} 🐛 📓

This project follows the all-contributors specification. Contributions of any kind welcome!