From 25dd99fb8c4bc4662cbe607df80b06a12ebd7df9 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 16 Nov 2020 10:10:06 +0100
Subject: [PATCH 1/8] reformat help section from checkCFG

---
 src/checkCFG.m | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/src/checkCFG.m b/src/checkCFG.m
index 4c3a3318..2f2eb114 100644
--- a/src/checkCFG.m
+++ b/src/checkCFG.m
@@ -2,28 +2,24 @@
 
 function cfg = checkCFG(cfg)
     %
-    % Short description of what the function does goes here.
+    % Check the fields of the configuration structure ``cfg``. If a required field is 
+    % missing the default value will be assigned to that field. If this field already
+    % exists then the existing value will not be replaced. 
     %
     % USAGE::
     %
-    %   [argout1, argout2] = templateFunction(argin1, [argin2 == default,] [argin3])
+    %   cfg = checkCFG([cfg])
     %
-    % :param argin1: (dimension) obligatory argument. Lorem ipsum dolor sit amet,
-    %                consectetur adipiscing elit. Ut congue nec est ac lacinia.
-    % :type argin1: type
-    % :param argin2: optional argument and its default value. And some of the
-    %               options can be shown in litteral like ``this`` or ``that``.
-    % :type argin2: string
-    % :param argin3: (dimension) optional argument
-    % :type argin3: integer
+    % :param cfg: Lorem ipsum dolor sit amet,
+    %             consectetur adipiscing elit. Ut congue nec est ac lacinia.
+    % :type cfg: type
     %
-    % :returns: - :argout1: (type) (dimension)
-    %           - :argout2: (type) (dimension)
+    % :returns: :cfg: (structure)
+    %           
+    % This function reuses a lot of code and comment from the BIDS starter kit:
+    % https://github.com/bids-standard/bids-starter-kit/tree/master/matlabCode
     %
-    % cfg = checkCFG(cfg)
-    %
-    % check that we have all the fields that we need in the experiment parameters
-    % reuses a lot of code from the BIDS starter kit
+
 
     if nargin < 1 || isempty(cfg)
         cfg = struct();

From 0186b98def1fa23c20906ad7746abf89d66fbf23 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 16 Nov 2020 13:17:34 +0100
Subject: [PATCH 2/8] reorder checkCFG sub-functions by order of appearance in
 main function

---
 src/checkCFG.m | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/src/checkCFG.m b/src/checkCFG.m
index 2f2eb114..f20cc488 100644
--- a/src/checkCFG.m
+++ b/src/checkCFG.m
@@ -54,12 +54,12 @@
 
     %% BIDS
 
-    fieldsToSet = behJsonDefaults(fieldsToSet);
     fieldsToSet = datasetDescriptionDefaults(fieldsToSet);
+    fieldsToSet = behJsonDefaults(fieldsToSet);
+    fieldsToSet = mriJsonDefaults(fieldsToSet);
     fieldsToSet = eegJsonDefaults(fieldsToSet);
     fieldsToSet = ieegJsonDefaults(fieldsToSet);
     fieldsToSet = megJsonDefaults(fieldsToSet);
-    fieldsToSet = mriJsonDefaults(fieldsToSet);
 
     fieldsToSet = transferInfoToBids(fieldsToSet, cfg);
 
@@ -126,6 +126,17 @@
 
 end
 
+function fieldsToSet = behJsonDefaults(fieldsToSet)
+    % for json for BEH data
+
+    fieldsToSet.bids.beh.TaskName = [];
+
+    fieldsToSet.bids.beh.Instructions = [];
+
+    fieldsToSet.bids.beh = orderfields(fieldsToSet.bids.beh);
+
+end
+
 function fieldsToSet = mriJsonDefaults(fieldsToSet)
     % for json for funcfional MRI data
 
@@ -251,17 +262,6 @@
 
 end
 
-function fieldsToSet = behJsonDefaults(fieldsToSet)
-    % for json for BEH data
-
-    fieldsToSet.bids.beh.TaskName = [];
-
-    fieldsToSet.bids.beh.Instructions = [];
-
-    fieldsToSet.bids.ieeg = orderfields(fieldsToSet.bids.beh);
-
-end
-
 function fieldsToSet = eyetrackerDefaults(fieldsToSet)
 
     fieldsToSet.eyeTracker.do = false;

From 5892a8b45ecbcb330b41a3c569e831a4215e9957 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 16 Nov 2020 16:59:50 +0100
Subject: [PATCH 3/8] remove repetition time from the list of suffixes

---
 src/checkCFG.m        | 1 -
 tests/test_checkCFG.m | 1 -
 2 files changed, 2 deletions(-)

diff --git a/src/checkCFG.m b/src/checkCFG.m
index f20cc488..28c29451 100644
--- a/src/checkCFG.m
+++ b/src/checkCFG.m
@@ -76,7 +76,6 @@
     fieldsToSet.suffix.reconstruction = [];
     fieldsToSet.suffix.echo = [];
     fieldsToSet.suffix.acquisition = [];
-    fieldsToSet.suffix.repetitionTime = [];
     fieldsToSet.suffix.recording = [];
 
     fieldsToSet.suffix = orderfields(fieldsToSet.suffix);
diff --git a/tests/test_checkCFG.m b/tests/test_checkCFG.m
index dc2edc90..25809d22 100644
--- a/tests/test_checkCFG.m
+++ b/tests/test_checkCFG.m
@@ -103,7 +103,6 @@ function test_checkCfgBasic()
     expectedCfgStructure.suffix.reconstruction = [];
     expectedCfgStructure.suffix.echo = [];
     expectedCfgStructure.suffix.acquisition = [];
-    expectedCfgStructure.suffix.repetitionTime = [];
     expectedCfgStructure.suffix.recording = [];
 
     expectedCfgStructure.bids.beh.TaskName = '';

From 8a788b7a47b0e6805fd86303b23115d3ca59d17e Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 16 Nov 2020 17:15:21 +0100
Subject: [PATCH 4/8] update help section of checkCFG

---
 src/checkCFG.m | 165 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 159 insertions(+), 6 deletions(-)

diff --git a/src/checkCFG.m b/src/checkCFG.m
index 28c29451..6eb55c63 100644
--- a/src/checkCFG.m
+++ b/src/checkCFG.m
@@ -10,16 +10,171 @@
     %
     %   cfg = checkCFG([cfg])
     %
-    % :param cfg: Lorem ipsum dolor sit amet,
-    %             consectetur adipiscing elit. Ut congue nec est ac lacinia.
-    % :type cfg: type
+    % :param cfg: The configuration variable to check.
+    % :type cfg: structure
     %
     % :returns: :cfg: (structure)
     %           
     % This function reuses a lot of code and comment from the BIDS starter kit:
+    %
     % https://github.com/bids-standard/bids-starter-kit/tree/master/matlabCode
     %
-
+    % **Fields descriptions**:
+    %  The following section describes the main fields set by ``checkCFG()`` with 
+    %  their associated default value.
+    %
+    %   - ``cfg.testingDevice = 'pc'``
+    %     set the way the experiment is run and the different options match the imaging
+    %     modality:
+    %
+    %     - ``pc`` is for behavioral test
+    %     - ``mri`` is for fMRI
+    %     - ``eeg`` is for EEG...
+    %
+    %   - ``cfg.verbose = 0`` 
+    %     sets how talkative the code will be. Possible values range from ``0`` to ``2``. 
+    %
+    %   - ``cfg.useGUI = false``
+    %     sets whether a graphic interface should be used for the ``userInputs()``
+    %     to query about group name, as well as for session, subject and run number.
+    %
+    %   - ``cfg.dir.output``
+    %     sets where the data will be saved.
+    %
+    %   Filename options:
+    %     Sets options that will help in creating the filenames.
+    %
+    %     - ``cfg.fileName.task = ''``
+    %       sets the name to be given to the task
+    %     - ``cfg.fileName.zeroPadding = 3`` 
+    %       sets tha amount of 0 padding the subject, session and run number.
+    %     - ``cfg.fileName.dateFormat = 'yyyymmddHHMM'``
+    %       sets the format of the date and time stamp that will be appended to all files.
+    %    
+    %     The following fields can be used to specify certain of the labels that are used
+    %     to specify certain of the acquisition conditions of certain experemental runs
+    %     in a BIDS data set. These are mostly for MRI and, if set, will be ignored 
+    %     for most other modalities. See ``tests/test_createFilename()`` for details on how
+    %     to use these.
+    %
+    %     - ``cfg.suffix.contrastEnhancement = []``
+    %     - ``cfg.suffix.phaseEncodingDirection = []``
+    %     - ``cfg.suffix.reconstruction = []``
+    %     - ``cfg.suffix.echo = []``
+    %     - ``cfg.suffix.acquisition = []``
+    %     - ``cfg.suffix.recording = []``
+    %  
+    %   Group and session options:  
+    %     All the fields of ``cfg.subject`` can be set using the ``userInputs()`` function
+    %     but can also be set "manually" directly into the ``cfg`` structure.
+    %
+    %     - ``cfg.subject.subjectGrp = ''`` 
+    %       is set to empty in case no group was provided.
+    %     - ``cfg.subject.sessionNb = 1`` 
+    %       always sets to 1 in case no session was provided.
+    %     - ``cfg.subject.askGrpSess = [true true]`` 
+    %       means that ``userInputs()`` will always ask for group and session by default.
+    %
+    %   Eyetracker options:
+    %     Those options are mostly work in progress at the moment but should allow to
+    %     track the some of the metadata regarding eyetracking data acquisition.
+    %
+    %     - ``cfg.eyeTracker.do = false``
+    %     - ``cfg.eyeTracker.SamplingFrequency = []``
+    %     - ``cfg.eyeTracker.PupilPositionType = ''``
+    %     - ``cfg.eyeTracker.RawSamples =  []``
+    %     - ``cfg.eyeTracker.Manufacturer = ''``
+    %     - ``cfg.eyeTracker.ManufacturersModelName = ''``
+    %     - ``cfg.eyeTracker.SoftwareVersions = ''``
+    %     - ``cfg.eyeTracker.CalibrationType = 'HV5'``
+    %     - ``cfg.eyeTracker.CalibrationPosition = ''``
+    %     - ``cfg.eyeTracker.CalibrationDistance = ''``
+    %     - ``cfg.eyeTracker.MaximalCalibrationError = []``
+    %     - ``cfg.eyeTracker.AverageCalibrationError = []``
+    %     - ``cfg.eyeTracker.RawDataFilters = {}``
+    %
+    % ``cfg.bids``:
+    %  ``checkCFG()`` will also initialize ``cfg.bids`` that
+    %  contains any information related to a BIDS data set and that will end up in
+    %  in one of the JSON "sidecar" files containing the metadata of your
+    %  experiment. 
+    %
+    %  If the content of some fields of ``cfg`` has been set before running ``checkCFG()``,
+    %  that content might be copied into the relevant field in ``cfg.bids``. For example,
+    %  if you have set the field ``cfg.mri.repetitionTime``, then when you run ``checkCFG()``,
+    %  its content will also be copied into ``cfg.bids.mri.RepetitionTime``.
+    %
+    %  ``cfg.bids`` is further sub-divided into several fields for the different 
+    %  "imaging modalities".
+    %
+    %  - ``cfg.bids.datasetDescription`` will be there for all type of experiments
+    %  - ``cfg.bids.beh`` is for purely behavioral experiment with no associated imaging
+    %  - ``cfg.bids.mri`` is for fMRI experiments
+    %  - ``cfg.bids.eeg`` is for EEG experiments
+    %  - ``cfg.bids.meg`` is for MEG experiments
+    %  - ``cfg.bids.ieeg`` is for iEEG experiments
+    %
+    %  The content of each of those subfields matches the different "keys" one can find 
+    %  in the JSON file for each modality. The content of those different keys is detailed 
+    %  in the code of ``checkCFG()``, 
+    %  but a more extensive and updated descriptions will be found in the 
+    %  BIDS specifications themselves.  
+    %
+    %  https://bids-specification.readthedocs.io/en/stable/
+    %  
+    %  For the content of the ``datasetDescription.json`` files::
+    %
+    %    cfg.bids.datasetDescription.Name = '';
+    %    cfg.bids.datasetDescription.BIDSVersion =  '';
+    %    cfg.bids.datasetDescription.License = '';
+    %    cfg.bids.datasetDescription.Authors = {''};
+    %    cfg.bids.datasetDescription.Acknowledgements = '';
+    %    cfg.bids.datasetDescription.HowToAcknowledge = '';
+    %    cfg.bids.datasetDescription.Funding = {''};
+    %    cfg.bids.datasetDescription.ReferencesAndLinks = {''};
+    %    cfg.bids.datasetDescription.DatasetDOI = '';
+    %
+    %  For the content of the JSON files for behavioral data::
+    %
+    %    cfg.bids.beh.TaskName = [];
+    %    cfg.bids.beh.Instructions = [];
+    %
+    %  For the content of the JSON files for fMRI data::
+    %
+    %    cfg.bids.mri.TaskName = '';
+    %    cfg.bids.mri.Instructions = '';
+    %    cfg.bids.mri.RepetitionTime = [];
+    %    cfg.bids.mri.SliceTiming = '';
+    %    cfg.bids.mri.TaskDescription = '';
+    %  
+    %  For the content of the JSON files for EEG::
+    %
+    %    cfg.bids.eeg.TaskName = '';
+    %    cfg.bids.eeg.Instructions = '';
+    %    cfg.bids.eeg.EEGReference = '';
+    %    cfg.bids.eeg.SamplingFrequency = [];
+    %    cfg.bids.eeg.PowerLineFrequency = 50;
+    %    cfg.bids.eeg.SoftwareFilters = 'n/a';
+    %   
+    %  For the content of the JSON files for iEEG::
+    %
+    %    cfg.bids.ieeg.TaskName = '';
+    %    cfg.bids.ieeg.Instructions = '';
+    %    cfg.bids.ieeg.iEEGReference = '';
+    %    cfg.bids.ieeg.SamplingFrequency = [];
+    %    cfg.bids.ieeg.PowerLineFrequency = 50;
+    %    cfg.bids.ieeg.SoftwareFilters = 'n/a';
+    %
+    %  For the content of the JSON files for MEG::
+    %
+    %    cfg.bids.meg.TaskName = '';
+    %    cfg.bids.meg.Instructions = '';
+    %    cfg.bids.meg.SamplingFrequency = [];
+    %    cfg.bids.meg.PowerLineFrequency = [];
+    %    cfg.bids.meg.DewarPosition = [];
+    %    cfg.bids.meg.SoftwareFilters = [];
+    %    cfg.bids.meg.DigitizedLandmarks = [];
+    %    cfg.bids.meg.DigitizedHeadPoints = [];
 
     if nargin < 1 || isempty(cfg)
         cfg = struct();
@@ -27,8 +182,6 @@
 
     checkCppBidsDependencies(cfg);
 
-    %% list the defaults to set
-
     fieldsToSet.verbose = 0;
 
     fieldsToSet.useGUI = false;

From 36e05895c0b83903c5b3730dc7203956a3c981a9 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 16 Nov 2020 17:18:32 +0100
Subject: [PATCH 5/8] mh fix

---
 src/checkCFG.m | 48 ++++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/src/checkCFG.m b/src/checkCFG.m
index 6eb55c63..762681ca 100644
--- a/src/checkCFG.m
+++ b/src/checkCFG.m
@@ -2,9 +2,9 @@
 
 function cfg = checkCFG(cfg)
     %
-    % Check the fields of the configuration structure ``cfg``. If a required field is 
+    % Check the fields of the configuration structure ``cfg``. If a required field is
     % missing the default value will be assigned to that field. If this field already
-    % exists then the existing value will not be replaced. 
+    % exists then the existing value will not be replaced.
     %
     % USAGE::
     %
@@ -14,13 +14,13 @@
     % :type cfg: structure
     %
     % :returns: :cfg: (structure)
-    %           
+    %
     % This function reuses a lot of code and comment from the BIDS starter kit:
     %
     % https://github.com/bids-standard/bids-starter-kit/tree/master/matlabCode
     %
     % **Fields descriptions**:
-    %  The following section describes the main fields set by ``checkCFG()`` with 
+    %  The following section describes the main fields set by ``checkCFG()`` with
     %  their associated default value.
     %
     %   - ``cfg.testingDevice = 'pc'``
@@ -31,8 +31,8 @@
     %     - ``mri`` is for fMRI
     %     - ``eeg`` is for EEG...
     %
-    %   - ``cfg.verbose = 0`` 
-    %     sets how talkative the code will be. Possible values range from ``0`` to ``2``. 
+    %   - ``cfg.verbose = 0``
+    %     sets how talkative the code will be. Possible values range from ``0`` to ``2``.
     %
     %   - ``cfg.useGUI = false``
     %     sets whether a graphic interface should be used for the ``userInputs()``
@@ -46,14 +46,14 @@
     %
     %     - ``cfg.fileName.task = ''``
     %       sets the name to be given to the task
-    %     - ``cfg.fileName.zeroPadding = 3`` 
+    %     - ``cfg.fileName.zeroPadding = 3``
     %       sets tha amount of 0 padding the subject, session and run number.
     %     - ``cfg.fileName.dateFormat = 'yyyymmddHHMM'``
     %       sets the format of the date and time stamp that will be appended to all files.
-    %    
+    %
     %     The following fields can be used to specify certain of the labels that are used
     %     to specify certain of the acquisition conditions of certain experemental runs
-    %     in a BIDS data set. These are mostly for MRI and, if set, will be ignored 
+    %     in a BIDS data set. These are mostly for MRI and, if set, will be ignored
     %     for most other modalities. See ``tests/test_createFilename()`` for details on how
     %     to use these.
     %
@@ -63,16 +63,16 @@
     %     - ``cfg.suffix.echo = []``
     %     - ``cfg.suffix.acquisition = []``
     %     - ``cfg.suffix.recording = []``
-    %  
-    %   Group and session options:  
+    %
+    %   Group and session options:
     %     All the fields of ``cfg.subject`` can be set using the ``userInputs()`` function
     %     but can also be set "manually" directly into the ``cfg`` structure.
     %
-    %     - ``cfg.subject.subjectGrp = ''`` 
+    %     - ``cfg.subject.subjectGrp = ''``
     %       is set to empty in case no group was provided.
-    %     - ``cfg.subject.sessionNb = 1`` 
+    %     - ``cfg.subject.sessionNb = 1``
     %       always sets to 1 in case no session was provided.
-    %     - ``cfg.subject.askGrpSess = [true true]`` 
+    %     - ``cfg.subject.askGrpSess = [true true]``
     %       means that ``userInputs()`` will always ask for group and session by default.
     %
     %   Eyetracker options:
@@ -97,14 +97,14 @@
     %  ``checkCFG()`` will also initialize ``cfg.bids`` that
     %  contains any information related to a BIDS data set and that will end up in
     %  in one of the JSON "sidecar" files containing the metadata of your
-    %  experiment. 
+    %  experiment.
     %
     %  If the content of some fields of ``cfg`` has been set before running ``checkCFG()``,
     %  that content might be copied into the relevant field in ``cfg.bids``. For example,
     %  if you have set the field ``cfg.mri.repetitionTime``, then when you run ``checkCFG()``,
     %  its content will also be copied into ``cfg.bids.mri.RepetitionTime``.
     %
-    %  ``cfg.bids`` is further sub-divided into several fields for the different 
+    %  ``cfg.bids`` is further sub-divided into several fields for the different
     %  "imaging modalities".
     %
     %  - ``cfg.bids.datasetDescription`` will be there for all type of experiments
@@ -114,14 +114,14 @@
     %  - ``cfg.bids.meg`` is for MEG experiments
     %  - ``cfg.bids.ieeg`` is for iEEG experiments
     %
-    %  The content of each of those subfields matches the different "keys" one can find 
-    %  in the JSON file for each modality. The content of those different keys is detailed 
-    %  in the code of ``checkCFG()``, 
-    %  but a more extensive and updated descriptions will be found in the 
-    %  BIDS specifications themselves.  
+    %  The content of each of those subfields matches the different "keys" one can find
+    %  in the JSON file for each modality. The content of those different keys is detailed
+    %  in the code of ``checkCFG()``,
+    %  but a more extensive and updated descriptions will be found in the
+    %  BIDS specifications themselves.
     %
     %  https://bids-specification.readthedocs.io/en/stable/
-    %  
+    %
     %  For the content of the ``datasetDescription.json`` files::
     %
     %    cfg.bids.datasetDescription.Name = '';
@@ -146,7 +146,7 @@
     %    cfg.bids.mri.RepetitionTime = [];
     %    cfg.bids.mri.SliceTiming = '';
     %    cfg.bids.mri.TaskDescription = '';
-    %  
+    %
     %  For the content of the JSON files for EEG::
     %
     %    cfg.bids.eeg.TaskName = '';
@@ -155,7 +155,7 @@
     %    cfg.bids.eeg.SamplingFrequency = [];
     %    cfg.bids.eeg.PowerLineFrequency = 50;
     %    cfg.bids.eeg.SoftwareFilters = 'n/a';
-    %   
+    %
     %  For the content of the JSON files for iEEG::
     %
     %    cfg.bids.ieeg.TaskName = '';

From 4488a846f39ef05369869eb7278c309fb749f586 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 16 Nov 2020 17:50:48 +0100
Subject: [PATCH 6/8] update help section transferInfoToBids

---
 src/utils/transferInfoToBids.m | 28 +++++++++++++---------------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/src/utils/transferInfoToBids.m b/src/utils/transferInfoToBids.m
index a57a68f2..cdb464d5 100644
--- a/src/utils/transferInfoToBids.m
+++ b/src/utils/transferInfoToBids.m
@@ -2,28 +2,26 @@
 
 function fieldsToSet = transferInfoToBids(fieldsToSet, cfg)
     %
-    % Short description of what the function does goes here.
+    % Transfers any info that might have been provided
+    % by the user in ``cfg`` to the relevant field of ``fieldsToSet``
+    % for its reuse later for BIDS filenames or JSON.
     %
     % USAGE::
     %
-    %   [argout1, argout2] = templateFunction(argin1, [argin2 == default,] [argin3])
+    %   fieldsToSet = transferInfoToBids(fieldsToSet, cfg)
     %
-    % :param argin1: (dimension) obligatory argument. Lorem ipsum dolor sit amet,
-    %                consectetur adipiscing elit. Ut congue nec est ac lacinia.
-    % :type argin1: type
-    % :param argin2: optional argument and its default value. And some of the
-    %               options can be shown in litteral like ``this`` or ``that``.
-    % :type argin2: string
-    % :param argin3: (dimension) optional argument
-    % :type argin3: integer
+    % :param fieldsToSet: List of the fields to set. See ``checkCFG()``.
+    % :type fieldsToSet: structure
+    % :param cfg: The configuration variable where the user has predefined some fields.
+    %             See ``checkCFG()``.
+    % :type cfg: structure
     %
-    % :returns: - :argout1: (type) (dimension)
-    %           - :argout2: (type) (dimension)
+    % :returns: :fieldsToSet: Updated list of the fields to set.
     %
-    % fieldsToSet = transferInfoToBids(fieldsToSet, cfg)
+    % This can be used for example to make sure that the repetition time set
+    % manually in ``cfg.mri.repetitionTime`` or in ``cfg.task.name``
+    % will be passed to the correct field in right fields of ``cfg.bids``.
     %
-    % transfer any info that might have been provided by the user to the
-    % relevant field for its reuse for BIDS filenames or JSON later
 
     if isfield(cfg, 'task') && isfield(cfg.task, 'name')
         [taskName, taskNameValid] = createValidName(cfg.task.name);

From 19b208fa1098d2a955fd0ee5fb676d1d2089094f Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 16 Nov 2020 19:44:08 +0100
Subject: [PATCH 7/8] basic set up of the doc

---
 README.md                            | 29 +-------
 docs/README.md                       |  2 +-
 docs/functions-description.md        | 98 ----------------------------
 docs/source/contributing.rst         |  7 +-
 docs/source/function_description.rst |  1 -
 docs/source/gui.rst                  | 18 +++++
 docs/source/index.rst                | 39 +++++++++--
 docs/source/set_up.rst               | 53 +++++++++++++++
 docs/source/utilities.rst            |  2 +-
 9 files changed, 112 insertions(+), 137 deletions(-)
 create mode 100644 docs/source/gui.rst
 create mode 100644 docs/source/set_up.rst

diff --git a/README.md b/README.md
index 971efaaa..6f23bdc8 100644
--- a/README.md
+++ b/README.md
@@ -48,36 +48,11 @@ A set of function for matlab and octave to create
 structure and filenames for the output of behavioral, EEG, fMRI, eyetracking
 studies.
 
-## Output format
-
-### Modality agnostic aspect
-
-Subjects, session and run number labels will be numbers with zero padding up to
-3 values (e.g subject 1 will become `sub-001`).
-
-A session folder will ALWAYS be created even if not requested (default will be
-`ses-001`).
-
-Task labels will be printed in camelCase in the filenames.
-
-Time stamps are added directly in the filename by adding a suffix
-`_date-YYYYMMDDHHMM` which makes the file name non-BIDS compliant. This was
-added to prevent overwriting files in case a certain run needs to be done a
-second time because of a crash (Some of us are paranoid about keeping even
-cancelled runs during my experiments). This suffix should be removed to make the
-data set BIDS compliant. See `convertSourceToRaw.m` for more details.
-
-For example:
-
-```bash
-sub-090/ses-003/sub-090_ses-003_task-auditoryTask_run-023_events_date-202007291536.tsv
-```
-
 ## Documentation
 
 -   [Installation](./docs/installation.md)
 -   [How to use it: jupyter notebooks](./notebooks)
--   [Functions description](./docs/functions-description.md)
+-   [General documentation](https://cpp-bids.readthedocs.io/en/dev/index.html)
 
 ## Contributing
 
@@ -90,7 +65,7 @@ or you get stuck: it is more likely we did not do good enough a job at
 explaining things. So do not hesitate to open an issue, just to ask for
 clarification.
 
-### Guidestyle
+### Style guide
 
 -   We use camelCase.
 
diff --git a/docs/README.md b/docs/README.md
index d34286ac..7d772758 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,7 +4,7 @@
 
 ```bash
 virtualenv -p python3 cpp_bids
-source cpp_spm/bin/activate
+source cpp_bids/bin/activate
 
 pip install -r requirements.txt
 ```
diff --git a/docs/functions-description.md b/docs/functions-description.md
index b6c3ab0d..d8fbb811 100644
--- a/docs/functions-description.md
+++ b/docs/functions-description.md
@@ -5,42 +5,14 @@
 <!-- TOC -->
 
 -   [functions description](#functions-description)
-    -   [userInputs](#userinputs)
     -   [createFilename](#createfilename)
     -   [saveEventsFile](#saveeventsfile)
-    -   [checkCFG](#checkcfg)
-        -   [CFG content](#cfg-content)
     -   [createBoldJson](#createboldjson)
 
 <!-- /TOC -->
 
 <!-- lint enable -->
 
-## userInputs
-
-Get subject, run and session number and make sure they are positive integer
-values.
-
-By default this will return `cfg.subject.session = 1` even if you asked it to
-omit enquiring about sessions. This means that the folder tree will always
-include a session folder.
-
-```matlab
-[cfg] = userInputs(cfg)
-```
-
-If you use it with `cfg.subject.askGrpSess = [0 0]`, it won't ask you about
-group or session.
-
-If you use it with `cfg.subject.askGrpSess = [1]`, it will only ask you about
-group
-
-If you use it with `cfg.subject.askGrpSess = [0 1]`, it will only ask you about
-session
-
-If you use it with `cfg.subject.askGrpSess = [1 1]`, it will ask you about both.
-This is the default behavior.
-
 ## createFilename
 
 Create the BIDS compliant directories and filenames (but not the files) for the
@@ -64,76 +36,6 @@ 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 `n/a` if no value is provided.
 
-## checkCFG
-
-Check that we have all the fields that we need in the experiment parameters.
-
-### CFG content
-
-```matlab
-% The following can be modified by users but their effect might
-% only be effective after running checkCFG
-
-cfg.verbose = 0;
-
-cfg.subject.subjectGrp = '';
-cfg.subject.sessionNb = 1;
-cfg.subject.askGrpSess = [true true];
-
-% BOLD MRI details
-% some of those will be transferred to the correct fields in cfg.bids by checkCFG
-cfg.mri.repetitionTime = [];
-cfg.mri.contrastEnhancement = [];
-cfg.mri.phaseEncodingDirection = [];
-cfg.mri.reconstruction = [];
-cfg.mri.echo = [];
-cfg.mri.acquisition = [];
-
-cfg.fileName.task = '';
-cfg.fileName.zeroPadding = 3; % amount of 0 padding the subject, session, run number
-
-cfg.eyeTracker.do = false;
-
-% content of the json side-car file for bold data
-cfg.bids.mri.RepetitionTime = [];
-cfg.bids.mri.SliceTiming = '';
-cfg.bids.mri.TaskName = '';
-cfg.bids.mri.Instructions = '';
-cfg.bids.mri.TaskDescription = '';
-
-% content of the json side-car file for MEG
-cfg.bids.meg.TaskName = '';
-cfg.bids.meg.SamplingFrequency = [];
-cfg.bids.meg.PowerLineFrequency = [];
-cfg.bids.meg.DewarPosition = [];
-cfg.bids.meg.SoftwareFilters = [];
-cfg.bids.meg.DigitizedLandmarks = [];
-cfg.bids.meg.DigitizedHeadPoints = [];
-
-% content of the datasetDescription.json file
-cfg.bids.datasetDescription.Name = '';
-cfg.bids.datasetDescription.BIDSVersion =  '';
-cfg.bids.datasetDescription.License = '';
-cfg.bids.datasetDescription.Authors = {''};
-cfg.bids.datasetDescription.Acknowledgements = '';
-cfg.bids.datasetDescription.HowToAcknowledge = '';
-cfg.bids.datasetDescription.Funding = {''};
-cfg.bids.datasetDescription.ReferencesAndLinks = {''};
-cfg.bids.datasetDescription.DatasetDOI = '';
-
-
-%% Should not be modified by users
-% many of those fields are set up by checkCFG and you might get output that is not BIDS valid if you touch those
-cfg.fileName.dateFormat = 'yyyymmddHHMM'; % actual date of the experiment that is appended to the filename
-cfg.fileName.modality
-cgf.fileName.suffix.mri
-cgf.fileName.suffix.meg
-cfg.fileName.stim
-cfg.fileName.events
-cfg.fileName.datasetDescription
-
-```
-
 ## createBoldJson
 
 ```bash
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
index fb47029d..38d48d74 100644
--- a/docs/source/contributing.rst
+++ b/docs/source/contributing.rst
@@ -1,7 +1,8 @@
-Contributing
-************
+How to contribute to this project
+*********************************
 
-How to contribute to this project. 
+For more details please check the `contributing guidelines  <https://github.com/cpp-lln-lab/.github/blob/main/CONTRIBUTING.md>`_
+on the CPP lab's Github organization.
 
 
 Function templates
diff --git a/docs/source/function_description.rst b/docs/source/function_description.rst
index 5a721c9c..99940d0d 100644
--- a/docs/source/function_description.rst
+++ b/docs/source/function_description.rst
@@ -7,7 +7,6 @@ List of functions in the ``src`` folder.
 
 .. automodule:: src 
 
-.. autofunction:: checkCFG
 .. autofunction:: convertSourceToRaw
 .. autofunction:: createDataDictionary
 .. autofunction:: createDatasetDescription
diff --git a/docs/source/gui.rst b/docs/source/gui.rst
new file mode 100644
index 00000000..631f935f
--- /dev/null
+++ b/docs/source/gui.rst
@@ -0,0 +1,18 @@
+Graphic interface
+*****************
+  
+List of functions in the ``gui`` folder: those are mostly to handle the "graphic interface"
+that can be used to deal with ``userInputs()``.
+
+----
+
+.. automodule:: src.gui 
+
+.. autofunction:: askForGroupAndOrSession
+.. autofunction:: askUserCli
+.. autofunction:: askUserGui
+.. autofunction:: createQuestionList
+.. autofunction:: getIsQuestionToAsk
+.. autofunction:: setDefaultResponses
+
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index c1b29398..b663cb83 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,7 +1,4 @@
-.. cpp_bids_spm documentation master file, created by
-   sphinx-quickstart on Tue Oct 13 11:38:30 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. cpp_bids documentation master file
 
 Welcome to CPP BIDS documentation!
 **********************************
@@ -10,17 +7,47 @@ Welcome to CPP BIDS documentation!
    :maxdepth: 2
    :caption: Content
 
+   set_up
    function_description
    utilities
+   gui
    contributing
 
-This pipeline contains a set of functions to run fMRI analysis on a
-[BIDS data set](https://bids.neuroimaging.io/) using SPM12.
+A set of function for matlab and octave to create
+`BIDS-compatible <https://bids-specification.readthedocs.io/en/stable/>`_
+structure and filenames for the output of behavioral, EEG, fMRI, eyetracking
+experiments.
 
+Output format
+=============
 
+Modality agnostic aspect
+------------------------
 
+The files created by this toolbox will always follow the following pattern::
 
+  dataDir/sub-<[Group]SubNb>/ses-sesNb/sub-<[Group]SubNb>_ses-<sesNb>_task-<taskName>*_modality_date-*.fileExtension
 
+Subjects, session and run number labels will be numbers with zero padding up (default is set to
+3, meaning that subject 1 will become ``sub-001``).
+
+The ``Group`` name is optional.
+
+A session folder will ALWAYS be created even if not requested (default will be ``ses-001``).
+
+Task labels will be printed in ``camelCase`` in the filenames.
+
+Time stamps are added directly in the filename by adding a suffix
+``_date-*`` (default format is ``YYYYMMDDHHMM``) which makes the file name non-BIDS compliant. 
+This was added to prevent overwriting files in case a certain run needs to be done 
+a second time because of a crash. 
+Some of us are paranoid about keeping even cancelled runs during my experiments. 
+This suffix should be removed to make the data set BIDS compliant. 
+See ``convertSourceToRaw()`` for more details.
+
+For example::
+
+  /user/bob/dataset002/sub-090/ses-003/sub-090_ses-003_task-auditoryTask_run-023_events_date-202007291536.tsv
 
 
 Indices and tables
diff --git a/docs/source/set_up.rst b/docs/source/set_up.rst
new file mode 100644
index 00000000..41c9edfb
--- /dev/null
+++ b/docs/source/set_up.rst
@@ -0,0 +1,53 @@
+Setting up your experiment
+**************************
+
+Configuration
+=============
+
+.. todo:
+   describe how to set things up
+
+
+.. automodule:: src
+.. autofunction:: checkCFG
+
+.. automodule:: src.utils
+.. autofunction:: transferInfoToBids
+
+.. todo:
+    0: almost nothing gets printed on screen
+    1: allows saveEvents to print stuff when saving to file or createFilename to tell you where things will be saved
+    2: let printCredits do its job and lets saveEvents print extra info when it sends some warning.
+
+Group, subject, session and run
+===============================
+
+You can use the ``userInputs()`` function to easily set the group name as well as
+the subject, session and run number. You can ask the function to not bother you with 
+group and session 
+
+
+.. todo:
+
+    Get subject, run and session number and make sure they are positive integer
+    values.
+
+    By default this will return `cfg.subject.session = 1` even if you asked it to
+    omit enquiring about sessions. This means that the folder tree will always
+    include a session folder.
+
+    ```matlab
+    [cfg] = userInputs(cfg)
+    ```
+
+    If you use it with `cfg.subject.askGrpSess = [0 0]`, it won't ask you about
+    group or session.
+
+    If you use it with `cfg.subject.askGrpSess = [1]`, it will only ask you about
+    group
+
+    If you use it with `cfg.subject.askGrpSess = [0 1]`, it will only ask you about
+    session
+
+    If you use it with `cfg.subject.askGrpSess = [1 1]`, it will ask you about both.
+    This is the default behavior.
\ No newline at end of file
diff --git a/docs/source/utilities.rst b/docs/source/utilities.rst
index 9197bd4a..4d0fb7c2 100644
--- a/docs/source/utilities.rst
+++ b/docs/source/utilities.rst
@@ -19,4 +19,4 @@ List of functions in the ``utils`` folder.
 .. autofunction:: returnNamesExtraColumns
 .. autofunction:: returnNbColumns
 .. autofunction:: setDefaultFields
-.. autofunction:: transferInfoToBids
+

From 01c0736f0478031e36441d858e3400d31fdb3a66 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 16 Nov 2020 20:10:41 +0100
Subject: [PATCH 8/8] move command line function of user input in the doc

and fix typo
---
 docs/source/gui.rst       | 1 -
 docs/source/utilities.rst | 3 +++
 src/gui/askUserCli.m      | 2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/source/gui.rst b/docs/source/gui.rst
index 631f935f..3852af8a 100644
--- a/docs/source/gui.rst
+++ b/docs/source/gui.rst
@@ -9,7 +9,6 @@ that can be used to deal with ``userInputs()``.
 .. automodule:: src.gui 
 
 .. autofunction:: askForGroupAndOrSession
-.. autofunction:: askUserCli
 .. autofunction:: askUserGui
 .. autofunction:: createQuestionList
 .. autofunction:: getIsQuestionToAsk
diff --git a/docs/source/utilities.rst b/docs/source/utilities.rst
index 4d0fb7c2..f78e6fee 100644
--- a/docs/source/utilities.rst
+++ b/docs/source/utilities.rst
@@ -20,3 +20,6 @@ List of functions in the ``utils`` folder.
 .. autofunction:: returnNbColumns
 .. autofunction:: setDefaultFields
 
+.. automodule:: src.gui 
+
+.. autofunction:: askUserCli
diff --git a/src/gui/askUserCli.m b/src/gui/askUserCli.m
index d44d04bd..3615d9f5 100644
--- a/src/gui/askUserCli.m
+++ b/src/gui/askUserCli.m
@@ -2,7 +2,7 @@
 
 function responses = askUserCli(questions, responses)
     %
-    % It shows the questions to ask in the commnad window and checks, when it is necessary, if the
+    % It shows the questions to ask in the command window and checks, when it is necessary, if the
     % given input by the user is an integer.
     %
     % USAGE::