Utility functions¶

+bids.+util.create_data_dict(varargin)¶

Create a JSON data dictionary for a TSV file.

Levels in columns that may lead to invalid matlab structure fieldnames are renamed. Hence the output may need manual cleaning.

Descriptions may be added for columns if a match is found in the BIDS schema: for example: trial_type, onset…

To create better data dictionaries, please see the tools for hierarchical event descriptions.

USAGE:

data_dict = bids.util.create_data_dict(tsv_file, ...
                                       'output', [], ...
                                       'schema', true, ...
                                       'force', false, ...
                                       'level_limit', 10, ...
                                       'verbose', true);

Parameters:

output – filename for the output files. Can pass be a cell string of paths
force (logical) – If set to false it will not overwrite any file already present in the destination.
schema (logical or a schema object) – If set to true it will use the schema to try to find definitions for the column headers
level_limit – Maximum number of levels to list. Defaults to 10;

EXAMPLE:

BIDS = bids.layout(pth_bids_example, 'ds001'));

tsv_files = bids.query(BIDS, 'data', ...
                       'sub', '01', ...
                       'suffix', 'events');

data_dict = bids.util.create_data_dict(tsv_files{1}, ...
                                       'output', 'tmp.json', ...
                                       'schema', true);

+bids.+util.create_participants_tsv(varargin)¶

Creates a simple participants tsv for a BIDS dataset.

USAGE:

output_filename = bids.util.create_participants_tsv(layout_or_path, ...
                                                    'use_schema', true, ...
                                                    'tolerant', true, ...
                                                    'verbose', false)

Parameters:

layout_or_path (path or structure) –
use_schema (logical) –
tolerant (logical) – Set to true to turn validation errors into warnings
verbose (logical) – Set to true to get more feedback

+bids.+util.create_readme(varargin)¶

Create a README in a BIDS dataset.

USAGE:

bids.util.create_readme(layout_or_path, is_datalad_ds, ...
                        'tolerant', true, ...
                        'verbose', false)

Parameters:

layout_or_path (path or structure) –
tolerant (logical) – Set to true to turn validation errors into warnings
verbose (logical) – Set to true to get more feedback

+bids.+util.create_scans_tsv(varargin)¶

Create a simple scans.tsv for each participant of a BIDS dataset.

USAGE:

output_filename = bids.util.create_scans_tsv(layout_or_path, ...
                                             'use_schema', true, ...
                                             'tolerant', true, ...
                                             'verbose', false)

Parameters:

layout_or_path (path or structure) –
use_schema (logical) –
tolerant (logical) – Set to true to turn validation errors into warnings
verbose (logical) – Set to true to get more feedback

+bids.+util.create_sessions_tsv(varargin)¶

Create a simple sessions.tsv for each participant of a BIDS dataset.

USAGE:

output_filename = bids.util.create_sessions_tsv(layout_or_path, ...
                                                'use_schema', true, ...
                                                'tolerant', true, ...
                                                'verbose', false)

Parameters:

layout_or_path (path or structure) –
use_schema (logical) –
tolerant (logical) – Set to true to turn validation errors into warnings
verbose (logical) – Set to true to get more feedback

+bids.+util.download_ds(varargin)¶

Downloads a BIDS data for a demo from a given source

USAGE:

output_dir = download_moae_ds('source', 'spm', ...
                              'demo', 'moae', ...
                              'out_path', fullfile(bids.internal.root_dir(), 'demos'), ...
                              'force', false, ...
                              'verbose', true, ...
                              'delete_previous', true);

SPM:

bids.util.download_ds('source', 'spm', 'demo', 'moae')
bids.util.download_ds('source', 'spm', 'demo', 'facerep')
bids.util.download_ds('source', 'spm', 'demo', 'eeg')

—

BRAINSTORM:

bids.util.download_ds('source', 'brainstorm', 'demo', 'ieeg')
bids.util.download_ds('source', 'brainstorm', 'demo', 'meg')

ieeg: SEEG+MRI: 190 Mb

https://neuroimage.usc.edu/brainstorm/Tutorials/Epileptogenicity ftp://neuroimage.usc.edu/pub/tutorials/tutorial_epimap_bids.zip

meg: MEG+MRI+DWI: 208 Mb

https://neuroimage.usc.edu/brainstorm/Tutorials/FemMedianNerve ftp://neuroimage.usc.edu/pub/tutorials/sample_fem.zip

ecog: SEEG+ECOG+MRI: 897 Mb

https://neuroimage.usc.edu/brainstorm/Tutorials/ECoG ftp://neuroimage.usc.edu/pub/tutorials/sample_ecog.zip

meg_rest: MEG resting-state: 5.2 Gb

https://neuroimage.usc.edu/brainstorm/Tutorials/RestingOmega ftp://neuroimage.usc.edu/pub/tutorials/sample_omega.zip

+bids.+util.jsondecode(file, varargin)¶

Decode JSON-formatted file

USAGE:

json = bids.util.jsondecode(file, opts)

Parameters:

file (string) – name of a JSON file or JSON string
opts (structure) – structure of optional parameters (only with JSONio):

opt.replacementStyle: string to control how non-alphanumeric characters are replaced.

'underscore' Default

'hex'

'delete'

'nop'

Returns:

json:

JSON structure

+bids.+util.jsonencode(varargin)¶

Encode data to JSON-formatted file

USAGE:

bids.util.jsonencode(filename, json, opts)

Parameters:

filename (string) – JSON filename
json (structure) – JSON structure

USAGE:

S = bids.util.jsonencode(json, opts)

Parameters:

json (structure) – JSON structure
opts – optional parameters

Returns:

S:

(string) serialized JSON structure

+bids.+util.mkdir(varargin)¶

Make new directory trees

USAGE:

sts = bids.util.mkdir(dir, ...)

Parameters:

dir (character array, or cell array of strings) – directory structure to create

Returns:

sts:

status is true if all directories were successfully created or already existing, false otherwise.

EXAMPLE:

bids.util.mkdir('dataset', {'sub-01', 'sub-02'}, {'mri', 'eeg'});

Based on spm_mkdir from SPM12

+bids.+util.plot_events(varargin)¶

USAGE:

plot_events(events_files, 'include', include, ...
                          'trial_type_col', 'trial_type', ...
                          'model_file', path_to_model)

Parameters:

events_files (path or cellstr of paths) – BIDS events TSV files.
include (char or cellstr) – Optional. Restrict conditions to plot.
trial_type_col (char or cellstr) – Optional. Defines the column where trial types are listed. Defaults to ‘trial_type’
model_file (fullpath) – Optional. Bids stats model file to apply to events.tsv before plotting

EXAMPLE:

data_dir = fullfile(get_test_data_dir(), 'ds108');

BIDS = bids.layout(data_dir);

events_files = bids.query(BIDS, ...
                          'data', ...
                          'sub', '01', ...
                          'run', '01', ...
                          'suffix', 'events');

include = {'Reapp_Neg_Cue', 'Look_Neg_Cue', 'Look_Neutral_Cue'};
bids.util.plot_events(events_files, 'include', include);

_images/plot_events_ds001.png — output of `plot_events`¶

+bids.+util.tsvread(filename, field_to_return, hdr)¶

Load text and numeric data from tab-separated-value or other file.

USAGE:

file_content = tsvread(filename, field_to_return, hdr)

Parameters:

filename (string) – filename (can be gzipped) {txt,mat,csv,tsv,json}ename
field_to_return – name of field to return if data stored in a structure [default: '']; or index of column if data stored as an array
hdr (logical) – detect the presence of a header row for csv/tsv [default: true]

Returns:

file_content:

corresponding data array or structure

Based on spm_load.m from SPM12.

+bids.+util.tsvwrite(filename, var)¶

Save text and numeric data to tab-separated-value file

USAGE:

tsvwrite(f, var)

Parameters:

filename (string) –
var (data array or structure) –

Based on spm_save.m from SPM12.