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 (string) – 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. If a folder path is provided, then the schema contained in that folder will be used for parsing.

  • 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 dependencies (json files, associated TSV files for each file…)

  • filter (struct with optional fields sub, ses, modality. Regular expression can be used for sub and ses.) – if true this will index the dependencies (json files, associated TSV files for each file…)

  • 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 string) – BIDS directory name or BIDS structure (from bids.layout)

  • query (string) – type of query (see list below)

Type of queries allowed.

Any of the following:

  • 'modalities'

  • 'entities'

  • 'suffixes'

  • 'data'

  • 'metadata'

  • 'metafiles'

  • 'dependencies'

  • 'extensions'

  • 'prefixes'

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 all 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 also possible to use regular expressions in the value.

Regex example:

% The following 2 will return the same thing
data = bids.query(BIDS, 'data', 'sub', '01')
data = bids.query(BIDS, 'data', 'sub', '^01$')

% But the following would return all the data for all subjects
% whose label ends in '01'
data = bids.query(BIDS, 'data', 'sub', '.*01')

Example 1: 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');

Example 2: 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);

Example 3: 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);

Example 4: The following query would return all files that do not contain the task entity:

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