Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/bids-standard/bids-matlab

MATLAB / Octave tools for BIDS datasets
https://github.com/bids-standard/bids-matlab
bids closember eeg ieeg matlab meg mri neuroimaging octave pet
Last synced: about 1 month ago
JSON representation
MATLAB / Octave tools for BIDS datasets
Host: GitHub
URL: https://github.com/bids-standard/bids-matlab
Owner: bids-standard
License: mit
Created: 2018-10-08T14:39:16.000Z (about 6 years ago)
Default Branch: main
Last Pushed: 2024-06-18T15:19:22.000Z (6 months ago)
Last Synced: 2024-06-22T11:18:21.250Z (6 months ago)
Topics: bids, closember, eeg, ieeg, matlab, meg, mri, neuroimaging, octave, pet
Language: MATLAB
Homepage: https://bids-matlab.readthedocs.io
Size: 6.19 MB
Stars: 48
Watchers: 5
Forks: 29
Open Issues: 31
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project

awesome-bids - bids-matlab
README

        

[![tests_matlab](https://github.com/bids-standard/bids-matlab/actions/workflows/run_tests_matlab.yml/badge.svg)](https://github.com/bids-standard/bids-matlab/actions/workflows/run_tests_matlab.yml)

[![tests_octave](https://github.com/bids-standard/bids-matlab/actions/workflows/run_tests_octave.yml/badge.svg)](https://github.com/bids-standard/bids-matlab/actions/workflows/run_tests_octave.yml)

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/bids-standard/bids-matlab/main?urlpath=demos)

[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/bids-standard/bids-matlab/main.svg)](https://results.pre-commit.ci/latest/github/bids-standard/bids-matlab/main)

[![miss hit](https://img.shields.io/badge/code%20style-miss_hit-000000.svg)](https://misshit.org/)

[![View bids-matlab on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://nl.mathworks.com/matlabcentral/fileexchange/93740-bids-matlab)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5910584.svg)](https://doi.org/10.5281/zenodo.5910584)

[![All Contributors](https://img.shields.io/badge/all_contributors-19-orange.svg?style=flat-square)](#contributors-)

# BIDS for MATLAB / Octave

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](https://github.com/bids-standard/pybids) for Python and the

[BIDS Starter Kit](https://github.com/bids-standard/bids-starter-kit).

## Installation

### 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.

For MacOS and Unix system, using `bids.copy_to_derivative` requires

a version of gunzip >= 1.6.

### Download or clone

Download, unzip this repository and add its content to the MATLAB/Octave path.

```Matlab

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

addpath('bids-matlab-main');

```

Or clone it with git:

```bash

git clone https://github.com/bids-standard/bids-matlab.git

```

and then add it to your MATLAB/Octave path.

```Matlab

addpath('bids-matlab');

```

### Get the latest features

Stable versions should be fetched from a specific version tag

or from the [Mathworkds file exchange](https://nl.mathworks.com/matlabcentral/fileexchange/93740-bids-matlab).

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:

```bash

git clone --branch main https://github.com/bids-standard/bids-matlab.git

```

## 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`),

- 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` and

  `bids.util.jsonwrite`) provided that the right

  [dependencies](#reading-and-writing-json-files) are installed,

- read and write TSV files (see `bids.util.tsvread` and `bids.util.tsvwrite`)

- access and query the [BIDS schema](https://bids-specification.readthedocs.io/en/latest/schema.json) (`bids.schema`)

- access, query and create basic transformations for the [BIDS statistical model](https://bids-standard.github.io/stats-models/) (`bids.Model` and `bids.transformers`)

The behavior of this toolbox assumes that it is interacting with a valid BIDS

dataset that should have been validated using

[BIDS-validator](https://bids-standard.github.io/bids-validator/). If the

Node.js version of the validator is

[installed on your computer](https://github.com/bids-standard/bids-validator#quickstart),

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

- generate human readable reports of the content of BIDS data with EEG, MEG,

  iEEG, physio and events data,

### What will this toolbox most likely never do

- 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`...)

## Usage

BIDS matlab is structured as package, so you can easily access functions in subfolders

that start with `+`.

To use the `+bids/layout.m` function:

```Matlab

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

bids.query(BIDS, 'subjects')

```

To use the `+bids/+util/jsondecode.m` function:

```Matlab

content = bids.util.jsondecode('/home/data/some_json_file.json');

```

## Demos

There are demos and tutorials showing some of the features in the `demos` folder.

### Reading and writing JSON files

Make sure to be familiar with the [JSON 101](https://bids-standard.github.io/stats-models/json_101.html).

Note some of the perks of working with JSON files described

on [the BIDS starterkit](https://bids-standard.github.io/bids-starter-kit/folders_and_files/metadata.html#interoperability-issues).

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:

- [JSONio](https://github.com/gllmflndn/JSONio) for MATLAB or Octave

- [SPM12](https://www.fil.ion.ucl.ac.uk/spm/software/spm12/)

## Get in touch

To contact us:

- open an [issue](https://github.com/bids-standard/bids-matlab/issues/new/choose)

- join our chat on the

[BIDS-MATLAB channel](https://mattermost.brainhack.org/brainhack/channels/bids-matlab)

on the brainhack mattermost

- join our [google group](https://groups.google.com/g/bids-matlab).

## Other tools (MATLAB only)

- [dicm2nii](https://github.com/xiangruili/dicm2nii): A DICOM to BIDS converter

- [imtool3D_BIDS](https://github.com/tanguyduval/imtool3D_td): A 3D viewer for BIDS directory

- [Brainstorm](https://github.com/brainstorm-tools/brainstorm3):

  Comprehensive brain analysis toolbox

  (includes BIDS [import and export](https://neuroimage.usc.edu/brainstorm/ExportBids) and

  different examples dealing with BIDS datasets

  (e.g. [group analysis from a MEG visual dataset](https://neuroimage.usc.edu/brainstorm/Tutorials/VisualGroup),

  [resting state analysis from OMEGA datasets](https://neuroimage.usc.edu/brainstorm/Tutorials/RestingOmega#BIDS_specifications))

## How to cite

To credit BIDS-Matlab in your work, please cite the [Zenodo archive](https://zenodo.org/record/5910584),

which points to a permanent record of all BIDS-Matlab versions.

We encourage you to mention the specific version you used.

```bibtex

@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

}

```

## Contributing

If you want to contribute make sure to check our [contributing guidelines](CONTRIBUTING.md)

and our [code of conduct](CODE_OF_CONDUCT.md).

Thanks goes to these wonderful people

([emoji key](https://allcontributors.org/docs/en/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}
💻 🤔

      
_{Christophe Phillips}
🤔

      
_CerenB
👀

    

    

      
_{marcobarilari}
👀

      
_{Michèle MacLean}
🐛

      
_{Jeanne Caron-Guyon}
🤔

      
_{Rotem Botvinik-Nezer}
🤔

      
_{Iqra Shahzad}
👀

      
_{DanielaMariaPinzon}
🐛

      
_JeanLucAnton
🐛

    

    

      
_{avanaudenhaege}
🐛

      
_coxroy
🐛 🤔 📓

      
_achilleasNP
🐛

    

  

This project follows the

[all-contributors](https://github.com/all-contributors/all-contributors)

specification. Contributions of any kind welcome!