Function description

List of functions in the src folder.

src.convertSourceToRaw(varargin)

Function attempts to convert a source dataset created with CPP_BIDS into a valid BIDS data set.

USAGE:

convertSourceToRaw(cfg, 'filter', filter)
Parameters

  • cfg (structure) – cfg structure is needed only for providing the path in cfg.dir.output.

  • filter (structure) – bids.query filter to only convert a subset of files.

Output
  • creates

    a dummy README and CHANGE file

  • copies

    source directory to raw directory

  • removes

    the date suffix _date-* from the files where it is present

  • zips

    the _stim.tsv files.

src.createDataDictionary(cfg, logFile)

It creates the data dictionary to be associated with a _events.tsv file. It will create empty fields that you can then fill in manually in the JSON file.

USAGE:

createDataDictionary(cfg, logFile)
Parameters

  • cfg (structure) – Configuration. See checkCFG().

  • logFile (structure) – Contains the data you want to save.

src.createDatasetDescription(cfg)

It creates dataset_description.json and writes in every entry contained in cfg.bids.datasetDescription. The file should go in the root of a BIDS dataset.

USAGE:

createDatasetDescription(cfg)
Parameters

cfg (structure) – Configuration. See checkCFG().

Output
  • dataset_description.json

    (jsonfile)

src.createFilename(cfg)

It creates the BIDS compliant directories and fileNames for the behavioral output for this subject / session / run using the information from cfg.

The folder tree will always include a session folder.

Will also create the right fileName for the eyetracking data file. For the moment the date of acquisition is appended to the fileName.

USAGE:

[cfg] = createFilename(cfg)
Parameters

cfg (structure) – Configuration. See checkCFG().

Returns

cfg

(structure) Configuration update with the name of info about the participants.

The behavior of this function depends on:

  • cfg.testingDevice:

    • set to pc (dummy try) or beh can work for behavioral experiment.

    • set on mri for fMRI experiment.

    • set on eeg or ieeg can work for electro encephalography or intracranial eeg

    • set on meg can work for magneto encephalography

  • cfg.eyeTracker.do set to true, can work for simple eyetracking data.

See test_createFilename in the tests folder for more details on how to use it.

src.createJson(varargin)

Creates the side car JSON file for a run.

For JSON sidecars for bold files, this will only contain the minimum BIDS requirement and will likey be less complete than the info you could from a proper BIDS conversion.

USAGE:

createJson(cfg [, modality] [, extraInfo])
createJson(cfg [, extraInfo])
Parameters

  • cfg (structure) – Configuration. See checkCFG().

  • modality (string) – can be any of the following 'beh', 'func', 'eeg', 'ieeg', 'meg') to specify which JSON to save. If it is not provided it will read from cfg.fileName.modality.

  • extraInfo (structure) – contains information in the JSON file. Beware that the BIDS validator is pretty strict on what information can go in a JSON so this can be useful to store additional information in your source dataset but it might have to be cleaned up to create a valid BIDS dataset.

Output
  • *.json

    (jsonfile) The file name corresponds to the run + suffix depending on the arguments passed in.

src.saveCfg(varargin)

Saves config as JSON.

USAGE:

saveCfg(cfg [, filename])
Parameters

  • cfg (structure) – Required. Configuration. See checkCFG().

  • filename (path) – Optional. Fullpath filename for the output file.

Output

filename

If a filename is provided, this will be used as an output file (and will create any required directory).

If no filename is provided, it will try to create one based on the content of cfg.fileName and cfg.dir. This would for example create a file:

./output/source/sub-01/func/sub-01_task-testTask_run-001_date-202203181752_cfg.json

If this fails it will save the file in the pwd under 'date-yyyymmddHHMM_cfg.json'.

saveCfg can be used to save in a human readable format the extra parameters that you used to run your experiment. This will most likely make the json file non-bids compliant but it can prove useful, to keep this information in your source dataset for when you write your methods sections 2 years later after running the experiment. This ensures that those are the exact parameters you used and you won’t have to read them from the setParameters.m file and wonder if those might have been modified when running the experiment and you did not commit and tagged that change with git.

And for the love of the flying spaghetti monster do not save all your parameters in a .mat file: think of the case when you won’t have Matlab or Octave installed on a computer (plus not everyone uses those).

src.readAndFilterLogfile(columnName, filterBy, saveOutputTsv, varargin)

It will display in the command window the content of the output.tsv filtered by one element of a target column.

USAGE:

outputFiltered = readAndFilterLogfile(columnName, filterBy, saveOutputTsv, tsvFile)

outputFiltered = readAndFilterLogfile(columnName, filterBy, saveOutputTsv, cfg)
Parameters

  • columnName (char) – the header of the column where the content of interest is stored (for example for trigger will be trial_type)

  • filterBy (char) –

    The content of the column you want to filter out. Relies on the filter transformer of bids.matlab Supports:

    • >, <, >=, <=, == for numeric values

    • == for string operation (case sensitive)

    For example, trial_type==trigger or onset > 1.

  • saveOutputTsv (boolean) – flag to save the filtered output in a tsv file

  • tsvFile (string) – TSV file to filter

  • cfg (structure) – Configuration. See checkCFG(). If cfg is given as input the name of the TSV file to read will be infered from there.

Returns

outputFiltered

dataset with only the specified content, to see it in the command window use display(outputFiltered).

See also: bids.transformers.filter

src.saveEventsFile(action, cfg, logFile)

Function to save output files for events that will be BIDS compliant.

USAGE:

[logFile] = saveEventsFile(action, cfg, logFile)
Parameters

  • action (string) – Defines the operation to do. The different possibilities are 'init', 'init_stim', 'open', 'save' or 'close'. For more information on each case see below.

  • cfg (structure) – Configuration variable. See checkCFG().

  • logFile (structure) – (n x 1) The logFile variable that contains the n events you want to save must be a nx1 structure.

See tests/test_saveEventsFile() for more details on how to use it.

Example:

logFile(1,1).onset = 2;
logFile(1,1).trial_type = 'motion_up';
logFile(1,1).duration = 1;

Actions:

Example:

logFile = saveEventsFile('init', cfg, logFile)
logFile = saveEventsFile('init_stim', cfg, logFile)
logFile = saveEventsFile('open', cfg, logFile)
logFile = saveEventsFile('save', cfg, logFile)

  • 'init' and 'init_stim' are used for events and stimuli tsv files respectively. This initializes the extra columns to be save.

  • 'open' will create the file ID and return it in logFile.fileID using the information in the cfg structure. This file ID is then reused when calling that function to save data into this file. This creates the header with the obligatory 'onset', 'duration' required by BIDS and other columns can be specified in varargin.

    Example:

    logFile = saveEventsFile('open', cfg, logFile);

  • 'save' will save the data contained in logfile by using the file ID logFile.fileID. If saving a stimulus file then the only the fields of logFile.extraColumns will be saved. For regular _events.tsv files, then logFile must then contain:

    • logFile.onset

    • logFile.duration

    Otherwise it will be skipped.

    Example:

    logFile = saveEventsFile('save', cfg, logFile);

  • 'close' closes the file with file ID logFile.fileID. If cfg.verbose is superior to 1 then this will tell you where the file is located.

    Example:

    logFile = saveEventsFile('close', cfg, logFile)
src.userInputs(cfg)

Get subject, run and session number and make sure they are positive integer values. Can do a graphic user interface if cfg.useGUI is set to true

USAGE:

cfg = userInputs(cfg)
Parameters

cfg (structure) – Configuration. See checkCFG().

Returns

cfg

(structure) Configuration update with the name of info about the participants.

Behavior of this functions depends on cfg.subject.askGrpSess a 1 X 2 array of booleans (default is [true true]):

  • the first value set to false will skip asking for the participants group

  • the second value set to false will skip asking for the session