Skip to content

Commit 8fd9a97

Browse files
Remi-GauRemi-Gau
committed
refactor README
1 parent 6109ffc commit 8fd9a97

File tree

2 files changed

+146
-115
lines changed

2 files changed

+146
-115
lines changed

‎README.md‎

Lines changed: 35 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,23 @@
1-
# CPP_PTB
1+
<!-- vscode-markdown-toc -->
2+
* 1. [Requirements](#Requirements)
3+
* 2. [Code guidestyle](#Codeguidestyle)
4+
* 3. [How to install](#Howtoinstall)
5+
* 3.1. [Download with git](#Downloadwithgit)
6+
* 3.2. [Add as a submodule](#Addasasubmodule)
7+
* 3.2.1. [Example for submodule usage](#Exampleforsubmoduleusage)
8+
* 3.3. [Direct download](#Directdownload)
9+
* 4. [Setting up keyboards](#Settingupkeyboards)
10+
* 5. [Structure](#Structure)
11+
* 6. [Annexes](#Annexes)
12+
* 6.1. [Experiment template [ WIP ]](#ExperimenttemplateWIP)
13+
* 6.2. [devSandbox (stand-alone)](#devSandboxstand-alone)
14+
* 7. [Contributors ✨](#Contributors)
15+
16+
<!-- vscode-markdown-toc-config
17+
numbering=true
18+
autoSave=true
19+
/vscode-markdown-toc-config -->
20+
<!-- /vscode-markdown-toc --># CPP_PTB
221

322
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
423
[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
@@ -9,7 +28,7 @@ This is List of Crossmodal Perception and Plasticity lab (CPP) PsychToolBox (PTB
928
Those functions are mostly wrappers around some PTB functions to facilitate their use and to have a codebase to facilitate their reuse.
1029

1130

12-
## Requirements
31+
## 1. <a name='Requirements'></a>Requirements
1332

1433
Make sure that the following toolboxes are installed and added to the matlab / octave path.
1534

@@ -18,13 +37,13 @@ For instructions see the following links:
1837
| Requirements | Used version |
1938
|----------------------------------------------------------|--------------|
2039
| [PsychToolBox](http://psychtoolbox.org/) Duuuuhh | >=3.0.14 |
21-
| [Matlab](https://www.mathworks.com/products/matlab.html) | 201?? |
40+
| [Matlab](https://www.mathworks.com/products/matlab.html) | >=2015b |
2241
| or [octave](https://www.gnu.org/software/octave/) | 4.? |
2342

2443
The exact version required for this to work but it is known to work with:
25-
- matlab 2017a or octave 4.2.2 and PTB 3.0.16.
44+
- matlab 2015b or octave 4.2.2 and PTB 3.0.14.
2645

27-
## Code guidestyle
46+
## 2. <a name='Codeguidestyle'></a>Code guidestyle
2847

2948
We use the `camelCase` to more easily differentiates our functions from the ones from PTB that use a `PascalCase`.
3049
We use the following regular expression for function names: `[a-z]+(([A-Z]|[0-9]){1}[a-z]+)*`.
@@ -33,9 +52,9 @@ We keep the McCabe complexity as reported by the [check_my_code function](https:
3352

3453
We use the [MISS_HIT linter](https://florianschanda.github.io/miss_hit/style_checker.html) to automatically fix some linting issues.
3554

36-
## How to install
55+
## 3. <a name='Howtoinstall'></a>How to install
3756

38-
### Download with git
57+
### 3.1. <a name='Downloadwithgit'></a>Download with git
3958

4059
``` bash
4160
cd fullpath_to_directory_where_to_install
@@ -59,7 +78,7 @@ To work with a specific version, create a branch at a specific version tag numbe
5978
git checkout -b version1 v0.0.1
6079
```
6180

62-
### Add as a submodule
81+
### 3.2. <a name='Addasasubmodule'></a>Add as a submodule
6382

6483
Add it as a submodule in the repo you are working on.
6584

@@ -81,7 +100,7 @@ git submodule update --remote --merge
81100

82101
Remember that updates to submodules need to be committed as well.
83102

84-
#### Example for submodule usage
103+
#### 3.2.1. <a name='Exampleforsubmoduleusage'></a>Example for submodule usage
85104

86105
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 my experiment repo):
87106
``` bash
@@ -104,12 +123,8 @@ git submodule update
104123
git submodule foreach --recursive 'git submodule init'
105124
git submodule foreach --recursive 'git submodule update'
106125
```
107-
**TO DO**
108-
<!-- Submodules
109-
pros: in principle, downloading the experiment you have the whole package plus the benefit to stay updated and use version control of this dependency. Can probably handle a use case in which one uses different version on different projects (e.g. older and newer projects).
110-
cons: for pro users and not super clear how to use it at the moment. -->
111126

112-
### Direct download
127+
### 3.3. <a name='Directdownload'></a>Direct download
113128

114129
Download the code. Unzip. And add to the matlab path.
115130

@@ -121,12 +136,7 @@ Or take the latest commit (NOT RECOMMENDED):
121136

122137
https://github.com/cpp-lln-lab/CPP_PTB/archive/master.zip
123138

124-
**TO DO**
125-
<!-- Download a specific version and c/p it in a subfun folder
126-
pros: the easiest solution to share the code and 'installing' it on the stimulation computer (usually not the one used to develop the code).
127-
cons: extreme solution useful only at the very latest stage (i.e. one minute before acquiring your data); prone to be customized/modified (is it what we want?) -->
128-
129-
## Setting up keyboards
139+
## 4. <a name='Settingupkeyboards'></a>Setting up keyboards
130140

131141
To select a specific keyboard to be used by the experimenter or the participant, you need to know
132142
the value assigned by PTB to each keyboard device.
@@ -151,7 +161,7 @@ press the keys necessary to start or abort the experiment.
151161

152162
Using empty vectors (ie `[]`) or a negative value for those means that you will let PTB find and use the default device.
153163

154-
## Structure
164+
## 5. <a name='Structure'></a>Structure
155165

156166
```matlab
157167
@@ -209,101 +219,11 @@ cfg.mri.triggerNb
209219
cfg.mri.triggerKey
210220
```
211221

212-
## function details
213-
214-
215-
### initPTB
216-
217-
This will initialize PsychToolBox
218-
219-
- screen
220-
- the windon opened takes the whole screen by default
221-
- set in debug mode with window transparency if necessary
222-
- can skip synch test if you ask for it (nicely)
223-
- gets the flip interval
224-
- computes the pixel per degree of visual angle
225-
- set font details
226-
- keyboard
227-
- sound
228-
229-
### testKeyboards
230-
231-
Checks that the keyboards asked for properly connected.
232-
233-
If no key is pressed on the correct keyboard after the timeOut time this exits with an error.
234-
235-
### cleanUp
236-
237-
A wrapper function to close all windows, ports, show mouse cursor, close keyboard queues
238-
and give access back to the keyboards.
239-
240-
### getExperimentStart
241-
242-
Wrapper function that will show a fixation cross and collect a start timestamp in `cfg.experimentStart`
243-
244-
### getExperimentEnd
245-
246-
Wrapper function that will show a fixation cross and display in the console the whole experiment's duration in minutes and seconds
247-
248-
### getResponse
249-
250-
It is wrapper function to use `KbQueue` which is definitely what you should use to collect responses.
251-
252-
You can easily collect responses while running some other code at the same time.
253-
254-
It will only take responses from one device which can simply be the "main keyboard"
255-
(the default device that PTB will find) or another keyboard connected to the computer
256-
or the response box that the participant is using.
257-
258-
You can use it in a way so that it only takes responses from certain keys and ignore others (like
259-
the triggers from an MRI scanner).
260-
261-
If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`.
262-
263-
In brief, there are several actions you can execute with this function.
264-
265-
- init: initialize the buffer for key presses on a given device (you can also specify the keys of interest that should be listened to).
266-
- start: start listening to the key presses (carefully insert into your script - where do you want to start buffering the responses).
267-
- check: till that point, it will check the buffer for all key presses.
268-
- It only reports presses on the keys of interest mentioned at initialization.
269-
- It **can** also check for presses on the escape key and abort if the escape key is part of the keys of interest.
270-
- flush: Empties the buffer of key presses in case you want to discard any previous key presses.
271-
- stop: Stops buffering key presses. You can still restart by calling "start" again.
272-
- release: Closes the buffer for good.
273-
274-
### deg2Pix
275-
276-
For a given field value in degrees of visual angle in the input `structure`,
277-
this computes its value in pixel using the pixel per degree value of the `cfg` structure
278-
and returns a structure with an additional field with Pix suffix holding that new value.
279-
280-
### drawFixationCross
281-
282-
Define the parameters of the fixation cross in `cfg` and `expParameters` and this does the rest.
283-
284-
### eyeTracker
285-
286-
This will handle the Eye Tracker (EyeLink set up) and can be called to initialize the connection and start the calibration, start/stop eye(s) movement recordings and save the `*.edf` file (named with BIDS specification from cpp-lln-lab/CPP_BIDS).
287-
288-
### pressSpace4me
289-
290-
Use that to stop your script and only restart when the space bar is pressed.
291-
292-
### standByScreen
293-
294-
It shows a basic one-page instruction stored in `cfg.task.instruction` and wait for `space` stroke.
295-
296-
### waitForTrigger
297-
298-
Counts a certain number of triggers coming from the mri/scanner before returning.
299-
Requires number of triggers to wait for.
300-
301-
302-
## Annexes
222+
## 6. <a name='Annexes'></a>Annexes
303223

304-
### Experiment template [ WIP ]
224+
### 6.1. <a name='ExperimenttemplateWIP'></a>Experiment template [ WIP ]
305225

306-
### devSandbox (stand-alone)
226+
### 6.2. <a name='devSandboxstand-alone'></a>devSandbox (stand-alone)
307227

308228
This script is a stand-alone function that can be useful as a sandbox to develop the PTB audio/visual stimulation of your experiment. No input/output required.
309229

@@ -317,7 +237,7 @@ It is composed of two parts:
317237

318238
When you are happy with it, ideally you will move the vars in `setParameters.m` and the stimulation code in a separate function in `my-experiment-folder/subfun`. The code style and variable names are the same used in `cpp-lln-lab/CPP_PTB` github repo, therefore it should be easy to move everything in your experiment scripts (see the template that is annexed in `cpp-lln-lab/CPP_PTB`).
319239

320-
## Contributors ✨
240+
## 7. <a name='Contributors'></a>Contributors ✨
321241

322242
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
323243

‎docs/functions_description.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<!-- vscode-markdown-toc -->
2+
* 1. [function details](#functiondetails)
3+
* 1.1. [initPTB](#initPTB)
4+
* 1.2. [testKeyboards](#testKeyboards)
5+
* 1.3. [cleanUp](#cleanUp)
6+
* 1.4. [getExperimentStart](#getExperimentStart)
7+
* 1.5. [getExperimentEnd](#getExperimentEnd)
8+
* 1.6. [getResponse](#getResponse)
9+
* 1.7. [deg2Pix](#deg2Pix)
10+
* 1.8. [drawFixationCross](#drawFixationCross)
11+
* 1.9. [eyeTracker](#eyeTracker)
12+
* 1.10. [pressSpace4me](#pressSpace4me)
13+
* 1.11. [standByScreen](#standByScreen)
14+
* 1.12. [waitForTrigger](#waitForTrigger)
15+
16+
<!-- vscode-markdown-toc-config
17+
numbering=true
18+
autoSave=true
19+
/vscode-markdown-toc-config -->
20+
<!-- /vscode-markdown-toc --># functions description
21+
22+
23+
24+
## 1. <a name='functiondetails'></a>function details
25+
26+
27+
### 1.1. <a name='initPTB'></a>initPTB
28+
29+
This will initialize PsychToolBox
30+
31+
- screen
32+
- the windon opened takes the whole screen by default
33+
- set in debug mode with window transparency if necessary
34+
- can skip synch test if you ask for it (nicely)
35+
- gets the flip interval
36+
- computes the pixel per degree of visual angle
37+
- set font details
38+
- keyboard
39+
- sound
40+
41+
### 1.2. <a name='testKeyboards'></a>testKeyboards
42+
43+
Checks that the keyboards asked for properly connected.
44+
45+
If no key is pressed on the correct keyboard after the timeOut time this exits with an error.
46+
47+
### 1.3. <a name='cleanUp'></a>cleanUp
48+
49+
A wrapper function to close all windows, ports, show mouse cursor, close keyboard queues
50+
and give access back to the keyboards.
51+
52+
### 1.4. <a name='getExperimentStart'></a>getExperimentStart
53+
54+
Wrapper function that will show a fixation cross and collect a start timestamp in `cfg.experimentStart`
55+
56+
### 1.5. <a name='getExperimentEnd'></a>getExperimentEnd
57+
58+
Wrapper function that will show a fixation cross and display in the console the whole experiment's duration in minutes and seconds
59+
60+
### 1.6. <a name='getResponse'></a>getResponse
61+
62+
It is wrapper function to use `KbQueue` which is definitely what you should use to collect responses.
63+
64+
You can easily collect responses while running some other code at the same time.
65+
66+
It will only take responses from one device which can simply be the "main keyboard"
67+
(the default device that PTB will find) or another keyboard connected to the computer
68+
or the response box that the participant is using.
69+
70+
You can use it in a way so that it only takes responses from certain keys and ignore others (like
71+
the triggers from an MRI scanner).
72+
73+
If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`.
74+
75+
In brief, there are several actions you can execute with this function.
76+
77+
- init: initialize the buffer for key presses on a given device (you can also specify the keys of interest that should be listened to).
78+
- start: start listening to the key presses (carefully insert into your script - where do you want to start buffering the responses).
79+
- check: till that point, it will check the buffer for all key presses.
80+
- It only reports presses on the keys of interest mentioned at initialization.
81+
- It **can** also check for presses on the escape key and abort if the escape key is part of the keys of interest.
82+
- flush: Empties the buffer of key presses in case you want to discard any previous key presses.
83+
- stop: Stops buffering key presses. You can still restart by calling "start" again.
84+
- release: Closes the buffer for good.
85+
86+
### 1.7. <a name='deg2Pix'></a>deg2Pix
87+
88+
For a given field value in degrees of visual angle in the input `structure`,
89+
this computes its value in pixel using the pixel per degree value of the `cfg` structure
90+
and returns a structure with an additional field with Pix suffix holding that new value.
91+
92+
### 1.8. <a name='drawFixationCross'></a>drawFixationCross
93+
94+
Define the parameters of the fixation cross in `cfg` and `expParameters` and this does the rest.
95+
96+
### 1.9. <a name='eyeTracker'></a>eyeTracker
97+
98+
This will handle the Eye Tracker (EyeLink set up) and can be called to initialize the connection and start the calibration, start/stop eye(s) movement recordings and save the `*.edf` file (named with BIDS specification from cpp-lln-lab/CPP_BIDS).
99+
100+
### 1.10. <a name='pressSpace4me'></a>pressSpace4me
101+
102+
Use that to stop your script and only restart when the space bar is pressed.
103+
104+
### 1.11. <a name='standByScreen'></a>standByScreen
105+
106+
It shows a basic one-page instruction stored in `cfg.task.instruction` and wait for `space` stroke.
107+
108+
### 1.12. <a name='waitForTrigger'></a>waitForTrigger
109+
110+
Counts a certain number of triggers coming from the mri/scanner before returning.
111+
Requires number of triggers to wait for.

0 commit comments

Comments
 (0)