Skip to content

Commit f875ef7

Browse files
Remi-GauRemi-Gau
authored
Merge pull request #74 from Remi-Gau/remi-gui_user_input
improve user input
2 parents c6659f7 + b89476b commit f875ef7

20 files changed

+958
-672
lines changed

‎README.md‎

Lines changed: 24 additions & 373 deletions
Large diffs are not rendered by default.

‎docs/functions_description.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# functions description
2+
3+
<!-- vscode-markdown-toc -->
4+
* 1. [userInputs](#userInputs)
5+
* 2. [createFilename](#createFilename)
6+
* 3. [saveEventsFile](#saveEventsFile)
7+
* 4. [checkCFG](#checkCFG)
8+
* 5. [CFG content](#CFGcontent)
9+
* 6. [createBoldJson](#createBoldJson)
10+
11+
<!-- vscode-markdown-toc-config
12+
numbering=true
13+
autoSave=true
14+
/vscode-markdown-toc-config -->
15+
<!-- /vscode-markdown-toc -->
16+
17+
## 1. <a name='userInputs'></a>userInputs
18+
19+
Get subject, run and session number and make sure they are positive integer values.
20+
21+
By default this will return `cfg.subject.session = 1` even if you asked it to omit enquiring about sessions. This means
22+
that the folder tree will always include a session folder.
23+
24+
```matlab
25+
[cfg] = userInputs(cfg)
26+
```
27+
28+
If you use it with `cfg.subject.askGrpSess = [0 0]`, it won't ask you about group or session.
29+
30+
If you use it with `cfg.subject.askGrpSess = [1]`, it will only ask you about group
31+
32+
If you use it with `cfg.subject.askGrpSess = [0 1]`, it will only ask you about session
33+
34+
If you use it with `cfg.subject.askGrpSess = [1 1]`, it will ask you about both. This is the default behavior.
35+
36+
37+
## 2. <a name='createFilename'></a>createFilename
38+
39+
Create the BIDS compliant directories and filenames (but not the files) for the behavioral output for this subject / session / run.
40+
41+
The folder tree will always include a session folder.
42+
43+
It will also create the right filename for the eye-tracking data file if you ask it.
44+
45+
For the moment the date of acquisition is appended to the filename
46+
- can work for behavioral experiment if `cfg.testingDevice` is set to `pc`,
47+
- can work for fMRI experiment if `cfg.testingDevice` is set to `mri`,
48+
- can work for simple eyetracking data if `cfg.eyeTracker.do` is set to 1.
49+
50+
## 3. <a name='saveEventsFile'></a>saveEventsFile
51+
52+
Function to save output files for events that will be BIDS compliant.
53+
54+
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.
55+
56+
## 4. <a name='checkCFG'></a>checkCFG
57+
58+
Check that we have all the fields that we need in the experiment parameters.
59+
60+
## 5. <a name='CFGcontent'></a>CFG content
61+
62+
```matlab
63+
% The following can be modified by users but their effect might
64+
% only be effective after running checkCFG
65+
66+
cfg.verbose = 0;
67+
68+
cfg.subject.subjectGrp = '';
69+
cfg.subject.sessionNb = 1;
70+
cfg.subject.askGrpSess = [true true];
71+
72+
% BOLD MRI details
73+
% some of those will be transferred to the correct fields in cfg.bids by checkCFG
74+
cfg.mri.repetitionTime = [];
75+
cfg.mri.contrastEnhancement = [];
76+
cfg.mri.phaseEncodingDirection = [];
77+
cfg.mri.reconstruction = [];
78+
cfg.mri.echo = [];
79+
cfg.mri.acquisition = [];
80+
81+
cfg.fileName.task = '';
82+
cfg.fileName.zeroPadding = 3; % amount of 0 padding the subject, session, run number
83+
84+
cfg.eyeTracker.do = false;
85+
86+
% content of the json side-car file for bold data
87+
cfg.bids.mri.RepetitionTime = [];
88+
cfg.bids.mri.SliceTiming = '';
89+
cfg.bids.mri.TaskName = '';
90+
cfg.bids.mri.Instructions = '';
91+
cfg.bids.mri.TaskDescription = '';
92+
93+
% content of the json side-car file for MEG
94+
cfg.bids.meg.TaskName = '';
95+
cfg.bids.meg.SamplingFrequency = [];
96+
cfg.bids.meg.PowerLineFrequency = [];
97+
cfg.bids.meg.DewarPosition = [];
98+
cfg.bids.meg.SoftwareFilters = [];
99+
cfg.bids.meg.DigitizedLandmarks = [];
100+
cfg.bids.meg.DigitizedHeadPoints = [];
101+
102+
% content of the datasetDescription.json file
103+
cfg.bids.datasetDescription.Name = '';
104+
cfg.bids.datasetDescription.BIDSVersion = '';
105+
cfg.bids.datasetDescription.License = '';
106+
cfg.bids.datasetDescription.Authors = {''};
107+
cfg.bids.datasetDescription.Acknowledgements = '';
108+
cfg.bids.datasetDescription.HowToAcknowledge = '';
109+
cfg.bids.datasetDescription.Funding = {''};
110+
cfg.bids.datasetDescription.ReferencesAndLinks = {''};
111+
cfg.bids.datasetDescription.DatasetDOI = '';
112+
113+
114+
%% Should not be modified by users
115+
% many of those fields are set up by checkCFG and you might get output that is not BIDS valid if you touch those
116+
cfg.fileName.dateFormat = 'yyyymmddHHMM'; % actual date of the experiment that is appended to the filename
117+
cfg.fileName.modality
118+
cgf.fileName.suffix.mri
119+
cgf.fileName.suffix.meg
120+
cfg.fileName.stim
121+
cfg.fileName.events
122+
cfg.fileName.datasetDescription
123+
124+
```
125+
126+
## 6. <a name='createBoldJson'></a>createBoldJson
127+
128+
```
129+
createBoldJson(cfg)
130+
```
131+
132+
This function creates a very light-weight version of the side-car JSON file for a BOLD functional run.
133+
134+
This will only contain the minimum BIDS requirement and will likely be less complete than the info you could from DICOM conversion.
135+
136+
If you put the following line at the end of your experiment script, it will dump the content of the `extraInfo` structure in the json file.
137+
138+
```
139+
createBoldJson(cfg, extraInfo)
140+
```
141+
142+
This allows to add all the parameters that you used to run your experiment in a human readable format: so that when you write your methods sections 2 years later ("the reviewer asked me for the size of my fixation cross... FML"), the info you used WHEN you ran the experiment is saved in an easily accessible text format. 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).
143+
144+
Also to reading your experiment parameters, you won't have to read it 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.

‎docs/installation.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Installation
2+
3+
<!-- vscode-markdown-toc -->
4+
* 1. [Download with git](#Downloadwithgit)
5+
* 2. [Add as a submodule](#Addasasubmodule)
6+
* 2.1. [Example for submodule usage](#Exampleforsubmoduleusage)
7+
* 3. [Direct download](#Directdownload)
8+
9+
<!-- vscode-markdown-toc-config
10+
numbering=true
11+
autoSave=true
12+
/vscode-markdown-toc-config -->
13+
<!-- /vscode-markdown-toc -->
14+
15+
## 1. <a name='Downloadwithgit'></a>Download with git
16+
17+
``` bash
18+
cd fullpath_to_directory_where_to_install
19+
20+
# use git to download the code
21+
git clone https://github.com/cpp-lln-lab/CPP_BIDS.git
22+
23+
# move into the folder you have just created
24+
cd CPP_BIDS
25+
26+
# add the src folder to the matlab path and save the path
27+
matlab -nojvm -nosplash -r "addpath(fullfile(pwd, 'src')); savepath ();"
28+
```
29+
30+
Then get the latest commit:
31+
```bash
32+
# from the directory where you downloaded the code
33+
git pull origin master
34+
```
35+
36+
To work with a specific version, create a branch at a specific version tag number
37+
```bash
38+
# creating and checking out a branch that will be called version1 at the version tag v0.0.1
39+
git checkout -b version1 v0.0.1
40+
```
41+
42+
## 2. <a name='Addasasubmodule'></a>Add as a submodule
43+
44+
Add it as a submodule in the repo you are working on.
45+
46+
``` bash
47+
cd fullpath_to_directory_where_to_install
48+
49+
# use git to download the code
50+
git submodule add https://github.com/cpp-lln-lab/CPP_BIDS.git
51+
52+
# move into the folder you have just created
53+
cd CPP_BIDS
54+
55+
# add the src folder to the matlab path and save the path
56+
matlab -nojvm -nosplash -r "addpath(fullfile(pwd, 'src'))"
57+
```
58+
59+
To get the latest commit you then need to update the submodule with the information
60+
on its remote repository and then merge those locally.
61+
```bash
62+
git submodule update --remote --merge
63+
```
64+
65+
Remember that updates to submodules need to be committed as well.
66+
67+
### 2.1. <a name='Exampleforsubmoduleusage'></a>Example for submodule usage
68+
69+
So say you want to clone a repo that has some nested submodules, then you would type this to get the content of all the submodules at once (here with assumption that you want to clone my experiment repo):
70+
```bash
71+
# clone the repo
72+
git clone https://github.com/user_name/myExperiment.git
73+
74+
# go into the directory
75+
cd myExperiment
76+
77+
# initialize and get the content of the first level of submodules (e.g. CPP_PTB and CPP_BIDS)
78+
git submodule init
79+
git submodule update
80+
81+
# get the nested submodules JSONio and BIDS-matlab for CPP_BIDS
82+
git submodule foreach --recursive 'git submodule init'
83+
git submodule foreach --recursive 'git submodule update'
84+
```
85+
86+
87+
## 3. <a name='Directdownload'></a>Direct download
88+
89+
Download the code. Unzip. And add to the matlab path.
90+
91+
Pick a specific version:
92+
93+
https://github.com/cpp-lln-lab/CPP_BIDS/releases
94+
95+
Or take the latest commit (NOT RECOMMENDED):
96+
97+
https://github.com/cpp-lln-lab/CPP_BIDS/archive/master.zip

‎docs/usage.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Usage
2+
3+
<!-- vscode-markdown-toc -->
4+
* 1. [To save events.tsv file](#Tosaveevents.tsvfile)
5+
6+
<!-- vscode-markdown-toc-config
7+
numbering=true
8+
autoSave=true
9+
/vscode-markdown-toc-config -->
10+
<!-- /vscode-markdown-toc -->
11+
12+
13+
14+
## 1. <a name='Tosaveevents.tsvfile'></a>To save events.tsv file
15+
16+
```matlab
17+
18+
% define the folder where the data will be saved
19+
cfg.outputDir = fullfile(pwd, '..', 'output');
20+
21+
% define the name of the task
22+
cfg.task.name = 'test task';
23+
24+
% can use the userInputs function to collect subject info
25+
% cfg = userInputs;
26+
27+
% or declare it directly
28+
cfg.subject.subjectNb = 1;
29+
cfg.subject.runNb = 1;
30+
31+
% by default we assume you are running things on a behavioral PC with no eyetracker
32+
% cfg.eyeTracker = false;
33+
% cfg.testingDevice = 'PC';
34+
35+
% if the testing device is set to 'PC' then the data will be saved in the `beh` folder
36+
% if set to 'mri' then the data will be saved in the `func` folder
37+
% cfg.testingDevice = 'mri';
38+
% if set to 'eeg' then the data will be saved in the `eeg` folder
39+
% cfg.testingDevice = 'eeg';
40+
41+
% create the filenames: this include a step to check that all the information is there (checkCFG)
42+
[cfg] = createFilename(cfg);
43+
44+
% initialize the events files with the typical BIDS columns (onsets, duration, trial_type)
45+
% logFile = saveEventsFile('open', cfg);
46+
47+
% You can add some more in this case (Speed and is_Fixation)
48+
logFile.extraColumns = {'Speed', 'is_Fixation'};
49+
logFile = saveEventsFile('open', cfg, logFile);
50+
51+
% The information about 2 events that we want to save
52+
% NOTE : If the user DOES NOT provide `onset`, `trial_type`, this events will be skipped.
53+
logFile(1,1).onset = 2;
54+
logFile(1,1).trial_type = 'motion_up';
55+
logFile(1,1).duration = 1;
56+
logFile(1,1).Speed = 2;
57+
logFile(1,1).is_Fixation = true;
58+
59+
logFile(2,1).onset = 3;
60+
logFile(2,1).trial_type = 'static';
61+
logFile(2,1).duration = 4;
62+
logFile(2,1).is_Fixation = 3;
63+
64+
% add those 2 events to the events.tsv file
65+
saveEventsFile('save', cfg, logFile);
66+
67+
% close the file
68+
saveEventsFile('close', cfg, logFile);
69+
70+
```
71+
72+
If you want to save more complex events.tsv file you can save several columns at once.
73+
74+
```matlab
75+
cfg.subject.subjectNb = 1;
76+
cfg.subject.runNb = 1;
77+
cfg.task.name = 'testtask';
78+
cfg.outputDir = outputDir;
79+
80+
cfg.testingDevice = 'mri';
81+
82+
[cfg] = createFilename(cfg);
83+
84+
% You can specify how many columns we want for each variable
85+
% will set 1 columns with name Speed
86+
% will set 12 columns with names LHL24-01, LHL24-02, ...
87+
% will set 1 columns with name is_Fixation
88+
89+
logFile.extraColumns.Speed.length = 1;
90+
logFile.extraColumns.LHL24.length = 12;
91+
logFile.extraColumns.is_Fixation.length = 1;
92+
93+
logFile = saveEventsFile('open', cfg, logFile);
94+
95+
logFile(1, 1).onset = 2;
96+
logFile(end, 1).trial_type = 'motion_up';
97+
logFile(end, 1).duration = 3;
98+
logFile(end, 1).Speed = 2;
99+
logFile(end, 1).is_Fixation = true;
100+
logFile(end, 1).LHL24 = 1:12;
101+
102+
saveEventsFile('save', cfg, logFile);
103+
104+
saveEventsFile('close', cfg, logFile);
105+
106+
```
107+
108+
If you have many columns to define but only a few with several columns, you can do this:
109+
110+
```matlab
111+
% define the extra columns: they will be added to the tsv files in the order the user input them
112+
logFile.extraColumns = {'Speed', 'is_Fixation'};
113+
114+
[cfg] = createFilename(cfg);
115+
116+
% initialize the logFile variable
117+
[logFile] = saveEventsFile('init', cfg, logFile);
118+
119+
% set the real length we really want
120+
logFile.extraColumns.Speed.length = 12;
121+
122+
% open the file
123+
logFile = saveEventsFile('open', cfg, logFile);
124+
```

0 commit comments

Comments
 (0)