Skip to content

Commit c5c3f83

Browse files
Remi-GauRemi-Gau
authored
Merge pull request #22 from Remi-Gau/remi-doc
[DOC] rewrite readme
2 parents 47e3a6e + e373599 commit c5c3f83

7 files changed

+148
-199
lines changed

‎README.md

+116-55
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,131 @@
1+
[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-) [![Build Status](https://travis-ci.com/cpp-lln-lab/CPP_BIDS.svg?branch=master)](https://travis-ci.com/cpp-lln-lab/CPP_BIDS)
2+
13
# CPP_BIDS
2-
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
3-
[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
4-
<!-- ALL-CONTRIBUTORS-BADGE:END -->
4+
5+
<!-- TOC -->
6+
7+
- [CPP_BIDS](#cpp_bids)
8+
- [Usage](#usage)
9+
- [Functions descriptions](#functions-descriptions)
10+
- [userInputs](#userinputs)
11+
- [createFilename](#createfilename)
12+
- [saveEventsFile](#saveeventsfile)
13+
- [checkCFG](#checkcfg)
14+
- [How to install](#how-to-install)
15+
- [Use the matlab package manager](#use-the-matlab-package-manager)
16+
- [Contributing](#contributing)
17+
- [Guidestyle](#guidestyle)
18+
- [BIDS naming convention](#bids-naming-convention)
19+
20+
<!-- /TOC -->
521

622
A set of function for matlab and octave to create [BIDS-compatible](https://bids-specification.readthedocs.io/en/stable/) folder structure and filenames for the output of behavioral, EEG, fMRI, eyetracking studies.
723

8-
Here are the naming templates used.
24+
## Usage
925

10-
- BOLD
26+
```matlab
1127
12-
`sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>]_<contrast_label>.nii[.gz]`
28+
% define the folder where the data will be saved
29+
expParameters.outputDir = fullfile(pwd, '..', 'output');
1330
14-
- iEEG
31+
% define the name of the task
32+
expParameters.task = 'testtask';
1533
16-
`sub-<label>[_ses-<label>]_task-<task_label>[_run-<index>]_ieeg.json`
34+
% can use the userInputs function to collect subject info
35+
% expParameters = userInputs;
1736
18-
- EEG
37+
% or declare it directly
38+
expParameters.subjectGrp = '';
39+
expParameters.subjectNb = 1;
40+
expParameters.sessionNb = 1;
41+
expParameters.runNb = 1;
1942
20-
`sub-<label>[_ses-<label>]_task-<label>[_run-<index>]_eeg.<manufacturer_specific_extension>`
43+
% Use the verbose switch to know where your data is being saved
44+
expParameters.verbose = true;
2145
22-
- Eyetracker
46+
% In case you are using en eyetracker
47+
cfg.eyeTracker = false;
2348
24-
`sub-<participant_label>[_ses-<label>][_acq-<label>]_task-<task_label>_eyetrack.<manufacturer_specific_extension>`
49+
% if the device is set to 'PC' then the data will be saved
50+
% in the `beh` folder
51+
cfg.device = 'PC';
2552
53+
% if the device is set to 'scanner' then the data will be saved
54+
% in the `func` folder
55+
% cfg.device = 'scanner';
2656
27-
## Contributing
57+
% check that cfg and exparameters have all the necessary information
58+
% and fill in any missing field
59+
expParameters = checkCFG(cfg, expParameters);
2860
29-
Feel free to open issues to report a bug and ask for improvements.
61+
% create the filenames
62+
expParameters = createFilename(cfg, expParameters);
3063
31-
### Guidestyle
64+
% initialize the events files with the typical BIDS
65+
% columns (onsets, duration, trial_type)
66+
% and add some more in this case (Speed and is_Fixation)
67+
logFile = saveEventsFile('open', expParameters, [], 'Speed', 'is_Fixation');
3268
33-
- We use camelCase.
34-
- We keep the McCabe complexity as reported by the [check_my_code function](https://github.com/Remi-Gau/matlab_checkcode) below 15.
69+
% create the information about 2 events that we want to save
70+
logFile(1,1).onset = 2;
71+
logFile(1,1).trial_type = 'motion_up';
72+
logFile(1,1).duration = 1;
73+
logFile(1,1).speed = 2;
74+
logFile(1,1).is_fixation = true;
75+
76+
logFile(2,1).onset = 3;
77+
logFile(2,1).trial_type = 'static';
78+
logFile(2,1).duration = 4;
79+
logFile(2,1).is_fixation = 3;
80+
81+
% add those 2 events to the events.tsv file
82+
saveEventsFile('save', expParameters, logFile, 'speed', 'is_fixation');
83+
84+
% close the file
85+
saveEventsFile('close', expParameters, logFile);
86+
87+
```
88+
89+
## Functions descriptions
90+
91+
### userInputs
92+
93+
Get subject, run and session number and make sure they are positive integer values.
94+
95+
### createFilename
96+
97+
Create the BIDS compliant directories and filenames (but not the files) for the behavioral
98+
output for this subject / session / run.
99+
100+
Will also create the right filename for the eye-tracking data file.
101+
102+
For the moment the date of acquisition is appended to the filename
103+
- can work for behavioral experiment if cfg.device is set to 'PC'
104+
- can work for fMRI experiment if cfg.device is set to 'scanner'
105+
- can work for simple eyetracking data if cfg.eyeTracker is set to 1
106+
107+
### saveEventsFile
108+
109+
Function to save output files for events that will be BIDS compliant.
110+
111+
### checkCFG
112+
Check that we have all the fields that we need in the experiment parameters.
35113

36114
## How to install
37115

38116
### Use the matlab package manager
39117

40-
This repository can be added as a dependencies by listing it in a [mpm-requirements.txt file](.mpm-requirements.txt)
41-
as follows:
118+
This repository can be added as a dependencies by listing it in a
119+
[mpm-requirements.txt file](.mpm-requirements.txt) as follows:
42120

43121
```
44122
CPP_BIDS -u https://github.com/cpp-lln-lab/CPP_BIDS.git
45123
```
46124

47-
You can then use the [matlab package manager](https://github.com/mobeets/mpm), to simply download the appropriate version of those dependencies and add them to your path by running a `getDependencies` function like the one below where you just need to replace `YOUR_EXPERIMENT_NAME` by the name of your experiment.
48-
125+
You can then use the [matlab package manager](https://github.com/mobeets/mpm), to simply download
126+
the appropriate version of those dependencies and add them to your path by running a
127+
`getDependencies` function like the one below where you just need to replace
128+
`YOUR_EXPERIMENT_NAME` by the name of your experiment.
49129

50130
```matlab
51131
function getDependencies(action)
@@ -76,50 +156,31 @@ addpath(genpath(fullfile(mpm_folder, 'mpm-packages', 'mpm-collections', experime
76156
end
77157
```
78158

79-
## Functions descriptions
80-
81-
### userInputs
82-
83-
Get subject, run and session number and make sure they are positive integer values.
84-
159+
## Contributing
85160

86-
### createFilename
161+
Feel free to open issues to report a bug and ask for improvements.
87162

88-
Create the BIDS compliant directories and filenames (but not the files) for the behavioral output for this subject /
89-
session / run.
163+
### Guidestyle
90164

91-
Will also create the right filename for the eye-tracking data file.
165+
- We use camelCase.
166+
- We keep the McCabe complexity as reported by the [check_my_code function](https://github.com/Remi-Gau/matlab_checkcode) below 15.
92167

93-
For the moment the date of acquisition is appended to the filename
94-
- can work for behavioral experiment if cfg.device is set to 'PC'
95-
- can work for fMRI experiment if cfg.device is set to 'scanner'
96-
- can work for simple eyetracking data if cfg.eyeTracker is set to 1
168+
### BIDS naming convention
97169

98-
### saveEventsFile
170+
Here are the naming templates used.
99171

100-
Function to save output files for events that will be BIDS compliant.
172+
- BOLD
101173

174+
`sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>]_<contrast_label>.nii[.gz]`
102175

103-
### checkCFG
104-
Check that we have all the fields that we need in the experiment parameters.
176+
- iEEG
105177

106-
## Contributors ✨
178+
`sub-<label>[_ses-<label>]_task-<task_label>[_run-<index>]_ieeg.json`
107179

108-
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
180+
- EEG
109181

110-
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
111-
<!-- prettier-ignore-start -->
112-
<!-- markdownlint-disable -->
113-
<table>
114-
<tr>
115-
<td align="center"><a href="https://github.com/CerenB"><img src="https://avatars1.githubusercontent.com/u/10451654?v=4" width="100px;" alt=""/><br /><sub><b>CerenB</b></sub></a><br /><a href="https://github.com/cpp-lln-lab/CPP_BIDS/commits?author=CerenB" title="Code">💻</a> <a href="#design-CerenB" title="Design">🎨</a> <a href="https://github.com/cpp-lln-lab/CPP_BIDS/commits?author=CerenB" title="Documentation">📖</a></td>
116-
<td align="center"><a href="https://github.com/marcobarilari"><img src="https://avatars3.githubusercontent.com/u/38101692?v=4" width="100px;" alt=""/><br /><sub><b>marcobarilari</b></sub></a><br /><a href="https://github.com/cpp-lln-lab/CPP_BIDS/commits?author=marcobarilari" title="Code">💻</a> <a href="#design-marcobarilari" title="Design">🎨</a> <a href="https://github.com/cpp-lln-lab/CPP_BIDS/commits?author=marcobarilari" title="Documentation">📖</a></td>
117-
<td align="center"><a href="https://remi-gau.github.io/"><img src="https://avatars3.githubusercontent.com/u/6961185?v=4" width="100px;" alt=""/><br /><sub><b>Remi Gau</b></sub></a><br /><a href="https://github.com/cpp-lln-lab/CPP_BIDS/commits?author=Remi-Gau" title="Code">💻</a> <a href="#design-Remi-Gau" title="Design">🎨</a> <a href="https://github.com/cpp-lln-lab/CPP_BIDS/commits?author=Remi-Gau" title="Documentation">📖</a></td>
118-
</tr>
119-
</table>
182+
`sub-<label>[_ses-<label>]_task-<label>[_run-<index>]_eeg.<manufacturer_specific_extension>`
120183

121-
<!-- markdownlint-enable -->
122-
<!-- prettier-ignore-end -->
123-
<!-- ALL-CONTRIBUTORS-LIST:END -->
184+
- Eyetracker
124185

125-
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
186+
`sub-<participant_label>[_ses-<label>][_acq-<label>]_task-<task_label>_eyetrack.<manufacturer_specific_extension>`

‎checkCFG.m

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
function [expParameters, cfg] = checkCFG(cfg,expParameters)
1+
function [expParameters, cfg] = checkCFG(cfg, expParameters)
22
% check that we have all the fields that we need in the experiment
33
% parameters
44

‎createFilename.m

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
function expParameters = createFilename(cfg,expParameters)
1+
function expParameters = createFilename(cfg, expParameters)
22
% create the BIDS compliant directories and filenames for the behavioral output for this subject /
33
% session / run using the information from cfg and expParameters.
44
% Will also create the right filename for the eyetracking data file.

‎createFilename.m~

-132
This file was deleted.

‎saveEventsFile.m

+19
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,24 @@
44
% INPUTS
55
%
66
% logFile:
7+
% When you want to save your data logFile contains the data you want to save.
8+
% The logFile variable that contains the n events you want to % save must be a nx1 structure.
9+
% Each field will be saved in a separate column.
10+
%
11+
% example:
12+
% logFile(1,1).onset = 2;
13+
% logFile(1,1).trial_type = 'motion_up';
14+
% logFile(1,1).duration = 1;
15+
% logFile(1,1).speed = 2;
16+
% logFile(1,1).is_fixation = true;
17+
%
18+
% logFile(2,1).onset = 3;
19+
% logFile(2,1).trial_type = 'static';
20+
% logFile(2,1).duration = 4;
21+
% logFile(2,1).is_fixation = 3;
22+
%
23+
%
24+
% logFile:
725
% When you want to save your data logFile contains the data you want to save.
826
% The logFile variable that contains the n events you want to % save must be a nx1 structure.
927
% Each field will be saved in a separate column.
@@ -27,6 +45,7 @@
2745
% into this file.
2846
% This creates the header with the obligatory 'onset', 'trial_type', 'duration' required bt BIDS and other
2947
% coluns can be specified in varargin.
48+
%
3049
% example : logFile = saveEventsFile('open', expParameters, [], 'direction', 'speed', 'target');
3150
%
3251
% - 'save': will save the data contained in logfile by using the file ID logFile.fileID;

0 commit comments

Comments
 (0)