Transformers¶

Those transformers are meant to be used to manipulate the content of TSV files once loaded as structure with bids.util.tsvread.

They are mostly meant to be used to implement the transformations described in BIDS stats models but can also be used to manipulate TSV files in batches.

For each type of transformer, we describe first how they are meant to be “called” in the JSON file of the BIDS stats model.

There is also an code example to show how to use them.

The behavior and their “call” in JSON should (hopefully) be fairly close to the pybids-transformers.

Applying transformations¶

An “array” of transformations can be applied one after the other using bids.transformers().

+bids.transformers(varargin)¶

Apply transformers to a structure

USAGE:

new_content = transformers(trans, data)

Parameters:

transformers (structure) –
data (structure) –

Returns:

new_content:

(structure)
json:

(structure) json equivalent of the transformers

EXAMPLE:

data = bids.util.tsvread(path_to_tsv);

% load transformation instruction from a model file
bm = bids.Model('file', model_file);
transformers = bm.get_transformations('Level', 'Run');

% apply transformers
new_content = bids.transformers(transformers.Instructions, data);

% if all fields in the structure have the same number of rows one
% create a new tsv file
bids.util.tsvwrite(path_to_new_tsv, new_content)

Basic operations¶

Add
Subtract
Multiply
Divide
Power

+bids.+transformers_list.Basic(transformer, data)¶

Performs a basic operation with a Value on the Input

JSON EXAMPLE:

{
  "Name":  "Add",
  "Input": "onset",
  "Value": 0.5,
  "Output": "delayed_onset"
  "Query": "familiarity == Famous face"
}

Each of these transformations takes one or more columns, and performs a mathematical operation on the input column and a provided operand. The operations are performed on each column independently.

Arguments:

Parameters:

Name – mandatory. Any of Add, Subtract, Multiply, Divide, Power.
Input (string or array) – mandatory. A array of columns to perform operation on.
Value (float) – mandatory. The value to perform operation with (i.e. operand).
Query (string) – Optional. logical expression used to select on which rows to act.
Output (string or array) – Optional. List of column names to write out to.

By default, computation is done in-place on the input (meaning that input columns are overwritten). If provided, the number of values must exactly match the number of input values, and the order will be mapped 1-to-1.

CODE EXAMPLE:

transformer = struct('Name', 'Subtract', ...
                      'Input', 'onset', ...
                      'Value', 3, ...
                      'Ouput', 'onset_minus_3');

data.onset = [1; 2; 5; 6];

data = bids.transformers(transformer, data);

data.onset_minus_3

ans =

      -2
      -1
       2
       3

Logical operations¶

And
Or
Not

+bids.+transformers_list.Logical(transformer, data)¶

Each of these transformations:

takes 2 or more columns as input
performs the corresponding logical operation

inclusive or

conjunction

logical negation

returning a single column as output.

JSON EXAMPLE:

{
  "Name":  "And",
  "Input": ["sex_m", "age_gt_twenty"],
  "Output": "men_older_twenty"
}

If non-logical input are passed, it is expected that:

all zero or nan (for numeric data types),
“NaN” or empty (for strings) values

will evaluate to false and all other values will evaluate to true.

Arguments:

Parameters:

Name – mandatory. Any of And, Or, Not.
Input (array) – mandatory. An array of columns to perform operation on. Only 1 for Not
Output (string or array) – Optional. The name of the output column.

CODE EXAMPLE:

transformers = struct('Name', 'And', ...
                      'Input', {{'sex_m', 'age_gt_twenty'}}, ...
                      'Output', 'men_gt_twenty');

data.age_gt_twenty = [nan; 25; 51; 12];
data.sex_m = {'M'; 'M'; nan; 'M'};

data = bids.transformers(transformer, data);

ans =

  4x1 logical array

   0
   1
   0
   1

Munge operations¶

Transformations that primarily involve manipulating/munging variables into other formats or shapes.

Assign¶

+bids.+transformers_list.Assign(transformer, data)¶

The Assign transformation assigns one or more variables or columns (specified as the input) to one or more other columns (specified by target and/or output as described below).

JSON EXAMPLE:

{
  "Name": "Assign",
  "Input": ["response_time"],
  "Target": ["face"],
  "TargetAttr": "duration",
  "Output": ["face_modulated_by_RT"]
}

Arguments:

Parameters:

Input (string or array) – mandatory. The name(s) of the columns from which attribute values are to be drawn (for assignment to the attributes of other columns). Must exactly match the length of the target argument.
Target (string or array) – mandatory. the name(s) of the columns to which the attribute values taken from the input are to be assigned. Must exactly match the length of the input argument. Names are mapped 1-to-1 from input to target.

Note

If no output argument is specified, the columns named in target are modified in-place.

Parameters:: Output (string or array) – Optional. Names of the columns to output the result of the assignment to. Must exactly match the length of the input and target arguments.

If no output array is provided, columns named in target are modified in-place.

If an output array is provided:

each column in the target array is first cloned,

then the reassignment from the input to the target is applied;

finally, the new (cloned and modified) column is written out to the column named in output.

Parameters:

InputAttr (string or array) – Optional. Specifies which attribute of the input column to assign. Defaults to value. If a array is passed, its length must exactly match that of the input and target arrays.
TargetAttr (string or array) – Optional. Specifies which attribute of the output column to assign to. Defaults to value. If a array is passed, its length must exactly match that of the input and target arrays.

InputAttr and TargetAttr must be one of:

value,
onset,
or duration.

Note

This transformation is non-destructive with respect to the input column(s). In case where in-place assignment is desired (essentially, renaming a column), either use the rename transformation, or set output to the same value as the input.

Examples:

To reassign the value property of a variable named response_time to the duration property of a face variable (as one might do in order to, e.g., model trial-by-trial reaction time differences for a given condition using a varying-epoch approach), and write it out as a new face_modulated_by_RT column.

CODE EXAMPLE:

transformer = struct('Name', 'Assign', ...
                      'Input', 'response_time', ...
                      'Target', 'face', ...
                      'TargetAttr', 'duration', ...
                      'Ouput', 'face_modulated_by_RT');

data.response_time = ;
data.face = ;
data.duration = ;

data = bids.transformers(transformer, data);

data.face_modulated_by_RT

ans =

Concatenate¶

+bids.+transformers_list.Concatenate(transformer, data)¶

Concatenate columns together.

JSON EXAMPLE:

{
  "Name": "Concatenate",
  "Input": [
      "face_type",
      "face_repetition"
  ],
  "Output": "face_type_repetition"
}

Arguments:

Parameters:

Input (array) – mandatory. Column(s) to concatenate. Must all be of the same length.
Output (string) – Optional. Name of the output column.

CODE EXAMPLE:

transformer = struct('Name', 'Concatenate', ...
                      'Input', {{'face_type', 'face_repetition'}}, ...
                      'Ouput', 'face_type_repetition');

data.face_type = {'familiar'; 'unknwown'; 'new'; 'familiar'; 'unknwown'; 'new'};
data.face_repetition = [1;1;1;2;2;2];

data = bids.transformers(transformer, data);

data.face_type_repetition

ans =
   {
     'familiar_1'
     'unknwown_1'
     'new_1'
     'familiar_2'
     'unknwown_2'
     'new_2'
   }

Copy¶

+bids.+transformers_list.Copy(transformer, data)¶

Clones/copies each of the input columns to a new column with identical values and a different name. Useful as a basis for subsequent transformations that need to modify their input in-place.

JSON EXAMPLE:

{
  "Name": "Copy",
  "Input": [
      "sex_m",
      "age_gt_twenty"
  ],
  "Output": [
      "tmp_sex_m",
      "tmp_age_gt_twenty"
  ]
}

Arguments:

Parameters:

Input (string or array) – mandatory. Column names to copy.
Output (string or array) – Optional. Names to copy the input columns to. Must be same length as input, and columns are mapped one-to-one from the input array to the output array.

CODE EXAMPLE:

transformer = struct('Name', 'Copy', ...
                      'Input', 'onset', ...
                      'Ouput', 'onset_copy');

data.onset = [1,2,3];

data = bids.transformers(transformer, data);

data.onset_copy

ans = [1,2,3]

Delete¶

+bids.+transformers_list.Delete(transformer, data)¶

Deletes column(s) from further analysis.

JSON EXAMPLE:

{
  "Name": "Delete",
  "Input": [
      "sex_m",
      "age_gt_twenty"
  ]
}

Arguments:

Parameters:: Input (string or array) – mandatory. The name(s) of the columns(s) to delete.

Note

The Select transformation provides the inverse function (selection of columns to keep for subsequent analysis).

CODE EXAMPLE:

transformer = struct('Name', 'Delete', ...
                      'Input', {{'sex_m', age_gt_twenty}});

data.sex_m = TODO;
data.age_gt_twenty = TODO;

data = bids.transformers(transformer, data);

data.

ans = TODO

DropNA¶

+bids.+transformers_list.Drop_na(transformer, data)¶

Drops all rows with “n/a”.

JSON EXAMPLE:

{
  "Name": "DropNA",
  "Input": [
      "age_gt_twenty"
  ],
  "Output": [
      "age_gt_twenty_clean"
  ]
}

Arguments:

Parameters:

Input (string or array) – mandatory. The name of the variable to operate on.
Output (string or array) – Optional. The column names to write out to. By default, computation is done in-place meaning that input columnise overwritten).

CODE EXAMPLE:

transformer = struct('Name', 'DropNA', ...
                      'Input', 'age_gt_twenty', ...
                      'Ouput', 'age_gt_twenty_clean');

data.age_gt_twenty = TODO;

data = bids.transformers(transformer, data);

data.

ans = TODO

Factor¶

+bids.+transformers_list.Factor(transformer, data)¶

Converts a nominal/categorical variable with N unique levels to either N indicators (i.e., dummy-coding).

JSON EXAMPLE:

{
  "Name": "Factor",
  "Input": [
      "gender",
      "age"
  ]
}

Arguments:

Parameters:: Input (string or array) – mandatory. The name(s) of the variable(s) to dummy-code.

By default it is the first factor level when sorting in alphabetical order (e.g., if a condition has levels ‘dog’, ‘apple’, and ‘helsinki’, the default reference level will be ‘apple’).

The name of the output columns for 2 input columns gender and age with 2 levels (M, F) and (20, 30) respectivaly will of the shape:

gender_F_age_20
gender_F_age_20
gender_M_age_30
gender_M_age_30

CODE EXAMPLE:

transformer = struct('Name', 'Factor', ...
                     'Input', {{'gender', 'age'}});

data.gender = TODO;
data.age = TODO;

data = bids.transformers(transformer, data);

data.gender_F_age_20

ans = TODO

Filter¶

+bids.+transformers_list.Filter(transformer, data)¶

Subsets rows using a logical expression.

JSON EXAMPLE:

{
  "Name": "Filter",
  "Input": "sex",
  "Query": "age > 20"
}

Arguments:

Parameters:

Input (string or array) – mandatory. The name(s) of the variable(s) to operate on.
Query (string) – mandatory. logical expression used to filter

Supports:

>, <, >=, <=, ==, ~= for numeric values

==, ~= for string operation (case sensitive). Regular expressions are supported

Parameters:: Output (string or array) – Optional. The optional column names to write out to.

By default, computation is done in-place (i.e., input columnise overwritten). If provided, the number of values must exactly match the number of input values, and the order will be mapped 1-to-1.

CODE EXAMPLE:

transformer = struct('Name', 'Filter', ...
                      'Input', 'sex', ...
                      'Query', 'age > 20');

data.sex = {'M', 'F', 'F', 'M'};
data.age = [10, 21, 15, 26];

data = bids.transformers(transformer, data);

data.sex

  ans =

  4X1 cell array

      [NaN]
      'F'
      [NaN]
      'M'

Label identical rows¶

+bids.+transformers_list.Label_identical_rows(transformer, data)¶

Creates an extra column to index consecutive identical rows in a column. The index restarts at 1 with every change of row content. This can for example be used to label consecutive events of the same trial_type in a block.

JSON EXAMPLE:

{
  "Name": "LabelIdenticalRows",
  "Input": "trial_type",
  "Cumulative": False
}

Arguments:

Parameters:

Input (string or array) – mandatory. The name(s) of the variable(s) to operate on.
Cumulative (logical) – optional. Defaults to False. If True, the labels are not reset to 0 when encoutering new row content.

Note

The labels will be by default be put in a column called Input(i)_label

CODE EXAMPLE:

transformers(1).Name = 'LabelIdenticalRows';
transformers(1).Input = {'trial_type', 'stim_type'};

data.trial_type = {'face';'face';'house';'house';'house';'house';'chair'};
data.stim_type =  {1'    ; 1    ;1      ;2      ;5      ;2      ; nan};

new_content = bids.transformers(transformers, data);

assertEqual(new_content.trial_type_label, [1;2;1;2;3;4;1]);
assertEqual(new_content.stim_type_label,  [1;2;3;1;1;1;1]);

Merge identical rows¶

+bids.+transformers_list.Merge_identical_rows(transformer, data)¶

Merge consecutive identical rows.

JSON EXAMPLE:

{
  "Name": "MergeIdenticalRows",
  "Input": "trial_type",
}

Arguments:

Parameters:: Input (string or array) – mandatory. The name(s) of the variable(s) to operate on.

Note

Only works on data commit from event.tsv
Content is sorted by onset time before merging
If multiple variables are specified, they are merged in the order they are specified
If a variable is not found, it is ignored
If a variable is found, but is empty, it is ignored
The content of the other columns corresponds to the last row being merged: this means that the content from other columns but the one specified in will be deleted execpt for the last one

CODE EXAMPLE:

transformers(1).Name = 'MergeIdenticalRows';
transformers(1).Input = {'trial_type'};

data.trial_type = {'house' ; 'face'  ; 'face'; 'house'; 'chair'; 'house' ; 'chair'};
data.duration =   [1       ; 1       ; 1     ; 1      ; 1      ; 1       ; 1];
data.onset =      [3       ; 1       ; 2     ; 6      ; 8      ; 4       ; 7];
data.stim_type =  {'delete'; 'delete'; 'keep'; 'keep' ; 'keep' ; 'delete'; 'delete'};

new_content = bids.transformers(transformers, data);

new_content.trial_type
ans =
  3X1 cell array
    'face'
    'house'
    'chair'

new_content.stim_type
ans =
  3X1 cell array
    'keep'
    'keep'
    'keep'

new_content.onset
ans =
     1
     3
     7

new_content.duration
ans =
     2
     4
     2

Replace¶

+bids.+transformers_list.Replace(transformer, data)¶

Replaces values in one or more input columns.

JSON EXAMPLE:

{
  "Name": "Replace",
  "Input": [
      "fruits",
  ],
  "Replace": [
          {"key": "apple",   "value": "bee"},
          {"key": "elusive", "value": 5},
          {"key": -1, "value": 0}]
   ],
   "Attribute": "all"
}

Arguments:

Parameters:

Input (string or array) – mandatory. Name(s of column(s) to search and replace within.
Replace (array of objects) – mandatory. The mapping old values ("key") to new values. ("value"). key can be a regular expression.
Attribute (array) – Optional. The column attribute to apply the replace to.

Valid values include:

"value" (the default),
"duration",
"onset",
and "all".

In the last case, all three attributes ("value", "duration", and "onset") will be scanned.

Parameters:: Output (string or array) – Optional. Optional names of columns to output. Must match length of input column(s) if provided, and columns will be mapped 1-to-1 in order. If no output values are provided, the replacement transformation is applied in-place to all the inputs.

CODE EXAMPLE:

data.fruits = {'apple'; 'banana'; 'elusive'};
data.onset = {1; 2; 3};
data.duration = {-1; 1; 3};

replace = struct('key', {'apple'; 'elusive'}, 'value', -1);
replace(end+1).key = -1;
replace(end).value = 0;

transformer = struct('Name', 'Replace', ...
                     'Input', 'fruits', ...
                     'Attribute', 'all', ...
                     'Replace', replace);

data = bids.transformers(transformer, data);


data.fruits

  ans =
    3X1 cell array
      [     0]
      'banana'
      [     0]

data.onset

  ans =
    3x1 cell array
      [1]
      [2]
      [3]

data.duration

  ans =
    3X1 cell array
      [-1]
      [ 1]
      [ 3]

Select¶

+bids.+transformers_list.Select(transformer, data)¶

The select transformation specifies which columns to retain for subsequent analysis.

Any columns that are not specified here will be dropped.

The only exception is when dealing with data with onset and duration columns (from *_events.tsv files) in this case the onset and duration column are also automatically selected.

JSON EXAMPLE:

{
  "Name": "Select",
  "Input": [
      "valid_trials",
      "reaction_time"
  ]
}

Arguments:

Parameters:: Input (string or array) – mandatory. The names of all columns to keep. Any columns not in this array will be deleted and will not be available to any subsequent transformations or downstream analyses.

Note

one can think of select as the inverse the Delete transformation that removes all named columns from further analysis.

CODE EXAMPLE:

transformer = struct('Name', 'Select', ...
                      'Input',  {{'valid_trials', 'reaction_time'}});

data.valid_trials = TODO
data.invalid_trials = TODO
data.reaction_time = TODO
data.onset = TODO
data.duration = TODO

data = bids.transformers(transformer, data);

data = TODO

ans = TODO

Split¶

+bids.+transformers_list.Split(transformer, data)¶

Split a variable into N variables as defined by the levels of one or more other variables.

JSON EXAMPLE:

{
  "Name": "Split",
  "Input": [
      "sex",
  ],
  "By": [
      "sex_m",
      "age_gt_twenty"
  ]
}

Arguments:

Parameters:

Input (array) – mandatory. The name of the variable(s) to operate on.
By (array) – Optional. Name(s) for variable(s) to split on.

For example, for given a variable Condition that we wish to split on two categorical columns A and B, where a given row has values A=a and B=1, the generated name will be Condition_BY_A_a_BY_B_1.

CODE EXAMPLE:

transformer = struct('Name', 'Split', ...
                      'Input', 'sex', ...
                      'By', {{'sex_m', 'age_gt_twenty'}});

data.sex = TODO;
data.sex_m = TODO;
data.age_gt_twenty = TODO

data = bids.transformers_list.split(transformer, data);

data.sex_BY % TODO

ans = TODO

Compute operations¶

Transformations that primarily involve numerical computation on variables.

Constant¶

+bids.+transformers_list.Constant(transformer, data)¶

Adds a new column with a constant value (numeric or char).

JSON EXAMPLE:

{
  "Name":  "Constant",
  "Value": 1,
  "Output": "intercept"
}

Arguments:

Parameters:

Output (string or array) – mandatory. Name of the newly generated column.
Value (float or char) – Optional. The value of the constant, defaults to 1.

CODE EXAMPLE:

transformer = struct('Name', 'Constant', ...
                      'Value', 1, ...
                      'Output', 'intercept');

data = bids.transformers(transformer, data);

ans = TODO

Mean¶

+bids.+transformers_list.Mean(transformer, data)¶

Compute mean of a column.

JSON EXAMPLE:

{
  "Name":  "Mean",
  "Input": "reaction_time",
  "OmitNan": false,
  "Output": "mean_RT"
}

Arguments:

Parameters:

Input (string or array) – mandatory. The name of the variable to operate on.
OmitNan (logical) – Optional. If false any column with nan values will return a nan value. If true nan values are skipped. Defaults to false.
Output (string or array) – Optional. The optional column names to write out to. By default, computation is done in-place (i.e., input columnise overwritten).

CODE EXAMPLE:

transformer = struct('Name', 'Mean', ...
                      'Input', 'reaction_time', ...
                      'OmitNan', false, ...
                      'Ouput', 'mean_RT');

data.reaction_time = TODO

data = bids.transformers(transformer, data);

data.mean_RT = TODO

ans = TODO

Product¶

+bids.+transformers_list.Product(transformer, data)¶

Computes the row-wise product of two or more columns.

JSON EXAMPLE:

{
  "Name":  "Product",
  "Input": ["duration", "reaction_time"],
  "Output": "duration_X_reaction_time",
  "OmitNan": false,
}

Arguments:

Parameters:

Input (array) – mandatory. Names of two or more columns to compute the product of.
Output (string or array) – mandatory. Name of the newly generated column.
OmitNan (logical) – Optional. If false any column with nan values will return a nan value. If true nan values are skipped. Defaults to false.

CODE EXAMPLE:

transformer = struct('Name', 'Product', ...
                      'Input', {'duration', 'reaction_time'}, ...
                      'OmitNan', false, ...
                      'Ouput', 'duration_X_reaction_time');


data = bids.transformers(transformer, data);


ans = TODO

Scale¶

+bids.+transformers_list.Scale(transformer, data)¶

Scales the values of one or more columns.

Semantics mimic scikit-learn, such that demeaning and rescaling are treated as independent arguments, with the default being to apply both (i.e., standardizing each value so that it has zero mean and unit SD).

JSON EXAMPLE:

{
  "Name":  "Scale",
  "Input": "reaction_time",
  "Demean": true,
  "Rescale": true,
  "ReplaceNa": true,
  "Output": "scaled_reaction_time"
}

Arguments:

Parameters:

Input (string or array) – mandatory. Names of columns to standardize.
Demean (logical) – Optional. If true, subtracts the mean from each input column (i.e., applies mean-centering).
Rescale (logical) – Optional. If true, divides each column by its standard deviation.
ReplaceNa (logical) – Optional. Whether/when to replace missing values with 0. If "off", no replacement is performed. If "before", missing values are replaced with 0 before scaling. If "after", missing values are replaced with 0 after scaling. Defaults to "off"
Output (string or array) – Optional. Optional names of columns to output. Must match length of input column if provided, and columns will be mapped 1-to-1 in order. If no output values are provided, the scaling transformation is applied in-place to all the input.

CODE EXAMPLE:

transformer = struct('Name', 'Scale', ...
                     'Input', 'reaction_time',
                     'Demean', true,
                     'Rescale', true,
                     'ReplaceNa', true,
                     'Output', 'scaled_reaction_time');

data.reaction_time = TODO

data = bids.transformers(transformer, data);

data.scaled_reaction_time = TODO

ans = TODO

Std¶

+bids.+transformers_list.Std(transformer, data)¶

Compute the sample standard deviation.

JSON EXAMPLE:

{
  "Name":  "Std",
  "Input": "reaction_time",
  "OmitNan": false,
  "Output": "std_RT"
}

Arguments:

Parameters:

Input (string or array) – mandatory. The name of the variable to operate on.
OmitNan (logical) – Optional. If false any column with nan values will return a nan value. If true nan values are skipped. Defaults to false.
Output (string or array) – Optional. The optional column names to write out to. By default, computation is done in-place (i.e., input columnise overwritten).

CODE EXAMPLE:

transformer = struct('Name', 'Std', ...
                      'Input', 'reaction_time', ...
                      'OmitNan', false, ...
                      'Ouput', 'std_RT');

data.reaction_time = TODO

data = bids.transformers(transformer, data);

data.std_RT = TODO

ans = TODO

Sum¶

+bids.+transformers_list.Sum(transformer, data)¶

Computes the (optionally weighted) row-wise sums of two or more columns.

JSON EXAMPLE:

{
  "Name":  "Sum",
  "Input": ["duration", "reaction_time"],
  "Output": "duration_X_reaction_time",
  "Weights": [1, 0.5],
  "OmitNan": false,
}

Arguments:

Parameters:

Input (array) – mandatory. Names of two or more columns to sum.
Output (string or array) – mandatory. Name of the newly generated column.
OmitNan (logical) – Optional. If false any column with nan values will return a nan value. If true nan values are skipped. Defaults to false.
Weights (array) – Optional. Optional array of floats giving the weights of the columns. If provided, length of weights must equal to the number of values in input, and weights will be mapped 1-to-1 onto named columns. If no weights are provided, defaults to unit weights (i.e., simple sum).

CODE EXAMPLE:

transformer = struct('Name', 'Sum', ...
                      'Input',  {{'duration', 'reaction_time'}}, ...
                      'OmitNan', false, ...
                      'Weights': [1, 0.5], ...
                      'Ouput', 'duration_plus_reaction_time');

data.duration = TODO
data.reaction_time = TODO

data = bids.transformers(transformer, data);

data.duration_plus_reaction_time = TODO

ans = TODO

Threshold¶

+bids.+transformers_list.Threshold(transformer, data)¶

Thresholds input values at a specified cut-off and optionally binarizes the result.

JSON EXAMPLE:

{
  "Name":  "Threshold",
  "Input": "onset",
  "Threshold": 0.5,
  "Binarize": true,
  "Output": "delayed_onset"
}

Arguments:

Parameters:

Input (string or array) – mandatory. The name(s)of the column(s) to threshold/binarize.
Threshold (float) – Optional. The cut-off to use for thresholding. Defaults to 0.
Binarize (logical) – Optional. If true, thresholded values will be binarized (i.e., all non-zero values will be set to 1). Defaults to false.
Above (logical) – Optional. Specifies which values to retain with respect to the cut-off. If true, all value above the threshold will be kept; if false, all values below the threshold will be kept. Defaults to true.
Signed (logical) – Optional. Specifies whether to treat the threshold as signed (default) or unsigned.

For example, when passing above=true and threshold=3, if signed=true, all and only values above +3 would be retained. If signed=false, all absolute values > 3 would be retained (i.e.,values in the range -3 < X < 3 would be set to 0).

Parameters:: Output (string or array) – Optional. Optional names of columns to output. Must match length of input column if provided, and columns will be mapped 1-to-1 in order. If no output values are provided, the threshold transformation is applied in-place to all the inputs.

CODE EXAMPLE:

transformer = struct('Name', 'Threshold', ...
                      'Input', 'onset', ...
                      'Value', 3, ...
                      'Ouput', 'onset_minus_3');

data.onset = TODO

data = bids.transformers(transformer, data);

data.onset_minus_3 = TODO

ans = TODO