BIDS file handling

class +bids.File(varargin)

Class to deal with BIDS filenames

USAGE:

file = bids.File(input, ...
                 'use_schema', false, ...
                 'tolerant', true,
                 'verbose', false);

Parameters:

• input (filename or structure) – path to the file or a structure with the file information

• use_schema (logical) – will apply the BIDS schema when parsing or creating filenames

• tolerant (logical) – turns errors into warning when set to true

• verbose (logical) – silences warnings

Initialize with a filename

EXAMPLE:

input = fullfile(pwd, 'sub-01_ses-02_T1w.nii');
file = bids.File(input);

Initialize with a structure

EXAMPLE:

input = struct('ext', '.nii', ...
               'suffix', 'T1w', ...
               'entities', struct('sub', '01', ...
                                  'ses', '02'));
file = bids.File(input);

Remove prefixes and add a ``desc-preproc`` entity-label pair

EXAMPLE:

input = 'wuasub-01_ses-test_task-faceRecognition_run-02_bold.nii';
file = bids.File(input, 'use_schema', false);
file.prefix = '';
file.entities.desc = 'preproc';
disp(file.filename)

Use the BIDS schema to get entities in the right order

EXAMPLE:

input.suffix = 'bold';
input.ext = '.nii';
input.entities = struct('sub', '01', ...
                        'acq', '1pt5', ...
                        'run', '02', ...
                        'task', 'face recognition');

file = bids.File(name_spec, 'use_schema', true);

prefix = "''"

bids prefix

extension = "''"

file extension

suffix = "''"

file suffix

entities = 'struct([])'

list of entities

modality = "''"

name of file modality

path = "''"

absolute path

bids_path = "''"

path within dataset

filename = "''"

bidsified name

json_filename = "''"

bidsified name for json file

metadata_files = '{}'

list of metadata files related

metadata = None

list of metadata for this file

entity_required = '{}'

Required entities

entity_order = '{}'

Expected order of entities

schema = '[]'

BIDS schema used

update()

executed automatically before getting a value

reorder_entities(entity_order)

USAGE:

file = file.reorder_entities(entity_order);

Parameters:

entity_order (cell of char) – Optional. The order of the entities.

If the no entity order is provided, it will try to rely on the schema to find an appropriate order

EXAMPLE:

% filename with ses entity in the wrong position
filename = 'wuasub-01_task-faceRecognition_ses-test_run-02_bold.nii';
file = bids.File(filename, 'use_schema', false);
file = file.reorder_entities({'sub', 'ses'});

% use the schema to do the reordering
filename = 'wuasub-01_task-faceRecognition_ses-test_run-02_bold.nii';
file = bids.File(filename, 'use_schema', false);
file = file.use_schema();
file = file.reorder_entities();

rename(varargin)

Renames a file according following some specification

USAGE:

file = file.rename('spec', spec, 'dry_run', true, 'verbose', [], 'force', false);

Parameters:

• spec (structure) – structure specifying what entities, suffix, extension… to apply

• dry_run (logical) – If true no file is actually renamed. true is the default to avoid renaming files by mistake.

• verbose (logical) – displays input --> output

• force (logical) – Overwrites existing file.

EXAMPLE:

%% rename an SPM preprocessed file

% expected_name = fullfile(pwd, ...
%                         'sub-01', ...
%                         'sub-01_task-faceRep_space-individual_desc-preproc_bold.nii');

input_filename = 'uasub-01_task-faceRep_bold.nii';

file = bids.File(input_filename, 'use_schema', false);

spec.prefix = ''; % remove prefix
spec.entities.desc = 'preproc'; % add description entity
spec.entity_order = {'sub', 'task', 'desc'};

file = file.rename('spec', spec, 'dry_run', false, 'verbose', true);


%% Get a specific file from a dataset to rename

BIDS = bids.layout(path_to_dataset)

% construct a filter to get only the file we want/
subject = '001';
run = '001';
suffix = 'bold';
task = 'faceRep';
filter = struct('sub', subject, 'task', task, 'run', run, 'suffix', suffix);

file_to_rename = bids.query(BIDS, 'data', filter);

file = bids.File(file_to_rename, 'use_schema', false);

% specification to remove run entity
spec.entities.run = '';

% first run with dry_run = true to make sure we will get the expected output
file = file.rename('spec', spec, 'dry_run', true, 'verbose', true);

% rename the file by setting dry_run to false
file = file.rename('spec', spec, 'dry_run', false, 'verbose', true);

use_schema()

Loads BIDS schema into instance and tries to update properties:

• file.modality

• file.required_entity

• file.entity_order

• file.relative_pth

USAGE:

file = file.use_schema();

validate_entities()

use entity_order got from schema as a proxy for allowed entity keys

USAGE:

file.validate_entities();

get_required_entities()

USAGE:

[file, required_entities] = file.get_required_entities()

get_modality_from_schema()

USAGE:

[file, modality] = file.get_modality_from_schema()

get_entity_order_from_schema()

USAGE:

[file, entity_order] = file.get_entity_order_from_schema()

check_required_entities()

USAGE:

file.check_required_entities()