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 totrue
, the parsing of the dataset will follow the bids-schema provided with bids-matlab. If set tofalse
files just have to be of the formsub-label_[entity-label]_suffix.ext
to be parsed.index_derivatives (
logical
) – iftrue
this will index the content of the anyderivatives
folder in the BIDS dataset.index_dependencies (
logical
) – iftrue
this will index the explicit dependencies (with “IntendedFor” in json files)filter (struct with optional fields
sub
,ses
,modality
. Regular expression can be used forsub
andses
.) – Can be used to index only a subset of the dataset.tolerant (
logical
) – Set totrue
to turn validation errors into warningsverbose (
logical
) – Set totrue
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', '')