developer documentation

+internal

bids.internal.add_missing_field(structure, field)

USAGE:

structure = add_missing_field(structure, field)
bids.internal.append_to_layout(file, subject, modality, schema, previous)

appends a file to the BIDS layout by parsing it according to the provided schema

USAGE:

subject = append_to_layout(file, subject, modality, schema == [])
Parameters:

  • file (char)

  • subject (structure) – subject sub-structure from the BIDS layout

  • modality (char)

  • schema (structure)

bids.internal.camel_case(str)

Removes non alphanumeric characters and uppercase first letter of all words but the first

USAGE:

str = camel_case(str)
Parameters:

str (char)

Returns:

str:

(char) returns the input with an upper case for first letter for all words but the first one (camelCase) and removes invalid characters (like spaces).

bids.internal.create_unordered_list(list)

turns a cell string or a structure into a string that is an unordered list to print to the screen

USAGE:

list = bids.internal.create_unordered_list(list)
Parameters:

list (cell string or structure) – obligatory argument.

bids.internal.download(URL, output_dir, verbose)

USAGE:

filename = download(URL, output_dir, verbose)
bids.internal.ends_with(str, pattern)

Checks id character array ‘str’ ends with ‘pat’

USAGE:

res = bids.internal.endsWith(str, pattern)
Parameters:

  • str (character array)

  • pattern (character array)

Based on the equivalent function from SPM12

bids.internal.error_handling(varargin)

USAGE:

error_handling(function_name, id, msg, tolerant, verbose)
Parameters:

  • function_name – default = bidsMatlab

  • id (char) – default = unspecified

  • msg (char) – default = unspecified

  • tolerant (logical)

  • verbose (logical)

Example

bids.internal.error_handling(mfilename(), 'thisError', 'this is an error', tolerant, verbose)
bids.internal.file_utils(str, varargin)

Character array (or cell array of char) handling facility

USAGE:

To list files or directories (with fullpath if necessary):

[files, dirs] = bids.internal.file_utils('List',   directory,        regexp)
[files, dirs] = bids.internal.file_utils('FPList', directory,        regexp)
[dirs]        = bids.internal.file_utils('List',   directory, 'dir', regexp)
[dirs]        = bids.internal.file_utils('FPList', directory, 'dir', regexp)

To get a certain piece of information from a file:

str = bids.internal.file_utils(str, option)

str - character array, or cell array of char

option - char of requested item - one among:

{‘path’, ‘basename’, ‘ext’, ‘filename’, ‘cpath’, ‘fpath’}

To set a certain piece of information from a file:

str = bids.internal.file_utils(str, opt_key, opt_val, ...)

str - character array, or cell array of char

opt_key - char of targeted item - one among:

{‘path’, ‘basename’, ‘ext’, ‘filename’, ‘prefix’, ‘suffix’}

opt_val - char of new value for feature

Based on spm_file.m and spm_select.m from SPM12.

bids.internal.format_path(pth)

USAGE:

pth = bids.internal.format_path(pth)

Replaces single ‘' by ‘/’ in Windows paths to prevent escaping warning when printing a path to screen

Parameters:

pth (char or cellstr$) – If pth is a cellstr of paths, pathToPrint will work recursively on it.

bids.internal.get_meta_list(varargin)

Read a BIDS’s file metadata according to the inheritance principle

USAGE:

metalist = bids.internal.get_metadata(filename, ...
                                      pattern, ...
                                      use_inheritance)
Parameters:

  • filename (char) – fullpath name of file following BIDS standard

  • pattern (char) – Regular expression matching the metadata file default = '^.*%s\\.json$' If provided, it must at least be '%s'.

Returns:

metalist - list of paths to metafiles

bids.internal.get_metadata(metafile)

Read a BIDS’s file metadata according to the inheritance principle.

USAGE:

meta = bids.internal.get_metadata(metafile)
Parameters:

metafile (char or array of chars) – list of fullpath names of metadata files.

Returns:

  • meta:

    metadata structure

bids.internal.get_version()

Reads the version number of the pipeline from the txt file in the root of the repository.

USAGE:

version_number = bids.internal.get_version()
Returns:

version_number:

(char) Use semantic versioning format (like v0.1.0)

bids.internal.is_github_ci()

  1. Copyright 2021 Remi Gau

bids.internal.is_octave()

Returns true if the environment is Octave.

USAGE:

status = bids.internal.is_octave()
Returns:

status:

(logical)

bids.internal.is_valid_fieldname(some_str)

A valid MATLAB identifier is a character vector of (A-Z, a-z, 0-9) and underscores, such that the first character is a letter and the length of the character vector is less than or equal to namelengthmax.

USAGE:

status = is_valid_fieldname(some_str)
bids.internal.keep_file_for_query(file_struct, options)

USAGE:

status = keep_file_for_query(file_struct, options)

returns ``false`` if the file is to be kept when running ``bids.query``
bids.internal.list_all_trial_types(varargin)

List all the trial_types in all the events.tsv files for a task.

USAGE:

trial_type_list = bids.internal.list_all_trial_types(BIDS, , ...
                                                     task, ...
                                                     'trial_type_col', 'trial_type', ...
                                                     'tolerant', true, ...
                                                     'verbose', false)
Parameters:

  • BIDS (structure or char) – BIDS directory name or BIDS structure (from bids.layout)

  • task (char) – name of the task

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

  • tolerant (logical) – Optional. Default to true.

  • verbose (logical) – Optional. Default to false.

bids.internal.match_structure_fields(struct_one, struct_two)

Update list of fields of a structure so it matches that of another.

USAGE:

[struct_one, struct_two] = match_structure_fields(struct_one, struct_two)
bids.internal.parse_filename(filename, fields, tolerant, verbose)

Split a filename into its building constituents

USAGE:

p = bids.internal.parse_filename(filename, fields, tolerant, verbose)
Parameters:

  • filename (string) – filename to parse that follows the pattern sub-label[_entity-label]*_suffix.extension

  • fields (cell) – cell of strings of the entities to use for parsing

Example

filename = '../sub-16/anat/sub-16_ses-mri_run-1_acq-hd_T1w.nii.gz';

bids.internal.parse_filename(filename)

ans =

struct with fields:

  'filename', 'sub-16_ses-mri_run-1_acq-hd_T1w.nii.gz', ...
  'suffix', 'T1w', ...
  'ext', '.nii.gz', ...
  'entities', struct('sub', '16', ...
                     'ses', 'mri', ...
                     'run', '1', ...
                     'acq', 'hd');

Example

filename = '../sub-16/anat/sub-16_ses-mri_run-1_acq-hd_T1w.nii.gz';
fields = {'sub', 'ses', 'run', 'acq', 'ce'};
output = bids.internal.parse_filename(filename, fields);

The output will have the following shape:

output = struct( ...
                  'filename', 'sub-16_ses-mri_run-1_acq-hd_T1w.nii.gz', ...
                  'suffix', 'T1w', ...
                  'ext', '.nii.gz', ...
                  'entities', struct('sub', '16', ...
                                     'ses', 'mri', ...
                                     'run', '1', ...
                                     'acq', 'hd', ...
                                     'ce', ''), ...
                  'prefix', '');
bids.internal.plot_diagnostic_table(diagnostic_table, headers, yticklabel, fig_name, visible)

Plot a diagnostic table to see the number of files per subject or of trials per run.

USAGE:

plot_diagnostic_table(diagnostic_table, headers, yticklabel, fig_name)
Parameters:

  • diagnostic_table (n X m array of integers) – table to plot

  • headers (n X 1 cell of struct) – Used to created the column names

  • yticklabel (m X 1 cellstr)

  • fig_name (str)

bids.internal.regexify(string)

Turns a string into a simple regex. Useful to query bids dataset with bids.query that by default expects will treat its inputs as regexp.

Input –> Output

foo –> ^foo$

USAGE:

string = bids.internal.regexify(string)
bids.internal.replace_placeholders(boilerplate_text, metadata)
bids.internal.return_file_index(BIDS, modality, filename)

For a given filename and modality, it returns the file index in the subject sub-structure of the BIDS structure.

UISAGE:

file_idx = return_file_index(BIDS, modality, filename)
bids.internal.return_file_info(BIDS, fullpath_filename)

USAGE:

file_info = return_file_info(BIDS, fullpath_filename)
bids.internal.return_subject_index(BIDS, filename)

For a given filename, it returns the subject index in BIDS structure so that: BIDS.subjects(sub_idx)

USAGE:

sub_idx = return_subject_index(BIDS, filename)
bids.internal.root_dir()
bids.internal.starts_with(str, pattern)

Checks id character array ‘str’ starts with ‘pattern’

USAGE:

res = bids.internal.startsWith(str, pattern)
Parameters:

  • str (character array)

  • pattern (character array)

Based on the equivalent function from SPM12.

bids.internal.url(section)

returns URL of some specific sections of the spec

USAGE:

value = url(section)