Function description


Creates dummy content for a given BIDS derivative file.


json = derivatives_json(derivative_filename, 'force', false)
  • derivative_filename (string) –

  • force (logical) – when true it will force the creation of a json content even when the filename contains no BIDS derivatives entity.


Initialize dataset with README, description, folder structure…


bids.init(pth, ...
          'folders', folders, ,...
          'is_derivative', false,...
          'is_datalad_ds', false, ...
          'tolerant', true, ...
          'verbose', false)
  • pth (string) – directory where to create the dataset

  • folders (structure) – define the folder structure to create. folders.subjects folders.sessions folders.modalities

  • is_derivative (logical) –

  • is_datalad_ds

class +bids.Description(varargin)

Class to deal with dataset_description files.


ds_desc = bids.Description(pipeline, BIDS);
  • pipeline (string) – pipeline name

  • BIDS (structure or char) – output from BIDS layout to identify the source dataset used when creating a derivatives dataset Can also be the path to a dataset_descriptin.json file

content = None

dataset description content

is_derivative = 'false'


pipeline = "''"

name of the pipeline used to generate this derivative dataset



ds_desc = bids.Description(pipeline, BIDS);


ds_desc = ds_desc.set_derivative();


ds_desc = ds_desc.set_field(key, value);
ds_desc = ds_desc.set_field(struct(key1, value1, ...
                                   key2, value2));
append(key, value)

Appends an item to the dataset description content.


ds_desc = ds_desc.append(key, value);

Writes json file of the dataset description.


ds_desc.write([folder = pwd]);

Copy selected data from BIDS layout to given derivatives folder.


bids.copy_to_derivative(BIDS, ...
                        'pipeline_name', '', ...
                        'out_path', '', ...
                        'filters', struct(), ...
                        'unzip', true, ...
                        'force', false, ...
                        'skip_dep', false, ...
                        'use_schema, use_schema, ...
                        'verbose', true);
  • BIDS (structure or string) – BIDS directory name or BIDS structure (from bids.layout)

  • pipeline_name (string) – name of pipeline to use

  • out_path (string) – path to directory containing the derivatives

  • filter (structure or cell) – list of filters to choose what files to copy (see bids.query)

  • unzip (logical) – If true then all .gz files will be unzipped after being copied.

  • force (logical) – If set to false it will not overwrite any file already present in the destination.

  • skip_dep (logical) – If set to false it will copy all the dependencies of each file.

  • tolerant (boolean) – Defaults to false. Set to true to turn errors into warnings.

  • use_schema (logical) – If set to true it will only copy files that are BIDS valid.

  • verbose (logical) –

All the metadata of each file is read through the whole hierarchy and dumped into one side-car json file for each file copied. In practice this “unravels” the inheritance principle.

Create a short summary of the acquisition parameters of a BIDS dataset.

The output can be saved to a markdown file and/or printed to the screen.

            'filter', filter, ...
            'output_path', output_path, ...
            'read_nifti', read_nifti, ...
            'verbose', verbose);
  • BIDS (string or structure) – Path to BIDS dataset or output of bids.layout [Default = pwd]

  • filter (structure) – Specifies which the subject, session, … to take as template. [Default = struct(‘sub’, ‘’, ‘ses’, ‘’)]. See bids.query for more information.

  • output_path (string) – Folder where the report should be printed. If empty (default) then the output is sent to the prompt.

  • read_nifti (logical) – If set to true (default) the function will try to read the NIfTI file to get more information. This relies on the spm_vol.m function from SPM.

  • verbose (logical) – If set to false (default) the function does not output anything to the prompt.

+bids.validate(root, options)

BIDS Validator


[sts, msg] = bids.validate(root, options)

root – directory formatted according to BIDS [Default: pwd]


  • sts:

    0 if successful

  • msg:

    warning and error messages

Command line version of the BIDS-Validator:

Web version:


Create a diagnostic figure for a dataset.

  • list the number of files for each subject split by: - modality - task (optional)

  • list the number of trials for each event type


diagnostic_table = diagnostic(BIDS, ...
                              'use_schema', true, ...
                              'output_path', '', ...
                              'filter', struct(), ...
                              'split_by', {''})
  • BIDS (structure or string) – BIDS directory name or BIDS structure (from bids.layout)

  • split_by (cell) – splits results by a given BIDS entity (now only task is supported)

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

  • out_path (string) – path to directory containing the derivatives

  • filter (structure or cell) – list of filters to choose what files to copy (see bids.query)

  • trial_type_col (char) – Optional. Name of the column containing the trial type. Defaults to 'trial_type'.

  • verbose (logical) – Optional. Set to false to not show the figure. Defaults to true.


BIDS = bids.layout(path_to_dataset);
diagnostic_table = bids.diagnostic(BIDS, 'output_path', pwd);
diagnostic_table = bids.diagnostic(BIDS, 'split_by', {'task'}, 'output_path', pwd);

output of diagnostic


output of diagnostic for events


output of diagnostic split by task