Merge pull request #12 from Remi-Gau/remi-doc

improve doc

Author: Remi-Gau

.gitignore

@@ -0,0 +1,8 @@
+*DS_Store
+
+*.m~
+*octave-workspace
+
+# exclude content of logfiles folders
+*.tsv
+*.mat

README.md

@@ -2,6 +2,24 @@
 
 A set of function for matlab and octave to create [BIDS-compatible](https://bids-specification.readthedocs.io/en/stable/) folder structure and filenames for the output of behavioral, EEG, fMRI, eyetracking studies.
 
+Here are the naming templates used.
+
+-   BOLD
+
+`sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>]_<contrast_label>.nii[.gz]`
+
+-   iEEG
+
+`sub-<label>[_ses-<label>]_task-<task_label>[_run-<index>]_ieeg.json`
+
+-   EEG
+
+`sub-<label>[_ses-<label>]_task-<label>[_run-<index>]_eeg.<manufacturer_specific_extension>`
+
+-   Eyetracker
+
+`sub-<participant_label>[_ses-<label>][_acq-<label>]_task-<task_label>_eyetrack.<manufacturer_specific_extension>`
+
 
 ## Contributing
 
@@ -12,17 +30,72 @@ Feel free to open issues to report a bug and ask for improvements.
 -   We use camelCase.
 -   We keep the McCabe complexity as reported by the [check_my_code function](https://github.com/Remi-Gau/matlab_checkcode) below 15.
 
+## How to install
 
-## Functions descriptions
+### Use the matlab package manager
+
+This repository can be added as a dependencies by listing it in a [mpm-requirements.txt file](.mpm-requirements.txt)
+as follows:
+
+```
+CPP_BIDS -u https://github.com/cpp-lln-lab/CPP_BIDS.git
+```
+
+You can then use the [matlab package manager](https://github.com/mobeets/mpm), to simply download the appropriate version of those dependencies and add them to your path by running a `getDependencies` function like the one below where you just need to replace `YOUR_EXPERIMENT_NAME` by the name of your experiment.
 
 
+```matlab
+function getDependencies(action)
+% Will install on your computer the matlab dependencies specified in the mpm-requirements.txt
+%  and add them to the matlab path. The path is never saved so you need to run getDependencies() when
+%  you start matlab.
+%
+% getDependencies('update') will force the update and overwrite previous version of the dependencies.
+%
+% getDependencies() If you only already have the appropriate version but just want to add them to the matlab path.
+
+experimentName = YOUR_EXPERIMENT_NAME;
+
+if nargin<1
+    action = '';
+end
+
+switch action
+    case 'update'
+        % install dependencies
+        mpm install -i mpm-requirements.txt -f -c YOUR_EXPERIMENT_NAME
+end
+
+% adds them to the path
+mpm_folder = fileparts(which('mpm'));
+addpath(genpath(fullfile(mpm_folder, 'mpm-packages', 'mpm-collections', experimentName)));
+
+end
+```
+
+## Functions descriptions
+
 ### userInputs
 
+Get subject, run and session number and make sure they are positive integer values.
+
 
 ### createFilename
 
+Create the BIDS compliant directories  and filenames (but not the files) for the behavioral output for this subject /
+session / run.
+
+Will also create the right filename for the eye-tracking data file.
+
+For the moment the date of acquisition is appended to the filename
+-   can work for behavioral experiment if cfg.device is set to 'PC'
+-   can work for fMRI experiment if cfg.device is set to 'scanner'
+-   can work for simple eyetracking data if cfg.eyeTracker is set to 1
 
 ### saveEventsFile
 
+Function to save output files for events that will be BIDS compliant.
+
 
 ### checkCFG
+Check that we have all the fields that we need in the experiment parameters.

createFilename.m

@@ -1,9 +1,9 @@
 function expParameters = createFilename(expParameters, cfg)
 % create the BIDS compliant directories and filenames for the behavioral output for this subject /
-% session / run.
+% session / run using the information from cfg and expParameters.
 % Will also create the right filename for the eyetracking data file.
 %
-% For the moment the date of acquisition is appreneded to the filename
+% For the moment the date of acquisition is appended to the filename
 %
 % can work for behavioral experiment if cfg.device is set to 'PC'
 % can work for fMRI experiment if cfg.device is set to 'scanner'
@@ -20,6 +20,9 @@
 %
 % EYETRACKER
 % sub-<participant_label>[_ses-<label>][_acq-<label>]_task-<task_label>_eyetrack.<manufacturer_specific_extension>
+%
+%
+% See test_createFilename in the test folder for more details on how to use it.
 
 zeroPadding = 3;
 pattern = ['%0' num2str(zeroPadding) '.0f'];
@@ -97,50 +100,50 @@
 %% create filenames
 
 switch modality
-    
+
     case 'beh'
-        
+
         expParameters.fileName.events = ...
             [expParameters.fileName.base, runSuffix, '_events_date-' expParameters.date '.tsv'];
-        
+
     case 'func'
-        
+
         expParameters.fileName.events = ...
             [expParameters.fileName.base, ...
             expParameters.acqSuffix, expParameters.ceSuffix, ...
             expParameters.dirSuffix, expParameters.recSuffix, ...
             runSuffix, expParameters.echoSuffix, ...
             '_events_date-' expParameters.date '.tsv'];
-        
+
 end
 
 if cfg.eyeTracker
-    
+
     expParameters.fileName.eyetracker = ...
         [expParameters.fileName.base, expParameters.acqSuffix, ...
         runSuffix, '_eyetrack_date-' expParameters.date '.edf'];
-    
+
 end
 
 if expParameters.verbose
-    
+
     fprintf(1,'\nData will be saved in this directory:\n\t%s\n', ...
         fullfile(expParameters.outputDir, modality));
-    
+
     fprintf(1,'\nData will be saved in this file:\n\t%s\n', ...
         expParameters.fileName.events);
-    
+
     if cfg.eyeTracker
-        
+
         fprintf(1,'\nEyetracking data will be saved in this directory:\n\t%s\n', ...
             fullfile(expParameters.outputDir, 'eyetracker'));
 
         fprintf(1,'\nEyetracking data will be saved in this file:\n\t%s\n', ...
             expParameters.fileName.eyetracker);
-        
+
     end
-    
+
 end
 
 
-end
+end

saveEventsFile.m

@@ -1,85 +1,108 @@
-function [ logFile ] = saveEventsFile(input, expParameters, logFile, varargin)
+function [ logFile ] = saveEventsFile(action, expParameters, logFile, varargin)
+% Function to save output files for events that will be BIDS compliant.
+%
+% INPUTS
+%
+% action:
+%  - 'open': will create the file ID and return it in logFile.eventLogFile using the information in
+% the expParameters 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', 'trial_type', 'duration' required bt BIDS and other
+% coluns can be specified in varargin.
+% example : logFile = saveEventsFile('open', expParameters, [], 'direction', 'speed', 'target');
+%
+%  - 'save': will save the data contained in logfile by using the file ID logFile.eventLogFile;
+% logfile must then contain:
+%     - logFile.onset
+%     - logFile.trial_type
+%     - logFile.duration
+% The name of any extra column whose content must be saved should be listed in varargin.
+%
+%  - 'close': closes the file with file ID logFile.eventLogFile. If expParameters.verbose is set to true
+% then this will tell you where the file is located.
+%
+% See test_saveEventsFile in the test folder for more details on how to use it.
 
 if nargin<3 || isempty(logFile)
     logFile = struct();
 end
 
-switch input
-    
+switch action
+
     case 'open'
-        
+
         logFile = struct();
-        
+
         % Initialize txt logfiles and empty fields for the standard BIDS
         %  event file
         logFile.eventLogFile = fopen(...
             fullfile(expParameters.outputDir, expParameters.modality, expParameters.fileName.events), ...
             'w');
-        
+
         % print the basic BIDS columns
         fprintf(logFile.eventLogFile, '%s\t%s\t%s\t', 'onset', 'trial_type', 'duration');
-        
+
         % print any extra column specified by the user
         %  also prepare an empty field in the structure to collect data
         %  for those
         for iExtraColumn = 1:numel(varargin)
             fprintf(logFile.eventLogFile,'%s\t', lower(varargin{iExtraColumn}));
         end
-        
+
         % next line so we start printing at the right place
         fprintf(logFile.eventLogFile, '\n');
-        
-        
+
+
     case 'save'
-        
+
         % appends to the logfile all the data stored in the structure
         % first with the standard BIDS data and then any extra things
         for iEvent = 1:size(logFile,1)
-            
+
             fprintf(logFile(1).eventLogFile,'%f\t%s\t%f\t',...
                 logFile(iEvent).onset, ...
                 logFile(iEvent).trial_type, ...
                 logFile(iEvent).duration);
-            
+
             for iExtraColumn = 1:numel(varargin)
-                
+
                 % if the field we are looking for does not exist or is empty in the
-                % input logFile structure we will write a NaN otherwise we
+                % action logFile structure we will write a NaN otherwise we
                 % write its content
-                
+
                 if ~isfield(logFile, varargin{iExtraColumn})
                     data = [];
                 else
                     data = getfield(logFile(iEvent), varargin{iExtraColumn});
                 end
-                
+
                 if isempty(data)
                     data = NaN;
                 end
-                
+
                 if ischar(data)
                     fprintf(logFile(1).eventLogFile, '%s\t', data);
                 else
                     fprintf(logFile(1).eventLogFile, '%f\t', data);
                 end
-                
+
             end
-            
+
             fprintf(logFile(1).eventLogFile, '\n');
         end
-        
+
     case 'close'
-        
+
         % close txt log file
         fclose(logFile(1).eventLogFile);
-        
+
         if expParameters.verbose
             fprintf(1,'\nData were saved in this file:\n\n%s\n\n', ...
                 fullfile(...
                 expParameters.outputDir, ...
                 expParameters.modality, ...
                 expParameters.fileName.events));
-            
+
         end
-        
-end
+
+end

userInputs.m

@@ -1,5 +1,5 @@
 function [expParameters] = userInputs(cfg, expParameters)
-% Get subject, run and session number and mae sure they are
+% Get subject, run and session number and make sure they are
 % positive integer values
 
 if nargin<1
@@ -12,25 +12,25 @@
 
 
 if cfg.debug
-    
+
     subjectGrp = 'ctrl';
     subjectNb = 666;
     runNb = 666;
     sessionNb = 666;
-    
+
 else
-    
+
     subjectGrp = lower(input('Enter subject group (leave empty if none): ', 's'));
-    
+
     subjectNb = str2double(input('Enter subject number (1-999): ', 's') );
     subjectNb = checkInput(subjectNb);
-    
+
     sessionNb = str2double(input('Enter the session (i.e day - 1-999)) number: ', 's'));
     sessionNb = checkInput(sessionNb);
-    
+
     runNb = str2double(input('Enter the run number (1-999): ', 's'));
     runNb = checkInput(runNb);
-    
+
 end
 
 
@@ -51,4 +51,4 @@
 end
 
 
-end
+end