Skip to content
/ CPP_PTB Public
forked from cpp-lln-lab/CPP_PTB

a set of function to make it easier to create behavioral, EEG, fMRI experiment with psychtoolbox

License

Notifications You must be signed in to change notification settings

CerenB/CPP_PTB

 
 

Repository files navigation

Build Status

codecov

All Contributors

CPP_PTB

This is the Crossmodal Perception and Plasticity lab (CPP) PsychToolBox (PTB) toolbox.

Those functions are mostly wrappers around some PTB functions to facilitate their use and to have a codebase to facilitate their reuse.

1. Requirements

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

For instructions see the following links:

Requirements Used version
PsychToolBox >=3.0.14
Matlab >=2015b
or octave 4.?

The exact version required for this to work but it is known to work with:

  • matlab 2015b or octave 4.2.2 and PTB 3.0.14.

2. Code guidestyle

We use the camelCase to more easily differentiates our functions from the ones from PTB that use a PascalCase. We use the following regular expression for function names: [a-z]+(([A-Z]|[0-9]){1}[a-z]+)*.

We keep the McCabe complexity as reported by the check_my_code function below 15.

We use the MISS_HIT linter to automatically fix some linting issues. The code style and quality is also checked during the continuous integration.

3. How to install

3.1. Download with git

cd fullpath_to_directory_where_to_install
# use git to download the code
git clone https://github.com/cpp-lln-lab/CPP_PTB.git
# move into the folder you have just created
cd CPP_PTB
# add the src folder to the matlab path and save the path
matlab -nojvm -nosplash -r "addpath(fullfile(pwd)); savepath ();"

Then get the latest commit:

# from the directory where you downloaded the code
git pull origin master

To work with a specific version, create a branch at a specific version tag number

# creating and checking out a branch that will be calle version1 at the version tag v0.0.1
git checkout -b version1 v0.0.1

3.2. Add as a submodule

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

cd fullpath_to_directory_where_to_install
# use git to download the code
git submodule add https://github.com/cpp-lln-lab/CPP_PTB.git
# move into the folder you have just created
cd CPP_PTB
# add the src folder to the matlab path and save the path
matlab -nojvm -nosplash -r "addpath(fullfile(pwd))"

To get the latest commit you then need to update the submodule with the information on its remote repository and then merge those locally.

git submodule update --remote --merge

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

3.2.1. Example for submodule usage

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):

git clone --recurse-submodules https://github.com/user_name/yourExperiment.git

This would be the way to do it "by hand"

# clone the repo
git clone https://github.com/user_name/yourExperiment.git

# go into the directory
cd yourExperiment

# initialize and get the content of the first level of submodules  (CPP_PTB and CPP_BIDS)
git submodule init
git submodule update

# get the nested submodules JSONio and BIDS-matlab for CPP_BIDS
git submodule foreach --recursive 'git submodule init'
git submodule foreach --recursive 'git submodule update'

3.3. Direct download

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

Pick a specific version:

https://github.com/cpp-lln-lab/CPP_PTB/releases

Or take the latest commit (NOT RECOMMENDED):

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

4. Setting up keyboards

To select a specific keyboard to be used by the experimenter or the participant, you need to know the value assigned by PTB to each keyboard device.

To know this copy-paste this on the command window:

[keyboardNumbers, keyboardNames] = GetKeyboardIndices;

disp(keyboardNumbers);
disp(keyboardNames);

You can then assign a specific device number to the main keyboard or the response box in the cfg structure

  • cfg.keyboard.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.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.keyboard.responseBox and cfg.keyboard.keyboard can be different or the same.

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

5. Structure

The cfg structure is where most of the information about your experiment will be defined.

Below we try to outline what it contains.

cfg.testingDevice = 'pc';

% cfg.color
cfg.keyboard.keyboard = [];
cfg.keyboard.responseBox = [];
cfg.keyboard.responseKey = {};
cfg.keyboard.escapeKey = 'ESCAPE';

% cfg.debug
cfg.debug.do = true;
cfg.debug.transpWin = true;
cfg.debug.smallWin = true;

% cfg.text
cfg.text.font
cfg.text.size
cfg.text.style

% cfg.color
cfg.color.background

% cfg.screen
cfg.screen.monitorWidth
cfg.screen.monitorDistance
cfg.screen.idx
cfg.screen.win
cfg.screen.winRect
cfg.screen.winWidth
cfg.screen.winHeight
cfg.screen.center
cfg.screen.FOV
cfg.screen.ppd
cfg.screen.ifi
cfg.screen.monRefresh

% cfg.audio
cfg.audio.do
cfg.audio.pahandle
cfg.audio.devIdx
cfg.audio.playbackMode
cfg.audio.requestedLatency
cfg.audio.fs
cfg.audio.channels
cfg.audio.initVolume
cfg.audio.pushSize  
cfg.audio.requestOffsetTime
cfg.audio.reqsSampleOffset

% cfg.mri
cfg.mri.repetitionTime
cfg.mri.triggerNb
cfg.mri.triggerKey

6. Annexes

6.1. Experiment template [ WIP ]

6.2. devSandbox (stand-alone)

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.

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.

It is composed of two parts:

  • a fixed structure that will initialize and close PTB in 'debug mode' (PsychDebugWindowConfiguration, SkipSyncTests)
  • the actual sandbox where to set your dynamic variables (the stimulation parameters) and the 'playground' where to develop the stimulation code

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).

7. Contributors ✨

Thanks goes to these wonderful people (emoji key):


Remi Gau

💻 🎨 📖

marcobarilari

💻 🎨 📖

CerenB

💻 🎨 📖 👀

This project follows the all-contributors specification. Contributions of any kind welcome!

About

a set of function to make it easier to create behavioral, EEG, fMRI experiment with psychtoolbox

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • MATLAB 100.0%