Skip to content

Commit a1f18ab

Browse files
Remi-GauRemi-Gau
authored
Merge pull request #52 from Remi-Gau/update_readme
[DOC] update README
2 parents edc8d57 + 46a1e01 commit a1f18ab

File tree

7 files changed

+122
-113
lines changed

7 files changed

+122
-113
lines changed

‎README.md‎

Lines changed: 35 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,43 @@
11
[![](https://img.shields.io/badge/Octave-CI-blue?logo=Octave&logoColor=white)](https://github.com/cpp-lln-lab/localizer_auditory_motion/actions)
2+
23
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
4+
35
[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
6+
47
<!-- ALL-CONTRIBUTORS-BADGE:END -->
5-
![](https://github.com/cpp-lln-lab/localizer_auditory_motion/workflows/CI/badge.svg)
68

9+
![](https://github.com/cpp-lln-lab/localizer_auditory_motion/workflows/CI/badge.svg)
710
[![codecov](https://codecov.io/gh/cpp-lln-lab/localizer_auditory_motion/branch/master/graph/badge.svg)](https://codecov.io/gh/cpp-lln-lab/localizer_auditory_motion)
8-
911
[![Build Status](https://travis-ci.com/cpp-lln-lab/localizer_auditory_motion.svg?branch=master)](https://travis-ci.com/cpp-lln-lab/localizer_auditory_motion)
1012

11-
1213
# Auditory Translational Motion
1314

14-
<!-- vscode-markdown-toc -->
15+
- [Auditory Translational Motion](#auditory-translational-motion)
16+
- [`audioLocTranslational`](#audioloctranslational)
17+
- [`setParameters`](#setparameters)
18+
- [Requirements](#requirements)
19+
- [Installation](#installation)
20+
- [Contributors ✨](#contributors-)
21+
22+
## `audioLocTranslational`
23+
24+
Running this script will play blocks of motion/static sounds. Motion blocks will
25+
play sounds moving in one of four directions (up-, down-, left-, and right-ward)
26+
27+
By default it is run in `Debug mode` meaning that it does not care about subjID,
28+
run n., fMRI triggers, Eye Tracker, etc..
1529

16-
- 1. [Requirements](#Requirements)
17-
- 2. [Installation](#Installation)
18-
- 3. [Structure and function details](#Structureandfunctiondetails)
19-
_ 3.1. [audioLocTranslational](#audioLocTranslational)
20-
_ 3.2. [setParameters](#setParameters)
21-
_ 3.3. [subfun/expDesign](#subfunexpDesign)
22-
_ 3.3.1. [EVENTS](#EVENTS)
23-
_ 3.3.2. [TARGETS:](#TARGETS:)
24-
_ 3.3.3. [Input:](#Input:)
25-
_ 3.3.4. [Output:](#Output:)
26-
_ 3.4. [subfun/eyeTracker](#subfuneyeTracker) \* 3.5. [subfun/wait4Trigger](#subfunwait4Trigger)
30+
Any details of the experiment can be changed in `setParameters.m` (e.g.,
31+
experiment mode, motion stimuli details, exp. design, etc.)
2732

28-
<!-- vscode-markdown-toc-config
29-
numbering=true
30-
autoSave=true
31-
/vscode-markdown-toc-config -->
32-
<!-- /vscode-markdown-toc -->
33+
### `setParameters`
3334

34-
## 1. <a name='Requirements'></a>Requirements
35+
`setParameters.m` is the core engine of the experiment. See [docs/configuration](.docs/../docs/configuration.md) for more information.
3536

36-
Make sure that the following toolboxes are installed and added to the matlab / octave path.
37+
## Requirements
38+
39+
Make sure that the following toolboxes are installed and added to the matlab /
40+
octave path.
3741

3842
For instructions see the following links:
3943

@@ -43,99 +47,21 @@ For instructions see the following links:
4347
| [Matlab](https://www.mathworks.com/products/matlab.html) | >=2017b |
4448
| or [octave](https://www.gnu.org/software/octave/) | >=4.? |
4549

46-
## 2. <a name='Installation'></a>Installation
50+
## Installation
4751

48-
The CPP_BIDS and CPP_PTB dependencies are already set up as submodule to this repository.
49-
You can install it all with git by doing.
52+
The CPP_BIDS and CPP_PTB dependencies are already set up as submodule to this
53+
repository. You can install it all with git by doing.
5054

5155
```bash
5256
git clone --recurse-submodules https://github.com/cpp-lln-lab/localizer_auditory_motion.git
5357
```
5458

55-
## 3. <a name='Structureandfunctiondetails'></a>Structure and function details
56-
57-
### 3.1. <a name='audioLocTranslational'></a>audioLocTranslational
58-
59-
Running this script will play blocks of motion/static sounds. Motion blocks will play sounds moving in one of four directions (up-, down-, left-, and right-ward)
60-
61-
By default it is run in `Debug mode` meaning that it does not care about subjID, run n., fMRI triggers, Eye Tracker, etc..
62-
63-
Any details of the experiment can be changed in `setParameters.m` (e.g., experiment mode, motion stimuli details, exp. design, etc.)
64-
65-
### 3.2. <a name='setParameters'></a>setParameters
66-
67-
`setParameters.m` is the core engine of the experiment. It contains the following tweakable sections:
68-
69-
- Debug mode setting
70-
- Engine parameters:
71-
- Devices parameters
72-
- Monitor parameters
73-
- Keyboard parameters
74-
- MRI parameters
75-
- Experiment Design
76-
- Timing
77-
- Auditory Stimulation
78-
- Task(s)
79-
- Instructions
80-
- Task #1 parameters
81-
82-
#### Let the scanner pace the experiment
83-
84-
Set `cfg.pacedByTriggers.do` to `true` and you can then set all the details in this `if` block
85-
86-
```matlab
87-
% Time is here in in terms of number repetition time (i.e MRI volumes)
88-
if cfg.pacedByTriggers.do
89-
90-
cfg.pacedByTriggers.quietMode = true;
91-
cfg.pacedByTriggers.nbTriggers = 1;
92-
93-
cfg.timing.eventDuration = cfg.mri.repetitionTime / 2 - 0.04; % second
94-
95-
% Time between blocs in secs
96-
cfg.timing.IBI = 0;
97-
% Time between events in secs
98-
cfg.timing.ISI = 0;
99-
% Number of seconds before the motion stimuli are presented
100-
cfg.timing.onsetDelay = 0;
101-
% Number of seconds after the end all the stimuli before ending the run
102-
cfg.timing.endDelay = 2;
103-
104-
end
105-
```
106-
107-
### 3.3. <a name='subfunexpDesign'></a>subfun/expDesign
108-
109-
Creates the sequence of blocks and the events in them. The conditions are consecutive static and motion blocks (Gives better results than randomised). It can be run as a stand alone without inputs to display a visual example of a possible design.
110-
111-
#### 3.3.1. <a name='EVENTS'></a>EVENTS
112-
113-
The `numEventsPerBlock` should be a multiple of the number of "base" listed in the `motionDirections` and `staticDirections` (4 at the moment).
114-
115-
#### 3.3.2. <a name='TARGETS:'></a>TARGETS:
116-
117-
- If there are 2 targets per block we make sure that they are at least 2 events apart.
118-
- Targets cannot be on the first or last event of a block
119-
120-
#### 3.3.3. <a name='Input:'></a>Input:
121-
122-
- `expParameters`: parameters returned by `setParameters`
123-
- `displayFigs`: a boolean to decide whether to show the basic design matrix of the design
124-
125-
#### 3.3.4. <a name='Output:'></a>Output:
126-
127-
- `expParameters.designBlockNames` is a cell array `(nr_blocks, 1)` with the name for each block
128-
- `expParameters.designDirections` is an array `(nr_blocks, numEventsPerBlock)` with the direction to present in a given block
129-
- `0 90 180 270` indicate the angle
130-
- `-1` indicates static
131-
- `expParameters.designSpeeds` is an array `(nr_blocks, numEventsPerBlock) * speedEvent`
132-
- `expParameters.designFixationTargets` is an array `(nr_blocks, numEventsPerBlock)` showing for each event if it should be accompanied by a target
133-
13459

13560

13661
## Contributors ✨
13762

138-
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
63+
Thanks goes to these wonderful people
64+
([emoji key](https://allcontributors.org/docs/en/emoji-key)):
13965

14066
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
14167
<!-- prettier-ignore-start -->
@@ -150,6 +76,9 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
15076

15177
<!-- markdownlint-enable -->
15278
<!-- prettier-ignore-end -->
79+
15380
<!-- ALL-CONTRIBUTORS-LIST:END -->
15481

155-
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
82+
This project follows the
83+
[all-contributors](https://github.com/all-contributors/all-contributors)
84+
specification. Contributions of any kind welcome!

‎audioLocTranslational.m‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,8 +90,7 @@
9090

9191
% we wait for a trigger every 2 events
9292
if cfg.pacedByTriggers.do && mod(iEvent, 2) == 1
93-
waitForTrigger( ...
94-
cfg, ...
93+
waitForTrigger(cfg, ...
9594
cfg.keyboard.responseBox, ...
9695
cfg.pacedByTriggers.quietMode, ...
9796
cfg.pacedByTriggers.nbTriggers);

‎docs/configuration.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
## Structure and function details
2+
3+
`setParameters.m` is the core engine of the experiment. It contains the
4+
following tweakable sections. See
5+
[docs/configuration](.docs/../docs/configuration.md) for more information.
6+
7+
- Debug mode setting
8+
- Engine parameters:
9+
- Devices parameters
10+
- Monitor parameters
11+
- Keyboard parameters
12+
- MRI parameters
13+
- Experiment Design
14+
- Timing
15+
- Auditory Stimulation
16+
- Task(s)
17+
- Instructions
18+
- Task #1 parameters
19+
20+
#### Let the scanner pace the experiment
21+
22+
Set `cfg.pacedByTriggers.do` to `true` and you can then set all the details in
23+
this `if` block
24+
25+
```matlab
26+
% Time is here in in terms of number repetition time (i.e MRI volumes)
27+
if cfg.pacedByTriggers.do
28+
29+
cfg.pacedByTriggers.quietMode = true;
30+
cfg.pacedByTriggers.nbTriggers = 1;
31+
32+
cfg.timing.eventDuration = cfg.mri.repetitionTime / 2 - 0.04; % second
33+
34+
% Time between blocs in secs
35+
cfg.timing.IBI = 0;
36+
% Time between events in secs
37+
cfg.timing.ISI = 0;
38+
% Number of seconds before the motion stimuli are presented
39+
cfg.timing.onsetDelay = 0;
40+
% Number of seconds after the end all the stimuli before ending the run
41+
cfg.timing.endDelay = 2;
42+
43+
end
44+
```
45+
46+
### subfun/expDesign
47+
48+
Creates the sequence of blocks and the events in them. The conditions are
49+
consecutive static and motion blocks (Gives better results than randomised). It
50+
can be run as a stand alone without inputs to display a visual example of a
51+
possible design.
52+
53+
#### EVENTS
54+
55+
The `numEventsPerBlock` should be a multiple of the number of "base" listed in
56+
the `motionDirections` and `staticDirections` (4 at the moment).
57+
58+
#### TARGETS
59+
60+
- If there are 2 targets per block we make sure that they are at least 2 events
61+
apart.
62+
- Targets cannot be on the first or last event of a block
63+
64+
#### Input
65+
66+
- `expParameters`: parameters returned by `setParameters`
67+
- `displayFigs`: a boolean to decide whether to show the basic design matrix of
68+
the design
69+
70+
#### Output
71+
72+
- `expParameters.designBlockNames` is a cell array `(nr_blocks, 1)` with the
73+
name for each block
74+
- `expParameters.designDirections` is an array `(nr_blocks, numEventsPerBlock)`
75+
with the direction to present in a given block
76+
- `0 90 180 270` indicate the angle
77+
- `-1` indicates static
78+
- `expParameters.designSpeeds` is an array
79+
`(nr_blocks, numEventsPerBlock) * speedEvent`
80+
- `expParameters.designFixationTargets` is an array
81+
`(nr_blocks, numEventsPerBlock)` showing for each event if it should be
82+
accompanied by a target

‎miss_hit.cfg‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ regex_function_name: "[a-z]+(([A-Z]){1}[A-Za-z]+)*"
66
regex_script_name: "[a-z]+(([A-Z]){1}[A-Za-z]+)*"
77
regex_parameter_name: "[a-z]+(([A-Z]){1}[A-Za-z]+)*"
88
suppress_rule: "copyright_notice"
9-
exclude_dir: "lib"
9+
exclude_dir: "lib"

‎setParameters.m‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@
88
% by default the data will be stored in an output folder created where the
99
% setParamters.m file is
1010
% change that if you want the data to be saved somewhere else
11-
cfg.dir.output = fullfile( ...
12-
fileparts(mfilename('fullpath')), 'output');
11+
cfg.dir.output = fullfile(fileparts(mfilename('fullpath')), 'output');
1312

1413
%% Debug mode settings
1514

‎tests/miss_hit.cfg‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,4 @@ suppress_rule: "copyright_notice"
88
metric "cnest": limit 4
99
metric "file_length": limit 500
1010
metric "cyc": limit 15
11-
metric "parameters": limit 5
11+
metric "parameters": limit 5

‎version.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
v0.2.2
1+
v0.2.2

0 commit comments

Comments
 (0)