Indexing and querying a BIDS dataset

BIDS-Matlab allows you to index a raw or derivative BIDS dataset with bids.layout(), and then query the content of that dataset with bids.query().

The general API of these functions is detailed below.

For an example on how to use them, check out this jupyter notebook.

bids.layout(varargin)

Parse a directory structure formatted according to the BIDS standard

USAGE:

BIDS = bids.layout(pwd, ...
                   'use_schema', true, ...
                   'index_derivatives', false, ...
                   'index_dependencies', true, ...
                   'filter', struct([]), ...
                   'tolerant', true, ...
                   'verbose', false)

Parameters:

root (char) – directory of the dataset formatted according to BIDS [default: pwd]
use_schema (logical) – If set to true, the parsing of the dataset will follow the bids-schema provided with bids-matlab. If set to false files just have to be of the form sub-label_[entity-label]_suffix.ext to be parsed.
index_derivatives (logical) – if true this will index the content of the any derivatives folder in the BIDS dataset.
index_dependencies (logical) – if true this will index the explicit dependencies (with “IntendedFor” in json files)
filter (struct with optional fields sub, ses, modality. Regular expression can be used for sub and ses.) – Can be used to index only a subset of the dataset.
tolerant (logical) – Set to true to turn validation errors into warnings
verbose (logical) – Set to true to get more feedback

Example

BIDS = bids.layout(fullfile(get_test_data_dir(), '7t_trt'), ...
                   'use_schema', true, ...
                   'verbose', true, ...
                   'index_derivatives', false, ...
                   'filter', struct('sub', {{'^0[12]'}}, ...
                                    'modality', {{'anat', 'func'}}, ...
                                    'ses', {{'1', '2'}}));

bids.query(BIDS, query, varargin)

Queries a directory structure formatted according to the BIDS standard

USAGE:

result = bids.query(BIDS, query, filter)

Parameters:

BIDS (structure or char) – BIDS directory name or BIDS structure (from bids.layout)
query (char) – type of query (see list below)

Type of queries allowed.

Any of the following:

'modalities': known as datatype in BIDS (anat, func, eeg…)
'entities'
'suffixes'
'data': filenames
'metadata': associated metadata (using the inheriance principle)
'metafiles': json sidecar files
'dependencies': associated files (for example the event.tsv for a bold.nii or eeg.eeg file)
'participants': content and metadata of participants.tsv
'phenotype': content and metadata of the phenotype folder
'extensions'
'tsv_content'

And any of the BIDS entities:

'acquisitions'
'atlases'
'ceagents'
'chunks'
'densities'
'descriptions'
'directions'
'echos'
'flips'
'hemispheres'
'inversions'
'labels'
'mtransfers'
'parts'
'processings'
'reconstructions'
'recordings'
'resolutions'
'sessions'
'subjects'
'runs'
'samples'
'spaces'
'splits'
'stains'
'tasks'
'tracers'

Warning

Note that most of the query types are plurals.

Parameters:: filter (structure or nX2 cell or series of key-value parameters) – filter for the query

The choice of available keys to filter with includes:

'suffix'
'extension'
'prefix'
'modality'

It can also include any of the entity keys present in the files in the dataset. To know what those are, use:

bids.query(BIDS, 'entities')

Warning

Note that integers as query label for the entity keys listed below:

'run'

'flip'

'inv'

'split'

'echo'

'chunk'

If you want to exclude an entity, use '' or [].

It is possible to use regular expressions in the queried values.

Examples

Querying for ‘BOLD’ files for subject ‘01’, for run 1 to 5 of the ‘stopsignalwithpseudowordnaming’ task with gunzipped nifti files.

data = bids.query(BIDS, 'data', ...
                        'sub', '01', ...
                        'task', 'stopsignalwithpseudowordnaming', ...
                        'run', 1:5, ...
                        'extension', '.nii.gz', ...
                        'suffix', 'bold');

Same as above but using a filter structure.

filters = struct('sub', '01', ...
                 'task', 'stopsignalwithpseudowordnaming', ...
                 'run', 1:5, ...
                 'extension', '.nii.gz', ...
                 'suffix', 'bold');

data = bids.query(BIDS, 'data', filters);

Same as above but using regular expression to query for subjects 1 to 5.

filters = {'sub', '0[1-5]'; ...
           'task', 'stopsignal.*'; ...
           'run', 1:5; ...
           'extension', '.nii.*'; ...
           'suffix', 'bold'};

data = bids.query(BIDS, 'data', filters);

The following query would return all files that do not contain the task entity.

data = bids.query(BIDS, 'data', 'task', '')