Skip to content

Commit 1ad6439

Browse files
Remi-GauRemi-Gau
committed
first go at rewriting some help sections
1 parent 5d8c48a commit 1ad6439

15 files changed

+373
-85
lines changed

‎docs/source/contributing.rst‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
Contributing
2+
************
3+
4+
How to contribute to this project.
5+
6+
7+
Function templates
8+
==================
9+
10+
.. automodule:: src.templates
11+
12+
Template proposal
13+
-----------------
14+
15+
::
16+
17+
% (C) Copyright 2020 CPP BIDS developers
18+
19+
function [argout1, argout2] = templateFunction(argin1, argin2, argin3)
20+
%
21+
% Short description of what the function does goes here.
22+
%
23+
% USAGE::
24+
%
25+
% [argout1, argout2] = templateFunction(argin1, [argin2 == default,] [argin3])
26+
%
27+
% :param argin1: (dimension) obligatory argument. Lorem ipsum dolor sit amet,
28+
% consectetur adipiscing elit. Ut congue nec est ac lacinia.
29+
% :type argin1: type
30+
% :param argin2: optional argument and its default value. And some of the
31+
% options can be shown in litteral like ``this`` or ``that``.
32+
% :type argin2: string
33+
% :param argin3: (dimension) optional argument
34+
%
35+
% :returns: - :argout1: (type) (dimension)
36+
% - :argout2: (type) (dimension)
37+
%
38+
% .. todo:
39+
%
40+
% - item 1
41+
% - item 2
42+
43+
% The code goes below
44+
45+
end
46+
47+
48+
end
49+
50+
.. autofunction:: templateFunction
51+
52+
53+
Example code in the help section
54+
--------------------------------
55+
56+
::
57+
58+
% (C) Copyright 2020 CPP BIDS developers
59+
60+
function templateFunctionExample()
61+
% This function illustrates a documentation test defined for MOdox.
62+
% Other than that it does absolutely nothinghort description of what
63+
% the function does goes here.
64+
%
65+
% Examples:
66+
% a=2;
67+
% disp(a)
68+
% % Expected output is prefixed by '%||' as in the following line:
69+
% %|| 2
70+
% %
71+
% % The test continues because no interruption through whitespace,
72+
% % as the previous line used a '%' comment character;
73+
% % thus the 'a' variable is still in the namespace and can be
74+
% % accessed.
75+
% b=3+a;
76+
% disp(a+[3 4])
77+
% %|| [5 6]
78+
%
79+
% % A new test starts here because the previous line was white-space
80+
% % only. Thus the 'a' and 'b' variables are not present here anymore.
81+
% % The following expression raises an error because the 'b' variable
82+
% % is not defined (and does not carry over from the previous test).
83+
% % Because the expected output indicates an error as well,
84+
% % the test passes
85+
% disp(b)
86+
% %|| error('Some error')
87+
%
88+
% % A set of expressions is ignored if there is no expected output
89+
% % (that is, no lines starting with '%||').
90+
% % Thus, the following expression is not part of any test,
91+
% % and therefore does not raise an error.
92+
% error('this is never executed)
93+
%
94+
%
95+
% % tests end here because test indentation has ended
96+
97+
% The code goes below
98+
99+
end
100+
101+
.. autofunction:: templateFunctionExample
102+
103+
104+

‎docs/source/function_description.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Function description
2+
********************
3+
4+
List of functions in the ``src`` folder.
5+
6+
----
7+
8+
.. automodule:: src
9+
10+
.. autofunction:: checkCFG
11+
.. autofunction:: convertSourceToRaw
12+
.. autofunction:: createDataDictionary
13+
.. autofunction:: createDatasetDescription
14+
.. autofunction:: createFilename
15+
.. autofunction:: createJson
16+
.. autofunction:: readAndFilterLogfile
17+
.. autofunction:: saveEventsFile
18+
.. autofunction:: userInputs
19+
20+

‎docs/source/index.rst‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
.. cpp_bids_spm documentation master file, created by
2+
sphinx-quickstart on Tue Oct 13 11:38:30 2020.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to CPP BIDS documentation!
7+
**********************************
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:caption: Content
12+
13+
function_description
14+
utilities
15+
contributing
16+
17+
This pipeline contains a set of functions to run fMRI analysis on a
18+
[BIDS data set](https://bids.neuroimaging.io/) using SPM12.
19+
20+
21+
22+
23+
24+
25+
26+
Indices and tables
27+
==================
28+
29+
* :ref:`genindex`
30+
* :ref:`modindex`
31+
* :ref:`search`

‎docs/source/utilities.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Utility functions
2+
*****************
3+
4+
List of functions in the ``utils`` folder.
5+
6+
----
7+
8+
.. automodule:: src.utils
9+
10+
.. autofunction:: checkCppBidsDependencies
11+
.. autofunction:: createValidName
12+
.. autofunction:: getFullFilename
13+
.. autofunction:: initializeExtraColumns
14+
.. autofunction:: isPositiveInteger
15+
.. autofunction:: printCreditsCppBids
16+
.. autofunction:: removeAllDateSuffix
17+
.. autofunction:: removeDateSuffix
18+
.. autofunction:: returnHeaderName
19+
.. autofunction:: returnNamesExtraColumns
20+
.. autofunction:: returnNbColumns
21+
.. autofunction:: setDefaultFields
22+
.. autofunction:: transferInfoToBids

‎src/createJson.m‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,34 @@
11
% (C) Copyright 2020 CPP_BIDS developers
22

33
function createJson(varargin)
4-
% createBoldJson(cfg, varargin)
54
%
65
% Creates the side car JSON file for a run.
7-
% This will only contain the minimum BIDS requirement and will likey be less
8-
% complete than the info you could from a proper conversion.
96
%
10-
% USAGE
7+
% For JSON sidecars for bold files, this will only contain the minimum BIDS
8+
% requirement and will likey be less complete than the info you could from
9+
% a proper BIDS conversion.
1110
%
12-
% createJson(cfg, modality)
11+
% USAGE::
1312
%
14-
% modality is string ('beh', 'func', 'eeg', 'ieeg', 'meg') to specify which
15-
% JSON to save
13+
% createJson(cfg [, modality] [, extraInfo])
14+
% createJson(cfg [, extraInfo])
1615
%
16+
% :param cfg: Configuration. See ``checkCFG()``.
17+
% :type cfg: structure
18+
% :param modality: can be any of the following ``'beh'``, ``'func'``, ``'eeg'``,
19+
% ``'ieeg'``, ``'meg'``) to specify which JSON to save. If it is not
20+
% provided it will read from ``cfg.fileName.modality``.
21+
% :type modality: string
22+
% :param extraInfo: contains information in the JSON file. Beware
23+
% that the BIDS validator is pretty strict on what information can
24+
% go in a JSON so this can be useful to store additional information
25+
% in your source dataset but it might have to be cleaned up to create
26+
% a valid BIDS dataset.
27+
% :type extraInfo: structure
1728
%
18-
% createJson(cfg, extraInfo)
19-
%
20-
% extraInfo is a strcuture to add axtra content can be added to the JSON file
21-
%
22-
%
23-
% createJson(cfg, modality, extraInfo)
24-
%
25-
% both are possible
29+
% .. TODO:
2630
%
31+
% - use input parser for this one
2732
%
2833

2934
[cfg, modality, extraInfo] = checkInput(varargin);

‎src/readAndFilterLogfile.m‎

Lines changed: 25 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,37 @@
11
% (C) Copyright 2020 CPP_BIDS developers
22

33
function outputFiltered = readAndFilterLogfile(columnName, filterBy, saveOutputTsv, varargin)
4-
% outputFiltered = readAndFilterLogfile(columnName, filterBy, saveOutputTsv, varargin)
54
%
6-
% It will display in the command window the content of the `output.tsv' filtered by one element
5+
% It will display in the command window the content of the ``output.tsv`` filtered by one element
76
% of a target column.
87
%
9-
% INPUT:
8+
% USAGE::
109
%
11-
% - columnName: string, the header of the column where the content of insterest is stored
12-
% (e.g., for 'trigger' will be 'trial type')
13-
% - filterBy: string, the content of the column you want to filter out. It can take just
14-
% part of the content name (e.g., you want to display the triggers and you have
15-
% 'trigger_motion' and 'trigger_static', 'trigger' as input will do)
16-
% - saveOutputTsv: boolean to save the filtered ouput
17-
% - varargin: either cfg (to display the last run output) or the file path as string
10+
% outputFiltered = readAndFilterLogfile(columnName, filterBy, saveOutputTsv, tsvFile)
1811
%
19-
% OUTPUT:
12+
% outputFiltered = readAndFilterLogfile(columnName, filterBy, saveOutputTsv, cfg)
2013
%
21-
% - outputFiltered: dataset with only the specified content, to see it in the command window
22-
% use display(outputFiltered)
14+
% :param columnName: the header of the column where the content of interest is stored
15+
% (for example for ``trigger`` will be ``trial type``)
16+
% :type columnName: string
17+
% :param filterBy: the content of the column you want to filter out. It can take just
18+
% part of the content name (for example, if you want to display the triggers
19+
% and you have ``trigger_motion`` and ``trigger_static``,
20+
% ``trigger`` as input will do)
21+
% :type filterBy: string
22+
% :param saveOutputTsv: flag to save output on file
23+
% :type saveOutputTsv: boolean
24+
% :param tsvFile: TSV file to filter
25+
% :type tsvFile: string
26+
% :param cfg: Configuration. See ``checkCFG()``. If ``cfg`` is given as input the name
27+
% of the TSV file to read will be infered from there.
28+
% :type cfg: structure
29+
%
30+
% :returns:
31+
%
32+
% :outputFiltered: dataset with only the specified content, to see it
33+
% in the command window use ``display(outputFiltered)``.
34+
%
2335

2436
% Create tag to add to output file in case you want to save it
2537
outputFilterTag = ['_filteredBy-' columnName '_' filterBy '.tsv'];

‎src/saveEventsFile.m‎

Lines changed: 44 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,68 @@
11
% (C) Copyright 2020 CPP_BIDS developers
22

33
function [logFile] = saveEventsFile(action, cfg, logFile)
4-
% [logFile] = saveEventsFile(action, cfg, logFile)
5-
%
4+
%
65
% Function to save output files for events that will be BIDS compliant.
76
%
8-
% USAGE
7+
% USAGE::
8+
%
9+
% [logFile] = saveEventsFile(action, cfg, logFile)
910
%
10-
% [logFile] = saveEventsFile('init', [cfg], logFile)
11-
% [logFile] = saveEventsFile('open', [cfg], logFile)
12-
% [logFile] = saveEventsFile('open_stim', [cfg], logFile)
13-
% [logFile] = saveEventsFile('save', [cfg], logFile)
14-
% [logFile] = saveEventsFile('close', cfg, logFile)
11+
% logFile] = saveEventsFile('init', [cfg], logFile)
12+
% logFile] = saveEventsFile('open', [cfg], logFile)
13+
% logFile] = saveEventsFile('open_stim', [cfg], logFile)
14+
% logFile] = saveEventsFile('save', [cfg], logFile)
15+
% logFile] = saveEventsFile('close', cfg, logFile)
1516
%
1617
% INPUTS
1718
%
1819
% logFile:
19-
% When you want to save your data logFile contains the data you want to save.
20-
% The logFile variable that contains the n events you want to % save must be a nx1 structure.
20+
%
21+
% When you want to save your data ``logFile`` contains the data you want to save.
22+
% The ``logFile`` variable that contains the n events you want to save must be a nx1 structure.
2123
% Each field will be saved in a separate column.
2224
%
23-
% example:
24-
% logFile(1,1).onset = 2;
25-
% logFile(1,1).trial_type = 'motion_up';
26-
% logFile(1,1).duration = 1;
27-
% logFile(1,1).speed = 2;
28-
% logFile(1,1).is_fixation = true;
25+
% example::
2926
%
30-
% logFile(2,1).onset = 3;
31-
% logFile(2,1).trial_type = 'static';
32-
% logFile(2,1).duration = 4;
33-
% logFile(2,1).is_fixation = 3;
27+
% logFile(1,1).onset = 2;
28+
% logFile(1,1).trial_type = 'motion_up';
29+
% logFile(1,1).duration = 1;
30+
% logFile(1,1).speed = 2;
31+
% logFile(1,1).is_fixation = true;
32+
%
33+
% logFile(2,1).onset = 3;
34+
% logFile(2,1).trial_type = 'static';
35+
% logFile(2,1).duration = 4;
36+
% logFile(2,1).is_fixation = 3;
3437
%
3538
%
3639
% action:
37-
% - 'open': will create the file ID and return it in logFile.fileID using the information in
38-
% the expParameters structure. This file ID is then reused when calling that function
39-
% to save data into this file.
40-
% This creates the header with the obligatory 'onset', 'trial_type', 'duration' required
41-
% by BIDS and other columns can be specified in varargin.
4240
%
43-
% example : logFile = saveEventsFile('open', cfg, [], 'direction', 'speed', 'target');
41+
% - ``'open'`` will create the file ID and return it in ``logFile.fileID`` using the information in
42+
% the ``cfg`` structure. This file ID is then reused when calling that function
43+
% to save data into this file.
44+
% This creates the header with the obligatory ``'onset'``, ``'duration'`` required
45+
% by BIDS and other columns can be specified in varargin.
46+
%
47+
% example::
48+
%
49+
% logFile = saveEventsFile('open', cfg, [], 'direction', 'speed', 'target');
50+
%
51+
%
52+
% - ``'save'`` will save the data contained in logfile by using the file ID ``logFile.fileID``;
53+
% logfile must then contain:
54+
%
55+
% - logFile.onset
56+
% - logFile.trial_type
57+
% - logFile.duration
4458
%
45-
% - 'save': will save the data contained in logfile by using the file ID logFile.fileID;
46-
% logfile must then contain:
47-
% - logFile.onset
48-
% - logFile.trial_type
49-
% - logFile.duration
5059
% The name of any extra column whose content must be saved should be listed in varargin.
5160
%
52-
% - 'close': closes the file with file ID logFile.fileID. If expParameters.verbose is set
53-
% to true then this will tell you where the file is located.
61+
% - ``'close'`` closes the file with file ID ``logFile.fileID``. If ``cfg.verbose`` is set
62+
% to true then this will tell you where the file is located.
63+
%
64+
% See ``tests/test_saveEventsFile()`` for more details on how to use it.
5465
%
55-
% See test_saveEventsFile in the test folder for more details on how to use it.
5666

5767
if nargin < 1
5868
error('Missing action input');

‎src/templates/templateFunction.m‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
% options can be shown in litteral like ``this`` or ``that``.
1616
% :type argin2: string
1717
% :param argin3: (dimension) optional argument
18+
% :type argin3: integer
1819
%
1920
% :returns: - :argout1: (type) (dimension)
2021
% - :argout2: (type) (dimension)

0 commit comments

Comments
 (0)