Merge pull request #44 from Remi-Gau/remi-simplify_saveEvents

Simplify save events

Author: Remi-Gau

README.md

@@ -6,6 +6,7 @@
 
 - [CPP_BIDS](#cpp_bids)
   - [Usage](#usage)
+    - [To save events.tsv file](#to-save-eventstsv-file)
   - [Functions descriptions](#functions-descriptions)
     - [userInputs](#userinputs)
     - [createFilename](#createfilename)
@@ -24,6 +25,8 @@ A set of function for matlab and octave to create [BIDS-compatible](https://bids
 
 ## Usage
 
+### To save events.tsv file
+
 ```matlab
 
 % define the folder where the data will be saved
@@ -36,14 +39,12 @@ expParameters.task = 'testtask';
 % expParameters = userInputs;
 
 % or declare it directly
-expParameters.subjectGrp = '';
 expParameters.subjectNb = 1;
-expParameters.sessionNb = 1;
 expParameters.runNb = 1;
 
 % by default we assume you are running things on a behavioral PC with no eyetracker
-cfg.eyeTracker = false;
-cfg.testingDevice = 'PC';
+% cfg.eyeTracker = false;
+% cfg.testingDevice = 'PC';
 
 % if the testing device is set to 'PC' then the data will be saved in the `beh` folder
 % if set to 'mri' then the data will be saved in the `func` folder
@@ -54,34 +55,88 @@ cfg.testingDevice = 'PC';
 % create the filenames: this include a step to check that all the information is there (checkCFG)
 [cfg, expParameters] = createFilename(cfg, expParameters);
 
-% initialize the events files with the typical BIDS
-% columns (onsets, duration, trial_type)
-% and add some more in this case (Speed and is_Fixation)
-logFile = saveEventsFile('open', expParameters, [], 'Speed', 'is_Fixation');
+% initialize the events files with the typical BIDS columns (onsets, duration, trial_type)
+% logFile = saveEventsFile('open', expParameters);
 
-% to initialize a stim file in case you want to store the info about the stimuli in it
-stimFile = saveEventsFile('open_stim', expParameters, []);
+% You can add some more in this case (Speed and is_Fixation)
+logFile.extraColumns = {'Speed', 'is_Fixation'};
+logFile = saveEventsFile('open', expParameters, logFile);
 
-% create the information about 2 events that we want to save
+% The information about 2 events that we want to save
+% NOTE : If the user DOES NOT provide `onset`, `trial_type`, this events will be skipped.
 logFile(1,1).onset = 2;
 logFile(1,1).trial_type = 'motion_up';
 logFile(1,1).duration = 1;
-logFile(1,1).speed = 2;
-logFile(1,1).is_fixation = true;
+logFile(1,1).Speed = 2;
+logFile(1,1).is_Fixation = true;
 
 logFile(2,1).onset = 3;
 logFile(2,1).trial_type = 'static';
 logFile(2,1).duration = 4;
-logFile(2,1).is_fixation = 3;
+logFile(2,1).is_Fixation = 3;
 
 % add those 2 events to the events.tsv file
-saveEventsFile('save', expParameters, logFile, 'speed', 'is_fixation');
+saveEventsFile('save', expParameters, logFile);
 
 % close the file
 saveEventsFile('close', expParameters, logFile);
 
 ```
 
+If you want to save more complex events.tsv file you can save several columns at once.
+
+```matlab
+expParameters.subjectNb = 1;
+expParameters.runNb = 1;
+expParameters.task = 'testtask';
+expParameters.outputDir = outputDir;
+
+cfg.testingDevice = 'mri';
+
+[cfg, expParameters] = createFilename(cfg, expParameters);
+
+% You can specify how many columns we want for each variable
+% will set 1 columns with name Speed
+% will set 12 columns with names LHL24-01, LHL24-02, ...
+% will set 1 columns with name is_Fixation
+
+logFile.extraColumns.Speed.length = 1;
+logFile.extraColumns.LHL24.length = 12;
+logFile.extraColumns.is_Fixation.length = 1;
+
+logFile = saveEventsFile('open', expParameters, logFile);
+
+logFile(1, 1).onset = 2;
+logFile(end, 1).trial_type = 'motion_up';
+logFile(end, 1).duration = 3;
+logFile(end, 1).Speed = 2;
+logFile(end, 1).is_Fixation = true;
+logFile(end, 1).LHL24 = 1:12;
+
+saveEventsFile('save', expParameters, logFile);
+
+saveEventsFile('close', expParameters, logFile);
+
+```
+
+If you have many columns to define but only a few with several columns, you can do this:
+
+```matlab
+% define the extra columns: they will be added to the tsv files in the order the user input them
+logFile.extraColumns = {'Speed', 'is_Fixation'};
+
+[cfg, expParameters] = createFilename(cfg, expParameters);
+
+% dummy call to initialize the logFile variable
+logFile = saveEventsFile('open', expParameters, logFile);
+
+% set the real length we really want
+logFile.extraColumns.Speed.length = 12;
+
+% actual inititalization
+logFile = saveEventsFile('open', expParameters, logFile);
+```
+
 ## Functions descriptions
 
 ### userInputs
@@ -127,7 +182,11 @@ For the moment the date of acquisition is appended to the filename
 
 Function to save output files for events that will be BIDS compliant.
 
+If the user DOES NOT provide `onset`, `trial_type`, this events will be skipped. `duration` will be set to "NaN" if 
+no value is provided.
+
 ### checkCFG
+
 Check that we have all the fields that we need in the experiment parameters.
 
 ## How to install

checkCFG.m

@@ -2,19 +2,19 @@
     % check that we have all the fields that we need in the experiment parameters
 
     %% set the expParameters defaults
-    
+
     fieldsToSet.verbose = 0;
     fieldsToSet.outputDir = fullfile( ...
-            fileparts(mfilename('fullpath')), ...
-            '..', ...
-            'output');
+        fileparts(mfilename('fullpath')), ...
+        '..', ...
+        'output');
 
     fieldsToSet.subjectGrp = []; % in case no group was provided
-    fieldsToSet.sessionNb = []; % in case no session was provided
+    fieldsToSet.sessionNb = 1; % in case no session was provided
     fieldsToSet.askGrpSess = [true true];
-    
+
     % BIDS
-    
+
     % dataset description json
     % required
     fieldsToSet.bids.datasetDescription.json.Name = '';
@@ -27,7 +27,7 @@
     fieldsToSet.bids.datasetDescription.json.Funding = {''};
     fieldsToSet.bids.datasetDescription.json.ReferencesAndLinks = {''};
     fieldsToSet.bids.datasetDescription.json.DatasetDOI = '';
-    
+
     % mri
     % for json
     fieldsToSet.MRI.repetitionTime = [];
@@ -37,38 +37,39 @@
     fieldsToSet.MRI.rec = []; % reconstruction of fMRI images
     fieldsToSet.MRI.echo = []; % echo fMRI images
     fieldsToSet.MRI.acq = []; % acquisition of fMRI images
-    
-    %% loop through the defaults and set them in expParameters if they don't exist
-    names = fieldnames(fieldsToSet);
-    
-    for i = 1:numel(names)
-        expParameters = setFieldToIfNotPresent(...
-            expParameters, ...
-            names{i}, ...
-            getfield(fieldsToSet, names{i})); %#ok<GFLD>
-    end
-    
+
+    expParameters = setDefaults(expParameters, fieldsToSet);
+
     %% set the cfg defaults
-    
-    clear fieldsToSet
+
+    clear fieldsToSet;
     fieldsToSet.testingDevice = 'pc';
     fieldsToSet.eyeTracker = false;
-    
-    % loop through the defaults and set them in cfg if they don't exist
+
+    cfg = setDefaults(cfg, fieldsToSet);
+
+end
+
+function structure = setDefaults(structure, fieldsToSet)
+    % loop through the defaults fiels to set and update if they don't exist
+
     names = fieldnames(fieldsToSet);
-    
+
     for i = 1:numel(names)
-        cfg = setFieldToIfNotPresent(...
-            cfg, ...
+
+        thisField = fieldsToSet.(names{i});
+
+        structure = setFieldToIfNotPresent( ...
+            structure, ...
             names{i}, ...
-            getfield(fieldsToSet, names{i})); %#ok<GFLD>
+            thisField);
+
     end
 
 end
 
-
-function struct = setFieldToIfNotPresent(struct, fieldName, value)
-    if ~isfield(struct, fieldName)
-        struct = setfield(struct, fieldName, value); %#ok<SFLD>
+function structure = setFieldToIfNotPresent(structure, fieldName, value)
+    if ~isfield(structure, fieldName)
+        structure.(fieldName) = value;
     end
-end
+end

createFilename.m

@@ -21,6 +21,23 @@
 
     [cfg, expParameters] = checkCFG(cfg, expParameters);
 
+    if ~isfield(expParameters, 'task')
+        error('createFilename: missing a task name. i.e expParameters.task');
+    end
+
+    expParameters = getModality(cfg, expParameters);
+
+    expParameters = createDirectories(cfg, expParameters);
+
+    expParameters = setSuffixes(expParameters);
+
+    expParameters = setFilenames(cfg, expParameters);
+
+    talkToMe(cfg, expParameters);
+
+end
+
+function expParameters = getModality(cfg, expParameters)
     switch lower(cfg.testingDevice)
         case 'pc'
             modality = 'beh';
@@ -35,16 +52,8 @@
         otherwise
             modality = 'beh';
     end
-    expParameters.modality = modality;
-
-    expParameters = createDirectories(cfg, expParameters);
-
-    expParameters = setSuffixes(expParameters);
-
-    expParameters = setFilenames(cfg, expParameters);
-
-    talkToMe(cfg, expParameters);
 
+    expParameters.modality = modality;
 end
 
 function [subjectGrp, subjectNb, sessionNb, modality] = extractInput(expParameters)
@@ -54,6 +63,10 @@
     sessionNb = expParameters.sessionNb;
     modality = expParameters.modality;
 
+    if isempty(sessionNb)
+        sessionNb = 1;
+    end
+
 end
 
 function expParameters = createDirectories(cfg, expParameters)

miss_hit.cfg

@@ -1,3 +1,3 @@
 line_length: 100
-regex_function_name: "[a-z]+(([A-Z]|[0-9]){1}[a-z]+)*"
+regex_function_name: "[a-z]+(([A-Z]){1}[A-Za-z]+)*"
 suppress_rule: "copyright_notice"