Merge pull request #136 from cpp-lln-lab/doc

[WIP] general update of the documentation

Author: Remi-Gau

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.
 

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
 ```

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

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

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

docs/source/gui.rst

@@ -0,0 +1,17 @@
+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:: askUserGui
+.. autofunction:: createQuestionList
+.. autofunction:: getIsQuestionToAsk
+.. autofunction:: setDefaultResponses
+
+

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

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.

docs/source/utilities.rst

@@ -19,4 +19,7 @@ List of functions in the ``utils`` folder.
 .. autofunction:: returnNamesExtraColumns
 .. autofunction:: returnNbColumns
 .. autofunction:: setDefaultFields
-.. autofunction:: transferInfoToBids
+
+.. automodule:: src.gui 
+
+.. autofunction:: askUserCli