BIDS stats model handling

See the BIDS stats model website for more information.

class bids.Model

Class to deal with BIDS stats models

See the BIDS stats model website for more information.

USAGE:: matlab

bm = bids.Model(‘init’, true, …
‘file’, path_to_bids_stats_model_file, … ‘tolerant’, true, ‘verbose’, false);

Parameters:

init (logical) – if true this will initialize an empty model. Defaults to false.
file (path) – fullpath the JSON file containing the BIDS stats model
tolerant (logical) – turns errors into warning
verbose (logical) – silences warnings

Examples

% initialize and write an empty model
bm = bids.Model('init', true);
filename = fullfile(pwd, 'model-foo_smdl.json');
bm.write(filename);

% load a stats model from a file
model_file = fullfile(get_test_data_dir(), ...
                      '..', ...
                      'data', ...
                      'model', ['model-narps_smdl.json']);

bm = bids.Model('file', model_file, 'verbose', false);

Property Summary

content: “raw” content of a loaded JSON

Name: Name of the model

Description: Description of the model

BIDSModelVersion: Version of the model

Input: Input of the model

Nodes: Nodes of the model

Edges: Edges of the model

tolerant: if true turns error into warning

verbose: hides warning if false

dag_built: if the directed acyclic graph has been built

Method Summary

get_nodes(varargin)

Get a specific node from the model given its Level and / or Name.

USAGE:

[value, idx] = bm.get_nodes('Level', '', 'Name', '')

Parameters:

Level – Must be one of Run, Session, Subject, Dataset. Default to ''
Name – Default to ''

Returns: value - Node(s) as struct if there is only one or a cell if more: idx - Node index

Example

bm = bids.Model('file', model_file('narps'), 'verbose', false);

% Get all nodes
bm.get_nodes()

% Get run level node
bm.get_nodes('Level', 'Run')

% Get the "Negative" node
bm.get_nodes('Name', 'negative')

get_edge(field, value)

USAGE:

edge = bm.get_edges(field, value)

field can be any of {‘Source’, ‘Destination’}

get_edges_from_nodes()

Generates all the default edges from the list of nodes in the model.

USAGE:

bm = bm.get_edges_from_nodes();
edges = bm.Edges();

validate()

Very light validation of fields that were not checked on loading. Automatically run on loaoding of a dataset.

USAGE:

bm.validate()

validate_edges()

USAGE:

bm.validate_edges()

get_transformations(varargin)

USAGE:

transformations = bm.get_transformations('Name', 'node_name')

Parameters:: Name (char) – name of the node whose transformations we want

get_dummy_contrasts(varargin)

USAGE:

dummy_contrasts = bm.get_dummy_contrasts('Name', 'node_name')

Parameters:: Name (char) – name of the node whose dummy contrasts we want

get_contrasts(varargin)

USAGE:

contrasts = bm.get_contrasts('Name', 'node_name')

Parameters:: Name (char) – name of the node whose contrasts we want

get_model(varargin)

USAGE:

model = bm.get_model('Name', 'node_name')

Parameters:: Name (char) – name of the node whose model we want

get_design_matrix(varargin)

USAGE:

matrix = bm.get_design_matrix('Name', 'node_name')

Parameters:: Name (char) – name of the node whose model matrix we want

default(varargin)

Generates a default BIDS stats model for a given data set

USAGE:

bm = bm.default(BIDS, tasks)

Parameters:

BIDS (path or structure) – fullpath to a BIDS dataset or output structure from bids.layout
tasks (char or cellstr) – tasks to include in the model

Example

pth_bids_example = get_test_data_dir();
BIDS = bids.layout(fullfile(pth_bids_example, 'ds003'));
bm = bids.Model();
bm = bm.default(BIDS, 'rhymejudgement');
filename = fullfile(pwd, 'model-rhymejudgement_smdl.json');
bm.write(filename);

update()

Update content for writing

USAGE:

bm = bm.update()

write(filename)

USAGE:

bm.write(filename)

static empty_node(level)

USAGE:

node = Model.empty_node('run')

static empty_transformations()

USAGE:

transformations = Model.empty_transformations()

static empty_model()

USAGE:

model = Model.empty_model()