|
| 1 | +# CPP_PTB documentation |
| 2 | + |
| 3 | +<!-- vscode-markdown-toc --> |
| 4 | +* 1. [the CFG gtructure](#theCFGgtructure) |
| 5 | +* 2. [Setting up keyboards](#Settingupkeyboards) |
| 6 | +* 3. [functions descriptions](#functionsdescriptions) |
| 7 | +* 4. [Annexes](#Annexes) |
| 8 | + * 4.1. [Experiment template [ WIP ]](#ExperimenttemplateWIP) |
| 9 | + * 4.2. [devSandbox (stand-alone)](#devSandboxstand-alone) |
| 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='theCFGgtructure'></a>the CFG gtructure |
| 18 | + |
| 19 | +The `cfg` structure is where most of the information about your experiment will be defined. |
| 20 | + |
| 21 | +Below we try to outline what it contains. |
| 22 | + |
| 23 | +Some of those fields you can set yourself while some others will be created and filled after running `initPTB.m`. |
| 24 | + |
| 25 | +If no value is provided here, it means that there is no set default (or that the `initPTB` takes care of it). |
| 26 | + |
| 27 | +```matlab |
| 28 | +%% -------------------------------------------------------------------------- %% |
| 29 | +cfg.testingDevice = 'pc'; % could be 'mri', 'eeg', 'meg' |
| 30 | +
|
| 31 | +
|
| 32 | +%% -------------------------------------------------------------------------- %% |
| 33 | +% cfg.keyboard |
| 34 | +cfg.keyboard.keyboard = []; % device index for the main keyboard (that of the experimenter) |
| 35 | +cfg.keyboard.responseBox = []; % device index used by the participants |
| 36 | +cfg.keyboard.responseKey = {}; % list the keys that PTB should "listen" to when |
| 37 | +% using KbQueue to collect responses ; if empty PTB will listen to all key presses |
| 38 | +cfg.keyboard.escapeKey = 'ESCAPE'; % key to press to escape |
| 39 | +
|
| 40 | +
|
| 41 | +%% -------------------------------------------------------------------------- %% |
| 42 | +% cfg.debug |
| 43 | +cfg.debug.do = true; % if true this will make less PTB tolerant with bad synchronisation |
| 44 | +cfg.debug.transpWin = true; % makes the stimulus windows semi-transparent: useful when designing your experiment |
| 45 | +cfg.debug.smallWin = true; % open a small window and not a full screen window ; can be useful for debugging |
| 46 | +
|
| 47 | +%% -------------------------------------------------------------------------- %% |
| 48 | +% cfg.text |
| 49 | +cfg.text.font = 'Courier New'; |
| 50 | +cfg.text.size = 18; |
| 51 | +cfg.text.style = 1; ??? |
| 52 | +
|
| 53 | +
|
| 54 | +%% -------------------------------------------------------------------------- %% |
| 55 | +% cfg.color |
| 56 | +cfg.color.background % [r g b] each in 0-255 |
| 57 | +
|
| 58 | +
|
| 59 | +%% -------------------------------------------------------------------------- %% |
| 60 | +% cfg.screen |
| 61 | +cfg.screen.monitorWidth = 42;% in cm |
| 62 | +cfg.screen.monitorDistance = 134;% in cm |
| 63 | +
|
| 64 | +% all the following will be initialised by initPTB |
| 65 | +cfg.screen.idx % screen index |
| 66 | +cfg.screen.win % window index |
| 67 | +cfg.screen.winRect % rectangle definition of the window |
| 68 | +cfg.screen.winWidth |
| 69 | +cfg.screen.winHeight |
| 70 | +cfg.screen.center % [x y] ; pixel coordinate of the window center |
| 71 | +cfg.screen.FOV % width of the field of view in degrees of visual angle |
| 72 | +cfg.screen.ppd % pixel per degree |
| 73 | +cfg.screen.ifi % inter frame interval |
| 74 | +cfg.screen.monRefresh % monitor refresh rate ; 1 / ifi |
| 75 | +
|
| 76 | +
|
| 77 | +%% -------------------------------------------------------------------------- %% |
| 78 | +% fixation |
| 79 | +cfg.fixation.type = 'cross'; % can also be 'dot' or 'bestFixation' |
| 80 | +cfg.fixation.xDisplacement = 0; % horizontal offset from window center |
| 81 | +cfg.fixation.yDisplacement = 0; % vertical offset from window center |
| 82 | +cfg.fixation.color = [255 255 255]; |
| 83 | +cfg.fixation.width = 1; % in degrees of visual angle |
| 84 | +cfg.fixation.lineWidthPix = 5; % width of the lines in pixel |
| 85 | +
|
| 86 | +
|
| 87 | +%% -------------------------------------------------------------------------- %% |
| 88 | +% aperture |
| 89 | +% mostly relevant for retinotopy scripts but can be reused for other types of |
| 90 | +% experiments where an aperture is needed |
| 91 | +cfg.aperture.type = 'none'; % 'bar', 'wedge', 'ring', 'circle' |
| 92 | +
|
| 93 | +
|
| 94 | +%% -------------------------------------------------------------------------- %% |
| 95 | +% cfg.audio |
| 96 | +cfg.audio.do = false; % set to true if you are going to play some sounds |
| 97 | +cfg.audio.pahandle |
| 98 | +cfg.audio.devIdx = [ ]; |
| 99 | +cfg.audio.playbackMode = 1; |
| 100 | +cfg.audio.requestedLatency = 3; |
| 101 | +cfg.audio.fs 44800; % sampling frequency |
| 102 | +cfg.audio.channels = 2; % number of auditory channels |
| 103 | +cfg.audio.initVolume = 1; |
| 104 | +cfg.audio.pushSize |
| 105 | +cfg.audio.requestOffsetTime = 1; |
| 106 | +cfg.audio.reqsSampleOffset |
| 107 | +cfg.audio.repeat = 1; |
| 108 | +cfg.audio.startCue = 0; |
| 109 | +cfg.audio.waitForDevice = 1; |
| 110 | +
|
| 111 | +
|
| 112 | +%% -------------------------------------------------------------------------- %% |
| 113 | +% eyetracker |
| 114 | +cfg.eyeTracker.do = false; % set to true if you are using an eyelink eyetracker |
| 115 | +cfg.eyeTracker.defaultCalibration = true; |
| 116 | +cfg.eyeTracker.backgroundColor = [192 192 192]; |
| 117 | +cfg.eyeTracker.fontColor = [0 0 0]; |
| 118 | +cfg.eyeTracker.calibrationTargetColor = [0 0 0]; |
| 119 | +cfg.eyeTracker.calibrationTargetSize = 1; |
| 120 | +cfg.eyeTracker.calibrationTargetWidth = 0.5; |
| 121 | +cfg.eyeTracker.displayCalResults = 1; |
| 122 | +
|
| 123 | +
|
| 124 | +%% -------------------------------------------------------------------------- %% |
| 125 | +% cfg.mri |
| 126 | +cfg.mri.repetitionTime |
| 127 | +
|
| 128 | +
|
| 129 | +%% -------------------------------------------------------------------------- %% |
| 130 | +% operating system information collected by initPTB |
| 131 | +cfg.software.os |
| 132 | +cfg.software.name = 'Psychtoolbox'; |
| 133 | +cfg.software.RRID = 'SCR_002881'; |
| 134 | +cfg.software.version % psychtoolbox version |
| 135 | +cfg.software.runsOn % matlab or octave and version number |
| 136 | +``` |
| 137 | + |
| 138 | +## 2. <a name='Settingupkeyboards'></a>Setting up keyboards |
| 139 | + |
| 140 | +To select a specific keyboard to be used by the experimenter or the participant, you need to know |
| 141 | +the value assigned by PTB to each keyboard device. |
| 142 | + |
| 143 | +To know this copy-paste this on the command window: |
| 144 | + |
| 145 | +``` matlab |
| 146 | +[keyboardNumbers, keyboardNames] = GetKeyboardIndices; |
| 147 | +
|
| 148 | +disp(keyboardNumbers); |
| 149 | +disp(keyboardNames); |
| 150 | +``` |
| 151 | + |
| 152 | +You can then assign a specific device number to the main keyboard or the response box in the `cfg` structure |
| 153 | + |
| 154 | +- `cfg.keyboard.responseBox` would be the device number of the device used by the participant to give his/her |
| 155 | +response: like the button box in the scanner or a separate keyboard for a behavioral experiment |
| 156 | +- `cfg.keyboard.keyboard` would be the device number of the keyboard on which the experimenter will type or |
| 157 | +press the keys necessary to start or abort the experiment. |
| 158 | + |
| 159 | +`cfg.keyboard.responseBox` and `cfg.keyboard.keyboard` can be different or the same. |
| 160 | + |
| 161 | +Using empty vectors (ie `[]`) or a negative value for those means that you will let PTB find and use the default device. |
| 162 | + |
| 163 | +## 3. <a name='functionsdescriptions'></a>functions descriptions |
| 164 | + |
| 165 | +The main functions of the toolbox are described [here](./10_functions_descriptions.md). |
| 166 | + |
| 167 | +## 4. <a name='Annexes'></a>Annexes |
| 168 | + |
| 169 | +### 4.1. <a name='ExperimenttemplateWIP'></a>Experiment template [ WIP ] |
| 170 | + |
| 171 | +Will be moved to a different repository |
| 172 | + |
| 173 | +### 4.2. <a name='devSandboxstand-alone'></a>devSandbox (stand-alone) |
| 174 | + |
| 175 | +Will be moved to a different repository |
| 176 | + |
| 177 | +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. |
| 178 | + |
| 179 | +Here, a tutorial from https://peterscarfe.com/contrastgratingdemo.html is provided for illustrative purpose (notice that some variable names are updated to our code style). For your use, you will delete that part. |
| 180 | + |
| 181 | +It is composed of two parts: |
| 182 | + - a fixed structure that will initialize and close PTB in 'debug mode' |
| 183 | + (`PsychDebugWindowConfiguration`, `SkipSyncTests`) |
| 184 | + - the actual sandbox where to set your dynamic variables (the stimulation |
| 185 | + parameters) and the 'playground' where to develop the stimulation code |
| 186 | + |
| 187 | + 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`). |
0 commit comments