This repository aims at centralising MATLAB/Octave tools to interact with BIDS (Brain Imaging Data Structure) datasets.
For more information about BIDS, visit https://bids.neuroimaging.io/.
See also PyBIDS for Python and the BIDS Starter Kit.
BIDS-MATLAB works with:
- Octave 5.2.0 or newer
- MATLAB R2014a or newer
We aim for compatibility with the latest stable release of Octave at any time. Compatibility can sometimes also be achieved with older versions of Octave but this is not guaranteed.
For MacOS and Unix system, using bids.copy_to_derivative
requires
a version of gunzip >= 1.6.
Download, unzip this repository and add its content to the MATLAB/Octave path.
unzip('https://github.com/bids-standard/bids-matlab/archive/main.zip');
addpath('bids-matlab-main');
Or clone it with git:
git clone https://github.com/bids-standard/bids-matlab.git
and then add it to your MATLAB/Octave path.
addpath('bids-matlab');
Stable versions should be fetched from a specific version tag or from the Mathworkds file exchange.
A new version of BIDS matlab should be released for each new version of the BIDS specification to allow for a support of new BIDS datatypes or features.
If you want the latest features of bids-matlab
that are in development are in our main
branch.
To access them you can either download the main
branch from there:
https://github.com/bids-standard/bids-matlab/tree/main
Or clone it:
git clone --branch main https://github.com/bids-standard/bids-matlab.git
-
read the layout of a BIDS dataset (see
bids.layout
), -
perform queries on that layout to get information about the subjects, sessions, runs, modalities, metadata... contained within that dataset (see
bids.query
), -
parse the layout of "BIDS-derivative compatible" datasets (like those generated by fMRIprep),
-
create BIDS compatible filenames or folder structures for raw or derivatives datasets (
bids.File
,bids.util.mkdir
,bids.dataset_description
), -
do basic copying of files to help initialize a derivative dataset to start a new analysis (
bids.copy_to_derivative
), -
generate a human readable report of the content of BIDS data set containing anatomical MRI, functional MRI, diffusion weighted imaging, field map data (see
bids.report
) -
bids.diagnostic
creates summary figures listing:- the number of files for each subject / session and imaging modality
- the number of trials for each trial type in each events.tsv file for a given task
-
read and write JSON files (see
bids.util.jsondecode
andbids.util.jsonwrite
) provided that the right dependencies are installed, -
read and write TSV files (see
bids.util.tsvread
andbids.util.tsvwrite
) -
access and query the BIDS schema (
bids.schema
) -
access, query and create basic transformations for the BIDS statistical model (
bids.Model
andbids.transformers
)
The behavior of this toolbox assumes that it is interacting with a valid BIDS
dataset that should have been validated using
BIDS-validator. If the
Node.js version of the validator is
installed on your computer,
you can call it from the matlab prompt using bids.validate
. Just be aware that
any unvalidated components may produce undefined behavior. Although, if you're
BIDS-y enough, the behavior may be predictable.
- generate human readable reports of the content of BIDS data with EEG, MEG, iEEG, physio and events data,
- act as a Matlab / Octave based BIDS-validator
- act as a BIDS converter
- implement reading / writing capabilities for the different modality-specific
data format that exist in BIDS (
.nii
,.eeg
,.ds
,.fif
...)
BIDS matlab is structured as package, so you can easily access functions in subfolders
that start with +
.
To use the +bids/layout.m
function:
BIDS = bids.layout('/home/data/ds000117');
bids.query(BIDS, 'subjects')
To use the +bids/+util/jsondecode.m
function:
content = bids.util.jsondecode('/home/data/some_json_file.json');
There are demos and tutorials showing some of the features in the demos
folder.
Make sure to be familiar with the JSON 101.
Note some of the perks of working with JSON files described on the BIDS starterkit.
For BIDS-MATLAB, if you are using MATLAB R2016b or newer, nothing else needs to be installed.
If you are using MATLAB R2016a or older, or using Octave, you need to install a supported JSON library for your MATLAB or Octave. This can be any of:
To contact us:
- open an issue
- join our chat on the BIDS-MATLAB channel on the brainhack mattermost
- join our google group.
- dicm2nii: A DICOM to BIDS converter
- imtool3D_BIDS: A 3D viewer for BIDS directory
- Brainstorm: Comprehensive brain analysis toolbox (includes BIDS import and export and different examples dealing with BIDS datasets (e.g. group analysis from a MEG visual dataset, resting state analysis from OMEGA datasets)
To credit BIDS-Matlab in your work, please cite the Zenodo archive, which points to a permanent record of all BIDS-Matlab versions. We encourage you to mention the specific version you used.
@software{Gau_bids-matlab,
author = {Gau, Rémi and Flandin, Guillaume and Janke, Andrew and Duval, Tanguy and Oostenveld, Robert and Madan, Christopher and Niso, Guiomar and Szczepanik, Michał and Mutsaerts, Henk and Beliy, Nikita and Norgaard, Martin and Pernet, Cyril and Chrisophe, Phillips and Shahzad, Iqra and Botvinik-Nezer, Rotem and Barilari, Marco and Battal, Ceren and MacLean, Michèle and Caron-Guyon, Jeanne},
license = {MIT},
title = {{bids-matlab}},
url = {https://github.com/bids-standard/bids-matlab},
doi = https://doi.org/10.5281/zenodo.3363985
}
If you want to contribute make sure to check our contributing guidelines and our code of conduct.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!