initial commit

Author: Remi-Gau

CPP_getResponseDemo.m

@@ -0,0 +1,118 @@
+  jk%% Demo showing how to use the getResponse function
+
+% This small script shows how to use the getReponse function 
+%  (a wrapper around the KbQueue function from PTB)
+
+% start with a clean slate
+clear; clc; 
+if IsOctave
+    more off % for a better display experience
+end
+
+%% set parameters
+
+% cfg.responseBox would be the device number of the device used by the participant to give his/her 
+% response: like the button box in the scanner or a separate keyboard for a behavioral experiment
+%
+% cfg.keyboard would be the device number of the keyboard on which the experimenter will type or 
+% press the keys necessary to start or abort the experiment.
+
+%  cfg.responseBox and cfg.keyboard can be different or the same.
+
+% If you want to know the device number of all the keyboards and responses
+% boxes connected to the computer you can use the following code.
+% [cfg.keyboardNumbers, cfg.keyboardNames] = GetKeyboardIndices
+
+% Using empty vectors should work for linux when to select the "main"
+%  keyboard. You might have to try some other values for Windows. To
+%  assigne a specific keyboard input the kb assigned value (see README)
+cfg.keyboard = [];
+cfg.responseBox = [];
+
+% We set which keys are "valid", any keys other than those will be ignored
+expParameters.responseKey = {};
+
+
+%% init
+
+% Keyboard
+%  Make sure keyboard mapping is the same on all supported operating systems
+%  Apple MacOS/X, MS-Windows and GNU/Linux:
+KbName('UnifyKeyNames');
+
+
+% we ask PTB to tell us which keyboard devices are connected to the computer
+[cfg.keyboardNumbers, cfg.keyboardNames] = GetKeyboardIndices;
+
+cfg.keyboardNumbers
+cfg.keyboardNames
+
+
+% Test that the keyboards are correctly configured
+testKeyboards(cfg);
+
+% Give the time to the test key to be released and not listened
+WaitSecs(1);
+
+
+fprintf('\nDuring the next 5 seconds we will collect responses on the following keys: \n\n');
+if isempty(expParameters.responseKey)
+    fprintf('\nALL KEYS\n\n');    
+else
+    for iKey=1:numel(expParameters.responseKey)
+        fprintf('\n%s', expParameters.responseKey{iKey});  
+    end
+    fprintf('\n\n');
+end
+
+
+
+%% Run demo
+
+% Create the keyboard queue to collect responses.
+getResponse('init', cfg, expParameters, 1);
+
+% Start collecting responses for 5 seconds
+%  Each new key press is added to the queue of events recorded by KbQueue
+startSecs = GetSecs();
+getResponse('start', cfg, expParameters, 1);
+
+
+
+% Here we wait for 5 seconds but are still collecting responses.
+%  So you could still be doing something else (presenting audio and visual stim) and
+%  still collect responses.
+WaitSecs(5);
+
+
+
+% Check what keys were pressed (all of them)
+responseEvents = getResponse('check', cfg, expParameters, 0, 1);
+
+% The following line would only return key presses and not releases
+% responseEvents = getResponse('check', cfg, expParameters, 1 , 1);
+
+% This can be used to flush the queue: empty all events that are still present in the queue
+getResponse('flush', cfg, expParameters, 1);
+
+% If you wan to stop listening to key presses.
+getResponse('stop', cfg, expParameters, 1);
+
+
+
+
+%% Now we look what keys were pressed and when
+for iEvent = 1:size(responseEvents, 1)
+
+    if responseEvents(iEvent).pressed
+        eventType = 'pressed';
+    else
+        eventType = 'released';
+    end
+
+    fprintf('%s was %s at time %.3f seconds\n', ...
+        responseEvents(iEvent).key_name, ...
+        eventType, ...
+        responseEvents(iEvent).onset - startSecs);
+
+end

README.md

@@ -0,0 +1,38 @@
+# CPP_PTB
+
+List of PsychToolBox (PTB) related functions for the Crossmodal Perpcetion and Plasticity lab (CPP)
+
+Most of the functions here are mostly wrappers around some PTB functions to facilitate their use and to have a codebase to facilitate their reuse.
+
+## Code guidestyle
+
+We use the `pascalCase` to more easily differentiates our functions from the ones from PTB that use a `CamelCase`.
+
+## Structure and function details
+
+### setParameters
+
+### initPTB
+
+### getResponse
+It is wrapper function to use KbQueue which is definitely what you should used to collect responses.
+
+You can easily collect responses while running some other code at the same time.
+
+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.
+
+You can use it in a way so that it only takes responses from certain keys.
+
+If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`.
+
+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:
+
+```
+[keyboardNumbers, keyboardNames] = GetKeyboardIndices;
+
+keyboardNumbers
+keyboardNames
+```
+
+
+### cleanUp

cleanUp.m

@@ -0,0 +1,23 @@
+function cleanUp
+
+WaitSecs(0.5);
+
+Priority(0);
+
+ListenChar(0);
+KbQueueRelease();
+
+ShowCursor
+
+% Screen Close All
+sca;
+
+if ~ismac
+    % remove PsychDebugWindowConfiguration
+    clear Screen
+end
+
+close all
+
+ 
+end

deg2Pix.m

@@ -0,0 +1,8 @@
+function structure = deg2Pix(fieldName, structure, Cfg)
+
+deg = getfield( structure, fieldName);
+
+structure = setfield( structure, [fieldName 'Pix'], ...
+    floor(Cfg.ppd * deg) ) ;
+
+end

drawFixationCross.m

@@ -0,0 +1,10 @@
+function drawFixationCross(Cfg, ExpParameters, color)
+
+Screen('DrawLines', ...
+    Cfg.win, ...
+    Cfg.allCoords, ...
+    ExpParameters.lineWidthPix, ...
+    color , ...
+    [Cfg.center(1) Cfg.center(2)], 1);
+
+end

getResponse.m

@@ -0,0 +1,162 @@
+function responseEvents = getResponse(action, cfg, expParameters, getOnlyPress, verbose)
+% wrapper function to use KbQueue
+% The queue will be listening to key presses on the response box as defined
+%  in the cfg structure : see setParameters for more details.
+%
+% Check the CPP_getResponseDemo for a quick script on how to use it.
+%
+%
+%
+% INPUT
+%
+% - action: Defines what we want the function to do
+%  - init: to initialise the queue
+%  - start: to start listening to keypresses
+%  - check:
+%  - flush:
+%  - stop:
+%
+% - getOnlyPress: if set to 1 the function will only return the key presses and 
+%    will not return when the keys were released (default=1) 
+%    See the section on OUTPUT below for more info
+%
+%
+% 
+% OUTPUT
+% 
+% responseEvents: returns all the keypresses and return them as a structure
+% with field names that make it easier to save the output of in a BIDS
+% format
+% 
+% responseEvents.onset : this is an absolute value and you should
+%   substract the "experiment start time" to get a value relative to when the
+%   experiment was started.
+% 
+% responseEvents.trial_type = 'response';
+% 
+% responseEvents.duration = 0;
+% 
+% responseEvents.key_name : the name of the key pressed
+% 
+% responseEvents(iEvent,1).pressed : if 
+%   pressed == 1  --> the key was pressed
+%   pressed == 0  --> the key was released
+
+
+if nargin < 4
+    getOnlyPress = 1;
+end
+
+if nargin < 5
+    verbose = 0;
+end
+
+responseEvents = struct;
+responseEvents.onset = [];
+responseEvents.trial_type = [];
+responseEvents.duration = [];
+responseEvents.key_name = [];
+responseEvents.pressed = [];
+
+responseBox = cfg.responseBox;
+
+switch action
+    
+    case 'init'
+        
+        % Prevent spilling of keystrokes into console. If you use ListenChar(2)
+        % this will prevent you from using KbQueue.
+        ListenChar(-1);
+        
+        % Clean and realease any queue that might be opened
+        KbQueueRelease(responseBox);
+        
+        %% Defines keys
+        % list all the response keys we want KbQueue to listen to
+        
+        % by default we listen to all keys
+        % but if responseKey is set in the parameters we override this
+        keysOfInterest = ones(1,256); 
+        
+        fprintf('\n Will be listening for key presses on : ')
+        
+        if isfield(expParameters, 'responseKey') && ~isempty(expParameters.responseKey)
+            
+            keysOfInterest = zeros(1,256);
+            
+            for iKey = 1:numel(expParameters.responseKey)
+                fprintf('\n  - %s ', expParameters.responseKey{iKey})
+                responseTargetKeys(iKey) = KbName(expParameters.responseKey(iKey)); %#ok<*SAGROW>
+            end
+            
+            keysOfInterest(responseTargetKeys) = 1;
+           
+        else
+            
+            fprintf('ALL KEYS.')
+            
+        end
+        
+        fprintf('\n\n')
+        
+        % Create the keyboard queue to collect responses.
+        KbQueueCreate(responseBox, keysOfInterest);
+        
+        
+    case 'start'
+        
+        fprintf('\n starting to listen to keypresses\n')
+        
+        KbQueueStart(responseBox);
+        
+        
+    case 'check'
+        
+        if verbose
+            fprintf('\n checking recent keypresses\n')
+        end
+        
+        iEvent = 1;
+         
+        while KbEventAvail(responseBox)
+            
+            event = KbEventGet(responseBox);
+            
+            % we only return the pressed keys by default
+            if getOnlyPress && event.Pressed==0
+            else
+                
+                responseEvents(iEvent,1).onset = event.Time;
+                responseEvents(iEvent,1).trial_type = 'response';
+                responseEvents(iEvent,1).duration = 0;
+                responseEvents(iEvent,1).key_name = KbName(event.Keycode);
+                responseEvents(iEvent,1).pressed =  event.Pressed;
+
+            end
+            
+            iEvent = iEvent + 1;
+            
+        end
+        
+    case 'flush'
+        
+        if verbose
+            fprintf('\n reinitialising keyboard queue\n')
+        end
+       
+        KbQueueFlush(responseBox);
+        
+        
+    case 'stop'
+        
+        fprintf('\n stopping to listen to keypresses\n\n')
+        
+        KbQueueRelease(responseBox);
+        
+        % Give me my keyboard back... Pretty please.
+        ListenChar(0);
+        
+end
+
+
+end