update doc

Author: Remi-Gau

docs/functions-description.md

@@ -14,19 +14,22 @@
 
 <!-- lint enable -->
 
+## Use the CPP templates for PsychToolBox experiments
+
+The easiest way to use this repository is to create a new repository by using
+the
+[template PTB experiment repository](https://github.com/cpp-lln-lab/template_PTB_experiment):
+this creates a new repository on your github account with all the basic folders,
+files and submodules (including CPP_BIDS) already set up. You only have to then
+clone the repository and you are good to go.
+
 ## Download with git
 
 ```bash
 cd fullpath_to_directory_where_to_install
 
-# use git to download the code
-git clone https://github.com/cpp-lln-lab/CPP_BIDS.git
-
-# move into the folder you have just created
-cd CPP_BIDS
-
-# add the src folder to the matlab path and save the path
-matlab -nojvm -nosplash -r "addpath(fullfile(pwd, 'src')); savepath ();"
+# use git to download the code and the submodules
+git clone --recurse-submodules https://github.com/cpp-lln-lab/CPP_BIDS.git
 ```
 
 Then get the latest commit:
@@ -53,12 +56,6 @@ cd fullpath_to_directory_where_to_install
 
 # use git to download the code
 git submodule add https://github.com/cpp-lln-lab/CPP_BIDS.git
-
-# move into the folder you have just created
-cd CPP_BIDS
-
-# add the src folder to the matlab path and save the path
-matlab -nojvm -nosplash -r "addpath(fullfile(pwd, 'src'))"
 ```
 
 To get the latest commit you then need to update the submodule with the
@@ -83,7 +80,7 @@ git clone https://github.com/user_name/myExperiment.git
 # go into the directory
 cd myExperiment
 
-# initialize and get the content of the first level of submodules  (e.g. CPP_PTB and CPP_BIDS)
+# initialize and get the content of the first level of submodules
 git submodule init
 git submodule update
 
@@ -94,6 +91,8 @@ git submodule foreach --recursive 'git submodule update'
 
 ## Direct download
 
+NOT RECOMMENDED.
+
 Download the code. Unzip. And add to the matlab path.
 
 Pick a specific version from

docs/installation.md

@@ -12,6 +12,21 @@ List of functions in the ``src`` folder.
 .. autofunction:: createDatasetDescription
 .. autofunction:: createFilename
 .. autofunction:: createJson
+
+``createJson`` 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).
+
 .. autofunction:: readAndFilterLogfile
 .. autofunction:: saveEventsFile
 .. autofunction:: userInputs

docs/source/function_description.rst

@@ -8,10 +8,12 @@ List of functions in the ``utils`` folder.
 .. automodule:: src.utils
 
 .. autofunction:: checkCppBidsDependencies
+.. autofunction:: checkInput
 .. autofunction:: createValidName
 .. autofunction:: getFullFilename
 .. autofunction:: initializeExtraColumns
 .. autofunction:: isPositiveInteger
+.. autofunction:: nanPadding
 .. autofunction:: printCreditsCppBids
 .. autofunction:: removeAllDateSuffix
 .. autofunction:: removeDateSuffix

docs/source/utilities.rst

@@ -3,9 +3,12 @@
 function cfg = createFilename(cfg)
     %
     % It creates the BIDS compliant directories and fileNames for the behavioral output
-    % for this subject / 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 appended to the fileName.
+    % 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::
     %
@@ -20,7 +23,9 @@
     %                 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

src/createFilename.m

@@ -4,7 +4,7 @@ function createJson(varargin)
     %
     % Creates the side car JSON file for a run.
     %
-    % For JSON sidecars for bold files,  this will only contain the minimum BIDS
+    % 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.
     %

src/createJson.m

@@ -9,7 +9,7 @@
     %   [logFile] = saveEventsFile(action, cfg, logFile)
     %
     % :param action: Defines the operation to do. The different possibilities are
-    %                ``'init'``, ``'open'``, ``'open_stim'``, ``'save'`` or ``'close'``.
+    %                ``'init'``, ``'init_stim'``, ``'open'``, ``'save'`` or ``'close'``.
     %                For more information on each case see below.
     % :type action: string
     % :param cfg: Configuration variable. See ``checkCFG()``.
@@ -31,15 +31,15 @@
     %
     % Actions:
     %
-    %   .. todo:
-    %      wait for updates on the API of this function to finish updating
-    %
     %   Example::
     %
-    %     logFile = saveEventsFile('init', [cfg], logFile)
-    %     logFile = saveEventsFile('open', [cfg], logFile)
-    %     logFile = saveEventsFile('open_stim', [cfg], logFile)
-    %     logFile = saveEventsFile('save', [cfg], logFile)
+    %     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.
@@ -52,15 +52,19 @@
     %       logFile = saveEventsFile('open', cfg, logFile);
     %
     %   - ``'save'`` will save the data contained in logfile by using the file ID
-    %     ``logFile.fileID``; logfile must then contain:
+    %     ``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.trial_type
     %     - logFile.duration
+    %       
+    %     Otherwise it will be skipped.
     %
     %     Example::
     %
-    %       logFile = saveEventsFile('open', cfg, logFile);
+    %       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