Skip to content

Commit 47b29b6

Browse files
Remi-GauRemi-Gau
authored
Merge pull request #15 from Remi-Gau/remi-doc
improve doc
2 parents 76ed6e7 + 9b1948e commit 47b29b6

11 files changed

+248
-93
lines changed

‎.gitignore

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
*DS_Store
2+
3+
*.m~
4+
*octave-workspace
5+
6+
# exclude content of logfiles folders
7+
*.tsv
8+
*.mat

‎CPP_getResponseDemo.m

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
jk%% Demo showing how to use the getResponse function
1+
%% Demo showing how to use the getResponse function
22

3-
% This small script shows how to use the getReponse function
3+
% This small script shows how to use the getReponse function
44
% (a wrapper around the KbQueue function from PTB)
55

66
% start with a clean slate
7-
clear; clc;
7+
clear; clc;
88
if IsOctave
99
more off % for a better display experience
1010
end
1111

1212
%% set parameters
1313

14-
% cfg.responseBox would be the device number of the device used by the participant to give his/her
14+
% cfg.responseBox would be the device number of the device used by the participant to give his/her
1515
% response: like the button box in the scanner or a separate keyboard for a behavioral experiment
1616
%
17-
% cfg.keyboard would be the device number of the keyboard on which the experimenter will type or
17+
% cfg.keyboard would be the device number of the keyboard on which the experimenter will type or
1818
% press the keys necessary to start or abort the experiment.
1919

2020
% cfg.responseBox and cfg.keyboard can be different or the same.
@@ -57,10 +57,10 @@
5757

5858
fprintf('\nDuring the next 5 seconds we will collect responses on the following keys: \n\n');
5959
if isempty(expParameters.responseKey)
60-
fprintf('\nALL KEYS\n\n');
60+
fprintf('\nALL KEYS\n\n');
6161
else
6262
for iKey=1:numel(expParameters.responseKey)
63-
fprintf('\n%s', expParameters.responseKey{iKey});
63+
fprintf('\n%s', expParameters.responseKey{iKey});
6464
end
6565
fprintf('\n\n');
6666
end

‎README.md

Lines changed: 101 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# CPP_PTB
2+
23
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
4+
35
[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
6+
47
<!-- ALL-CONTRIBUTORS-BADGE:END -->
58

69
This is List of Crossmodal Perpeption and Plasticity lab (CPP) PsychToolBox (PTB) toolbox.
@@ -16,7 +19,7 @@ For instructions see the following links:
1619

1720
| Requirements | Used version |
1821
|----------------------------------------------------------|--------------|
19-
| [PsychToolBox](http://psychtoolbox.org/) Duuuuhh | >3.0.13 |
22+
| [PsychToolBox](http://psychtoolbox.org/) Duuuuhh | >=3.0.14 |
2023
| [Matlab](https://www.mathworks.com/products/matlab.html) | 201?? |
2124
| or [octave](https://www.gnu.org/software/octave/) | 4.? |
2225

@@ -27,42 +30,126 @@ The exact version required for this to work but it is known to work with:
2730

2831
We use the `camelCase` to more easily differentiates our functions from the ones from PTB that use a `PascalCase`.
2932

33+
We keep the McCabe complexity as reported by the [check_my_code function](https://github.com/Remi-Gau/matlab_checkcode) below 15.
34+
35+
## How to install
36+
37+
### Use the matlab package manager
38+
39+
This repository can be added as a dependencies by listing it in a [mpm-requirements.txt file](.mpm-requirements.txt)
40+
as follows:
41+
42+
CPP_PTB -u https://github.com/cpp-lln-lab/CPP_PTB.git
43+
44+
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.
45+
46+
```matlab
47+
function getDependencies(action)
48+
% Will install on your computer the matlab dependencies specified in the mpm-requirements.txt
49+
% and add them to the matlab path. The path is never saved so you need to run getDependencies() when
50+
% you start matlab.
51+
%
52+
% getDependencies('update') will force the update and overwrite previous version of the dependencies.
53+
%
54+
% getDependencies() If you only already have the appropriate version but just want to add them to the matlab path.
55+
56+
experimentName = YOUR_EXPERIMENT_NAME;
57+
58+
if nargin<1
59+
action = '';
60+
end
61+
62+
switch action
63+
case 'update'
64+
% install dependencies
65+
mpm install -i mpm-requirements.txt -f -c YOUR_EXPERIMENT_NAME
66+
end
67+
68+
% adds them to the path
69+
mpm_folder = fileparts(which('mpm'));
70+
addpath(genpath(fullfile(mpm_folder, 'mpm-packages', 'mpm-collections', experimentName)));
71+
72+
end
73+
```
74+
75+
3076
## Structure and function details
3177

32-
### setParameters
78+
<!-- ### setParameters -->
3379

3480
### initPTB
3581

82+
This will initialize PsychToolBox
83+
84+
- screen
85+
- the windon opened takes the whole screen by default
86+
- set in debug mode with window transparency if necessary
87+
- can skip synch test if you ask for it (nicely)
88+
- gets the flip interval
89+
- computes the pixel per degree of visual angle
90+
- set font details
91+
- keyboard
92+
- sound
93+
94+
### testKeyboards
95+
96+
Checks that the keyboards asked for properly connected.
97+
98+
If no key is pressed on the correct keyboard after the timeOut time this exits with an error.
99+
100+
### cleanUp
101+
102+
A wrapper function to close all windows, ports, show mouse cursor, close keyboard queues
103+
and give access back to the keyboards.
104+
36105
### getResponse
37-
It is wrapper function to use KbQueue which is definitely what you should used to collect responses.
106+
107+
It is wrapper function to use `KbQueue` which is definitely what you should used to collect responses.
38108

39109
You can easily collect responses while running some other code at the same time.
40110

41-
It will only take responses from the `response box` which can simply be the "main keyboard" or another keyboard connected to the computer or the response box that the participant is using.
111+
It will only take responses from the `response box` which can simply be the "main keyboard" or
112+
another keyboard connected to the computer or the response box that the participant is using.
42113

43-
You can use it in a way so that it only takes responses from certain keys.
114+
You can use it in a way so that it only takes responses from certain keys and ignore others (like
115+
the triggers from an MRI scanner).
44116

45117
If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`.
46118

47-
To select a specific keyboard to be used by experimenter/participant, you need to know the assigned MATLAB value. To copy-paste this on the command wuindow:
119+
To select a specific keyboard to be used by the experimenter or the participant, you need to know
120+
the value assigned by PTB to each keyboard device.
48121

49-
```
50-
[keyboardNumbers, keyboardNames] = GetKeyboardIndices;
122+
To know this copy-paste this on the command window:
51123

52-
keyboardNumbers
53-
keyboardNames
54-
```
124+
[keyboardNumbers, keyboardNames] = GetKeyboardIndices;
55125

126+
keyboardNumbers
127+
keyboardNames
56128

57-
### cleanUp
129+
### deg2Pix
130+
131+
For a given field value in degrees of visual angle in the input `structure`,
132+
this computes its value in pixel using the pixel per degree value of the `cfg` structure
133+
and returns a structure with an additional field with Pix suffix holding that new value.
134+
135+
### drawFixationCross
136+
137+
Define the parameters of the fixation cross in `cfg` and `expParameters` and this does the rest.
138+
139+
### pressSpace4me
140+
141+
Use that to stop your script and only restart when the space bar is pressed.
58142

59143
## Contributors ✨
60144

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

63147
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
148+
64149
<!-- prettier-ignore-start -->
150+
65151
<!-- markdownlint-disable -->
152+
66153
<table>
67154
<tr>
68155
<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_PTB/commits?author=Remi-Gau" title="Code">💻</a> <a href="#design-Remi-Gau" title="Design">🎨</a> <a href="https://github.com/cpp-lln-lab/CPP_PTB/commits?author=Remi-Gau" title="Documentation">📖</a></td>
@@ -71,7 +158,9 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
71158
</table>
72159

73160
<!-- markdownlint-enable -->
161+
74162
<!-- prettier-ignore-end -->
163+
75164
<!-- ALL-CONTRIBUTORS-LIST:END -->
76165

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

‎checkDependencies.m

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,41 @@ function checkDependencies()
33

44
printCredits()
55

6-
7-
PTB = '3.0.16';
6+
PTB.major = 3;
7+
PTB.minor = 0;
8+
PTB.point = 14;
89

910
fprintf('Checking dependencies\n')
1011

1112
% check ptb version
1213
try
13-
a = PsychtoolboxVersion
14-
fprintf(' Using %s %s\n', a, b)
15-
if any(~strcmp(a, PTB))
16-
str = sprintf('%s %s %s.\n%s', ...
17-
'The current version PTB version is not', PTB,...
18-
'In case of problems (e.g json file related) consider updating.');
19-
warning(str); %#ok<*SPWRN>
20-
end
14+
15+
[~, versionStruc] = PsychtoolboxVersion;
16+
17+
fprintf(' Using PTB %i.%i.%i\n', ...
18+
versionStruc.major, ...
19+
versionStruc.minor, ...
20+
versionStruc.point)
21+
22+
if any( [...
23+
versionStruc.major < PTB.major, ...
24+
versionStruc.minor < PTB.minor, ...
25+
versionStruc.point < PTB.point, ...
26+
])
27+
28+
str = sprintf('%s %i.%i.%i %s.\n%s', ...
29+
'The current version PTB version is not', ...
30+
PTB.major, ...
31+
PTB.minor, ...
32+
PTB.point, ...
33+
'In case of problems (e.g json file related) consider updating.');
34+
warning(str); %#ok<*SPWRN>
35+
end
2136
catch
2237
error('Failed to check the PTB version: Are you sure that PTB is in the matlab path?')
2338
end
2439

2540

26-
fprintf(' We got all we need. Let''s get to work.\n')
41+
fprintf(' We got all we need. Let us get to work.\n')
2742

2843
end

‎cleanUp.m

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
function cleanUp
2+
% A wrapper function to close all windows, ports, show mouse cursor, close keyboard queues
3+
% and give access back to the keyboards.
24

35
WaitSecs(0.5);
46

@@ -24,5 +26,5 @@
2426

2527
close all
2628

27-
29+
2830
end

‎deg2Pix.m

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
1-
function structure = deg2Pix(fieldName, structure, Cfg)
1+
function structure = deg2Pix(fieldName, structure, cfg)
2+
% For a given field value in degrees of visual angle in the structure,
3+
% this computes its value in pixel using the pixel per degree value of the cfg structure
4+
% and returns a structure with an additional field with Pix suffix holding that new value.
25

36
deg = getfield( structure, fieldName);
47

58
structure = setfield( structure, [fieldName 'Pix'], ...
6-
floor(Cfg.ppd * deg) ) ;
9+
floor(cfg.ppd * deg) ) ;
710

8-
end
11+
end

‎drawFixationCross.m

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
function drawFixationCross(Cfg, ExpParameters, color)
1+
function drawFixationCross(cfg, expParameters, color)
2+
% Define the parameters of the fixation cross in `cfg` and `expParameters` and this does the rest.
23

34
Screen('DrawLines', ...
4-
Cfg.win, ...
5-
Cfg.allCoords, ...
6-
ExpParameters.lineWidthPix, ...
5+
cfg.win, ...
6+
cfg.allCoords, ...
7+
expParameters.lineWidthPix, ...
78
color , ...
8-
[Cfg.center(1) Cfg.center(2)], 1);
9+
[cfg.center(1) cfg.center(2)], 1);
910

10-
end
11+
end

0 commit comments

Comments
 (0)