BIDS file handling

class bids.File

Class to deal with BIDS filenames

USAGE:

bf = 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

Examples

Initialize with a filename.

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

Initialize with a structure

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

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

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

Use the BIDS schema to get entities in the right order.

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

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

Load metadata (supporting inheritance).

bf = bids.File('tests/data/synthetic/sub-01/anat/sub-01_T1w.nii.gz');

Access metadata

bf.metadata()

  struct with fields:
    Manufacturer: 'Siemens'
    FlipAngle: 10

Modify metadata

% Adding new value

bf = bf.metadata_add('NewField', 'new value');
bf.metadata()

  struct with fields:
    manufacturer: 'siemens'
    flipangle: 10
    NewField: 'new value'

% Appending to existing value

bf = bf.metadata_append('NewField', 'new value 1');
bf.metadata()

  struct with fields:
    manufacturer: 'siemens'
    flipangle: 10
    NewField: {'new value'; 'new value 1'}

% Removing value

bf = bf.metadata_remove('NewField');
bf.metadata()

  struct with fields:
    manufacturer: 'siemens'
    flipangle: 10

Modify several fields of metadata

bf = bf.metadata_update('Description', 'source file', ...
                      'NewField', 'new value', ...
                      'manufacturer', []);
bf.metadata()

  struct with fields:
    flipangle: 10
    description: 'source file'
    NewField: 'new value'

Export metadata as json:

bf.metadata_write()

Property Summary

prefix: bids prefix

extension: file extension

suffix: file suffix

entities: 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: list of metadata for this file

entity_required: Required entities

entity_order: Expected order of entities

schema: BIDS schema used

Method Summary

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 If one of the entities in the spec contains a ‘.’ it will be replaced by pt.
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);

normalize_entities(~, entities, replace)

Clean up entities

Replaces “.” in entity label with “pt”.

USAGE:

entities = file.normalize_entities(entities);

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()

metadata_update(varargin)

Update stored metadata with new values passed in varargin, which can be either a structure, or pairs of key-values.

See also: bids.util.update_struct

USAGE:

f = f.metadata_update(key1, value1, key2, value2);
f = f.metadata_update(struct(key1, value1, ...
                      key2, value2));

metadata_add(field, value): Add a new field (or replace existing) to the metadata structure

metadata_append(field, value): Append new value to a metadata.(field) If metadata.(field) is a chararray, it will be first transformed into cellarray.

metadata_remove(field): Removes field from metadata

metadata_write(varargin)

Export current content of metadata to sidecar json with same name as current file.

Metadata fields can be modified with new values passed in varargin, which can be either a structure, or pairs of key-values. These modifications do not affect current File object, and only exported into file. Use bids.File.metadata_update to update current metadata. Returns full path to the exported sidecar json file.

See also: bids.util.update_struct

USAGE:

f.metadata_write(key1, value1, key2, value2);
f.metadata_write(struct(key1, value1, ...
                        key2, value2));

get_modality(entities)

Retrieves modality out of the path

Only works if ses and sub entities match those found in the path