README.md

BIDS for MATLAB / Octave

This repository aims at centralising MATLAB/Octave tools to interact with datasets conforming to the BIDS (Brain Imaging Data Structure) format.

For more information about BIDS, visit https://bids.neuroimaging.io/.

Join our chat on the BIDS-MATLAB channel on the brainhack mattermost.

See also PyBIDS for Python and the BIDS Starter Kit.

Features

What this toolbox can do

• 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),
• 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)
• read and write JSON files (see bids.util.jsondecode and bids.util.jsonencode) provided that the right dependencies are installed,
• read and write TSV files (see bids.util.tsvread and bids.util.tsvwrite),

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.

What this toolbox cannot do... yet

• 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,
• do basic copying of files to help with derivative dataset generation,
• generate human readable reports of the content of BIDS data with EEG, MEG, iEEG, physio and events data,
• deal with some of the most recent updates or incoming BIDS extensions (basic derivatives, ASL, PET, BIDS model...)
• ...

We are trying to centralize the requests for new features in this issue: have a browse to see what could be coming soon or if we have missed something obvious.

Installation

Download this repository and add it to your MATLAB/Octave path.

unzip('https://github.com/bids-standard/bids-matlab/archive/master.zip');
addpath('bids-matlab-master');

If your version of MATLAB/Octave does not support JSON natively, please also install SPM12 or JSONio.

Usage

BIDS = bids.layout('/home/data/ds000117');
bids.query(BIDS, 'subjects')

A tutorial is available as a Jupyter Notebook and can be run interactively via Binder.

Requirements

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.

Reading and writing JSON files

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:

• JSONio for MATLAB or Octave
• SPM12

Implementation

Starting point was spm_BIDS.m from SPM12 (documentation) reformatted in a +bids package with dependencies to other SPM functions removed.

Other tools (MATLAB only)

• 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 )

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Guillaume 💻 🎨 📖 💡 🤔 🚇 🚧 💬 👀 ⚠️	Remi Gau 💻 🎨 📖 💡 🤔 🚧 💬 👀 ⚠️	Andrew Janke 💻 🎨 📖 🤔 👀 🚇	tanguyduval 💻 📖 🤔	Robert Oostenveld 💻 📖 🤔 👀	Christopher Madan 🖋	Julia Guiomar Niso Galán 👀
Michał Szczepanik 🚇 🤔 💻	Henk Mutsaerts 💻 🤔	Nikita Beliy 💻 🤔 👀	Martin Norgaard 🐛 🤔	Cyril Pernet 💻 🤔

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