diff --git a/README.md b/README.md index c7fb344..a16a0e4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,23 @@ -# CPP_PTB + +* 1. [Requirements](#Requirements) +* 2. [Code guidestyle](#Codeguidestyle) +* 3. [How to install](#Howtoinstall) + * 3.1. [Download with git](#Downloadwithgit) + * 3.2. [Add as a submodule](#Addasasubmodule) + * 3.2.1. [Example for submodule usage](#Exampleforsubmoduleusage) + * 3.3. [Direct download](#Directdownload) +* 4. [Setting up keyboards](#Settingupkeyboards) +* 5. [Structure](#Structure) +* 6. [Annexes](#Annexes) + * 6.1. [Experiment template [ WIP ]](#ExperimenttemplateWIP) + * 6.2. [devSandbox (stand-alone)](#devSandboxstand-alone) +* 7. [Contributors ✨](#Contributors) + + +# CPP_PTB [![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 Those functions are mostly wrappers around some PTB functions to facilitate their use and to have a codebase to facilitate their reuse. -## Requirements +## 1. Requirements Make sure that the following toolboxes are installed and added to the matlab / octave path. @@ -18,13 +37,13 @@ For instructions see the following links: | Requirements | Used version | |----------------------------------------------------------|--------------| | [PsychToolBox](http://psychtoolbox.org/) Duuuuhh | >=3.0.14 | -| [Matlab](https://www.mathworks.com/products/matlab.html) | 201?? | +| [Matlab](https://www.mathworks.com/products/matlab.html) | >=2015b | | or [octave](https://www.gnu.org/software/octave/) | 4.? | The exact version required for this to work but it is known to work with: -- matlab 2017a or octave 4.2.2 and PTB 3.0.16. +- matlab 2015b or octave 4.2.2 and PTB 3.0.14. -## Code guidestyle +## 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]+)*`. @@ -33,9 +52,9 @@ We keep the McCabe complexity as reported by the [check_my_code function](https: We use the [MISS_HIT linter](https://florianschanda.github.io/miss_hit/style_checker.html) to automatically fix some linting issues. -## How to install +## 3. How to install -### Download with git +### 3.1. Download with git ``` bash 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 git checkout -b version1 v0.0.1 ``` -### Add as a submodule +### 3.2. Add as a submodule Add it as a submodule in the repo you are working on. @@ -81,7 +100,7 @@ git submodule update --remote --merge Remember that updates to submodules need to be committed as well. -#### Example for submodule usage +#### 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): ``` bash @@ -104,12 +123,8 @@ git submodule update git submodule foreach --recursive 'git submodule init' git submodule foreach --recursive 'git submodule update' ``` -**TO DO** - -### Direct download +### 3.3. Direct download Download the code. Unzip. And add to the matlab path. @@ -121,12 +136,7 @@ Or take the latest commit (NOT RECOMMENDED): https://github.com/cpp-lln-lab/CPP_PTB/archive/master.zip -**TO DO** - - -## Setting up keyboards +## 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. @@ -151,7 +161,7 @@ press the keys necessary to start or abort the experiment. Using empty vectors (ie `[]`) or a negative value for those means that you will let PTB find and use the default device. -## Structure +## 5. Structure ```matlab @@ -209,101 +219,11 @@ cfg.mri.triggerNb cfg.mri.triggerKey ``` -## function details - - -### initPTB - -This will initialize PsychToolBox - -- screen -- the windon opened takes the whole screen by default -- set in debug mode with window transparency if necessary -- can skip synch test if you ask for it (nicely) -- gets the flip interval -- computes the pixel per degree of visual angle -- set font details -- keyboard -- sound - -### testKeyboards - -Checks that the keyboards asked for properly connected. - -If no key is pressed on the correct keyboard after the timeOut time this exits with an error. - -### cleanUp - -A wrapper function to close all windows, ports, show mouse cursor, close keyboard queues -and give access back to the keyboards. - -### getExperimentStart - -Wrapper function that will show a fixation cross and collect a start timestamp in `cfg.experimentStart` - -### getExperimentEnd - -Wrapper function that will show a fixation cross and display in the console the whole experiment's duration in minutes and seconds - -### getResponse - -It is wrapper function to use `KbQueue` which is definitely what you should use to collect responses. - -You can easily collect responses while running some other code at the same time. - -It will only take responses from one device which can simply be the "main keyboard" -(the default device that PTB will find) 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 and ignore others (like -the triggers from an MRI scanner). - -If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`. - -In brief, there are several actions you can execute with this function. - -- init: initialize the buffer for key presses on a given device (you can also specify the keys of interest that should be listened to). -- start: start listening to the key presses (carefully insert into your script - where do you want to start buffering the responses). -- check: till that point, it will check the buffer for all key presses. - - It only reports presses on the keys of interest mentioned at initialization. - - It **can** also check for presses on the escape key and abort if the escape key is part of the keys of interest. -- flush: Empties the buffer of key presses in case you want to discard any previous key presses. -- stop: Stops buffering key presses. You can still restart by calling "start" again. -- release: Closes the buffer for good. - -### deg2Pix - -For a given field value in degrees of visual angle in the input `structure`, -this computes its value in pixel using the pixel per degree value of the `cfg` structure -and returns a structure with an additional field with Pix suffix holding that new value. - -### drawFixationCross - -Define the parameters of the fixation cross in `cfg` and `expParameters` and this does the rest. - -### eyeTracker - -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). - -### pressSpace4me - -Use that to stop your script and only restart when the space bar is pressed. - -### standByScreen - -It shows a basic one-page instruction stored in `cfg.task.instruction` and wait for `space` stroke. - -### waitForTrigger - -Counts a certain number of triggers coming from the mri/scanner before returning. -Requires number of triggers to wait for. - - -## Annexes +## 6. Annexes -### Experiment template [ WIP ] +### 6.1. Experiment template [ WIP ] -### devSandbox (stand-alone) +### 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. @@ -317,7 +237,7 @@ It is composed of two parts: 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`). -## Contributors ✨ +## 7. Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): diff --git a/docs/functions_description.md b/docs/functions_description.md new file mode 100644 index 0000000..f373e1e --- /dev/null +++ b/docs/functions_description.md @@ -0,0 +1,111 @@ + +* 1. [function details](#functiondetails) + * 1.1. [initPTB](#initPTB) + * 1.2. [testKeyboards](#testKeyboards) + * 1.3. [cleanUp](#cleanUp) + * 1.4. [getExperimentStart](#getExperimentStart) + * 1.5. [getExperimentEnd](#getExperimentEnd) + * 1.6. [getResponse](#getResponse) + * 1.7. [deg2Pix](#deg2Pix) + * 1.8. [drawFixationCross](#drawFixationCross) + * 1.9. [eyeTracker](#eyeTracker) + * 1.10. [pressSpace4me](#pressSpace4me) + * 1.11. [standByScreen](#standByScreen) + * 1.12. [waitForTrigger](#waitForTrigger) + + +# functions description + + + +## 1. function details + + +### 1.1. initPTB + +This will initialize PsychToolBox + +- screen +- the windon opened takes the whole screen by default +- set in debug mode with window transparency if necessary +- can skip synch test if you ask for it (nicely) +- gets the flip interval +- computes the pixel per degree of visual angle +- set font details +- keyboard +- sound + +### 1.2. testKeyboards + +Checks that the keyboards asked for properly connected. + +If no key is pressed on the correct keyboard after the timeOut time this exits with an error. + +### 1.3. cleanUp + +A wrapper function to close all windows, ports, show mouse cursor, close keyboard queues +and give access back to the keyboards. + +### 1.4. getExperimentStart + +Wrapper function that will show a fixation cross and collect a start timestamp in `cfg.experimentStart` + +### 1.5. getExperimentEnd + +Wrapper function that will show a fixation cross and display in the console the whole experiment's duration in minutes and seconds + +### 1.6. getResponse + +It is wrapper function to use `KbQueue` which is definitely what you should use to collect responses. + +You can easily collect responses while running some other code at the same time. + +It will only take responses from one device which can simply be the "main keyboard" +(the default device that PTB will find) 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 and ignore others (like +the triggers from an MRI scanner). + +If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`. + +In brief, there are several actions you can execute with this function. + +- init: initialize the buffer for key presses on a given device (you can also specify the keys of interest that should be listened to). +- start: start listening to the key presses (carefully insert into your script - where do you want to start buffering the responses). +- check: till that point, it will check the buffer for all key presses. + - It only reports presses on the keys of interest mentioned at initialization. + - It **can** also check for presses on the escape key and abort if the escape key is part of the keys of interest. +- flush: Empties the buffer of key presses in case you want to discard any previous key presses. +- stop: Stops buffering key presses. You can still restart by calling "start" again. +- release: Closes the buffer for good. + +### 1.7. deg2Pix + +For a given field value in degrees of visual angle in the input `structure`, +this computes its value in pixel using the pixel per degree value of the `cfg` structure +and returns a structure with an additional field with Pix suffix holding that new value. + +### 1.8. drawFixationCross + +Define the parameters of the fixation cross in `cfg` and `expParameters` and this does the rest. + +### 1.9. eyeTracker + +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). + +### 1.10. pressSpace4me + +Use that to stop your script and only restart when the space bar is pressed. + +### 1.11. standByScreen + +It shows a basic one-page instruction stored in `cfg.task.instruction` and wait for `space` stroke. + +### 1.12. waitForTrigger + +Counts a certain number of triggers coming from the mri/scanner before returning. +Requires number of triggers to wait for. \ No newline at end of file diff --git a/checkPtbVersion.m b/src/checkPtbVersion.m similarity index 100% rename from checkPtbVersion.m rename to src/checkPtbVersion.m diff --git a/cleanUp.m b/src/cleanUp.m similarity index 100% rename from cleanUp.m rename to src/cleanUp.m diff --git a/computeFOV.m b/src/computeFOV.m similarity index 100% rename from computeFOV.m rename to src/computeFOV.m diff --git a/degToPix.m b/src/degToPix.m similarity index 100% rename from degToPix.m rename to src/degToPix.m diff --git a/drawFixation.m b/src/drawFixation.m similarity index 100% rename from drawFixation.m rename to src/drawFixation.m diff --git a/eyeTracker.m b/src/eyeTracker.m similarity index 100% rename from eyeTracker.m rename to src/eyeTracker.m diff --git a/farewellScreen.m b/src/farewellScreen.m similarity index 100% rename from farewellScreen.m rename to src/farewellScreen.m diff --git a/getExperimentEnd.m b/src/getExperimentEnd.m similarity index 100% rename from getExperimentEnd.m rename to src/getExperimentEnd.m diff --git a/getExperimentStart.m b/src/getExperimentStart.m similarity index 100% rename from getExperimentStart.m rename to src/getExperimentStart.m diff --git a/initFixation.m b/src/initFixation.m similarity index 100% rename from initFixation.m rename to src/initFixation.m diff --git a/initPTB.m b/src/initPTB.m similarity index 91% rename from initPTB.m rename to src/initPTB.m index 76925de..0476e8d 100644 --- a/initPTB.m +++ b/src/initPTB.m @@ -21,6 +21,8 @@ % checkPtbVersion(); + + cfg = getOsInfo(cfg); pth = fileparts(mfilename('fullpath')); addpath(genpath(fullfile(pth, 'src'))); @@ -85,6 +87,27 @@ end +function cfg = getOsInfo(cfg) + + cfg.software.os = computer(); + cfg.software.name = 'Psychtoolbox'; + cfg.software.RRID = 'SCR_002881'; + + [~, versionStruc] = PsychtoolboxVersion; + + cfg.software.version = sprintf('%i.%i.%i', ... + versionStruc.major, ... + versionStruc.minor, ... + versionStruc.point); + + runsOn = 'Matlab - '; + if IsOctave + runsOn = 'Octave - '; + end + cfg.software.runsOn = [runsOn version()]; + +end + function initDebug(cfg) % init PTB with different options in concordance to the debug Parameters diff --git a/checkAbort.m b/src/keyboard/checkAbort.m similarity index 100% rename from checkAbort.m rename to src/keyboard/checkAbort.m diff --git a/collectAndSaveResponses.m b/src/keyboard/collectAndSaveResponses.m similarity index 100% rename from collectAndSaveResponses.m rename to src/keyboard/collectAndSaveResponses.m diff --git a/getResponse.m b/src/keyboard/getResponse.m similarity index 100% rename from getResponse.m rename to src/keyboard/getResponse.m diff --git a/pressSpaceForMe.m b/src/keyboard/pressSpaceForMe.m similarity index 100% rename from pressSpaceForMe.m rename to src/keyboard/pressSpaceForMe.m diff --git a/testKeyboards.m b/src/keyboard/testKeyboards.m similarity index 100% rename from testKeyboards.m rename to src/keyboard/testKeyboards.m diff --git a/printCreditsCppPtb.m b/src/printCreditsCppPtb.m similarity index 100% rename from printCreditsCppPtb.m rename to src/printCreditsCppPtb.m diff --git a/setDefaultsPTB.m b/src/setDefaultsPTB.m similarity index 100% rename from setDefaultsPTB.m rename to src/setDefaultsPTB.m diff --git a/standByScreen.m b/src/standByScreen.m similarity index 100% rename from standByScreen.m rename to src/standByScreen.m diff --git a/waitForTrigger.m b/src/waitForTrigger.m similarity index 100% rename from waitForTrigger.m rename to src/waitForTrigger.m