Define all other parameters (sections 2-11) in [myHardwareSetup.m](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myHardwareSetup.m) if necessary. You can find descriptions and possible arguments in the script that will help you. This will set up the general hardware for your experiment, including input and output devices and possibly a connected Raspberry system that can be controlled remotely via network. For the first start the standard setting are fine and you can now start with your first project.
Make sure to specify the correct pin numbers when using any external devices such as house light or feeder (read chapter 2.2. Coding device interfaces for further information). Default settings are good for testing purposes. In the following example the feeder uses pin number 4 and the feeder light uses pin number 5. Other output devices are not used, thus they contain an empty matrix.
Make sure to specify the correct pin numbers when using any external devices such as house light or feeder (read [chapter 2.2. Coding device interfaces](/How-tos#using-a-raspberry-pi-as-local) for further information). Default settings are good for testing purposes. In the following example the feeder uses pin number 4 and the feeder light uses pin number 5. Other output devices are not used, thus they contain an empty matrix.
~~~matlab
%% (3a) Please specify the OUTPUT devices
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Each device is connected to a separate pin/output at the output device.
% Please specify the pin numbers for the devices used in the setup. Unused
For beginners and your first programs there is no need to modify the [myParadigmSetup.m](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myParadigmSetup.m) script, since it deals with hardware setups that you probably don’t have for your first steps.
If you are more familiar with the toolbox and had your first success stories continue with setting up the myParadigmSetup script in defining the position of response keys. This feature is mostly used for setups with physical switches that are used in front of a monitor or for setups with a touch screen that expects a response on a defined position.
If you are more familiar with the toolbox and had your first success stories continue with setting up the [myParadigmSetup](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myParadigmSetup.m) script in defining the position of response keys. This feature is mostly used for setups with physical switches that are used in front of a monitor or for setups with a touch screen that expects a response on a defined position.
Edit sections 1-6 to choose certain setups for your software. These include switch/ image position with respect to the screen size (1), width and height of these switches/ images (2), background color for your presentation window (3), enabled/ disabled transparency of your stimuli (4), enable/ disable sound support (5) and choosing an image for negative feedback if needed (6).
This is an example of how to define the position of a response key on the monitor.
he advantage of having these two setup functions of the toolbox becomes apparent when you want to move your whole experiment to a new hardware device. In this case you only need to copy the whole experimental folder and edit myHardwareSetup without losing your other settings. The experiment will run just as fine as on the old hardware device. On the other hand, if you only want to change specific parts of your paradigm (e.g. timing, other stimuli, other response choices) you only need to edit your experiment function or, in case you want to change some of the above mentioned setups, myParadigmSetup. The myHardwareSetup function can stay untouched in these cases. The following figure displays what you need to edit when you change your hardware, paradigm or both.
The advantage of having these two setup functions of the toolbox becomes apparent when you want to move your whole experiment to a new hardware device. In this case you only need to copy the whole experimental folder and edit [myHardwareSetup](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myHardwareSetup.m) without losing your other settings. The experiment will run just as fine as on the old hardware device. On the other hand, if you only want to change specific parts of your paradigm (e.g. timing, other stimuli, other response choices) you only need to edit your experiment function or, in case you want to change some of the above mentioned setups, [myParadigmSetup](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myParadigmSetup.m). The [myHardwareSetup](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myHardwareSetup.m) function can stay untouched in these cases. The following figure displays what you need to edit when you change your hardware, paradigm or both.
@@ -82,32 +95,97 @@ Several functions of this toolbox are part of one of two modes: human and animal
Very simple experiments (especially for testing purposes) can be coded within one single script by calling functions of this toolbox. Generally, you can call functions of the toolbox one by one each by itself. Some functions, however, depend on the call of other functions before (see [function tree](function-tree)).
Functions that you will have to use in every single script are
-[initOTBR ](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/initOTBR.m)(3.3) to initialize the toolbox and
-[stopExperiment](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Tools/stopExperiment.m)(3.5.) to close the toolbox and reset all defined IO pins related to the toolbox.
-[initOTBR ](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/initOTBR.m)(or see [section 3.3](/Initialization#initotbr)) to initialize the toolbox and
-[stopExperiment](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Tools/stopExperiment.m)(or see [section 3.5.](/Initialization#stopexperiment)) to close the toolbox and reset all defined IO pins related to the toolbox.
Other essential functions include:
-[initWindow](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Screen/initWindow.m)(4.1.) to initialize the presentation window for every visual stimulus display (text, images, videos);
-[keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m)(9.2.) that is the main function used for behavioral in- and output during animal experiments, it can also be used to code waiting periods or inter-trial intervals (you can also use the Psychophysics toolbox function WaitSecs for that);
-[getAnswer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/getAnswer.m)(9.3.) has a similar usage and is better designed to be used in human experiments (also useful: getButtonClick (9.5.));
- bIO (10.1.) which is the most basic function to control external devices for e.g. feeding and punishment in animal experiments (more fine-grained functions for specific uses only: feeding, punishment (10.2., 10.3.)).
-[initWindow](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Screen/initWindow.m)(or see [section 4.1.](/Stimuli-Display#initwindow)) to initialize the presentation window for every visual stimulus display (text, images, videos);
-[keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m)(or see [section 9.2.](/User-or-animal-response#keybuffer-animal)) that is the main function used for behavioral in- and output during animal experiments, it can also be used to code waiting periods or inter-trial intervals (you can also use the Psychophysics toolbox function WaitSecs for that);
-[getAnswer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/getAnswer.m)(or see [section 9.3.](/User-or-animal-response#getanswer-human)) has a similar usage and is better designed to be used in human experiments (also useful: getButtonClick (9.5.));
-[bIO](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/Interface10/bIO.m)(or see [section 10.1.](/Device-interface#bio)) which is the most basic function to control external devices for e.g. feeding and punishment in animal experiments (more fine-grained functions for specific uses only: [feeding](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/feeding.m), [punishment](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/punishment.m)(or see section [10.2.](/Device-interface#feeding-animal), [10.3.](/Device-interface#punishment-animal), respectively)).
Furthermore, two very useful functions are:
-[save2File](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Tools/save2File.m)(11.3.) to save all your workspace variables in a MATLAB file and
-[errorSave](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Tools/errorSave.m)(11.1.) that, in case of an error, still saves all variables and returns an error warning (needs to be called in a try-catch statement).
-[save2File](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Tools/save2File.m)(or see [section 11.3.](/Save-Options#save2file)) to save all your workspace variables in a MATLAB file and
-[errorSave](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Tools/errorSave.m)(or see [section 11.1.](/Save-Options#errorsave)) that, in case of an error, still saves all variables and returns an error warning (needs to be called in a try-catch statement).
## Simple example
One simple example of a code that you can directly copy into your myExperiment.m file to try out simple functions of the toolbox (after adjusting myHardwareSetup and myParadigmSetup). Before trying out this example make sure that MATLAB’s working directory is correctly set to your experimental folder. It displays a text on the screen, waits for one second and closes the window and toolbox again.
One simple example of a code that you can directly copy into your myExperiment.m file to try out simple functions of the toolbox (after adjusting [myHardwareSetup](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myHardwareSetup.m) and [myParadigmSetup](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myParadigmSetup.m)). Before trying out this example make sure that MATLAB’s working directory is correctly set to your experimental folder. It displays a text on the screen, waits for one second and closes the window and toolbox again.
~~~matlab
% initialize toolbox (internal call of myHardwareSetup and myParadigmSetup)
initOTBR;
% initialize presentation window on your device's second monitor
initWindow(2);
% display the text 'Hello World' on the presentation window
The second advanced example will display a text and the toolbox will wait for 10 seconds or until the proper response (pressing key ’1’) has been made using the [keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m) function. After that depending on if a response has been made one of two text will be displayed followed by a one second waiting period. This is implemented by using a simple if statement and the output from [keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m)(see section 9.2. for clarification). Then the window and toolbox will be closed. Make sure to only press key ‘1’ when you are enabled to (during the ten second period when [keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m) is running).
The second advanced example will display a text and the toolbox will wait for 10 seconds or until the proper response (pressing key ’1’) has been made using the [keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m) function. After that depending on if a response has been made one of two text will be displayed followed by a one second waiting period. This is implemented by using a simple if statement and the output from [keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m)(see[section 9.2.](/User-or-animal-response#keybuffer-animal) for clarification). Then the window and toolbox will be closed. Make sure to only press key ‘1’ when you are enabled to (during the ten second period when [keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m) is running).
~~~matlab
% initialize toolbox (internal call of myHardwareSetup and myParadigmSetup)
initOTBR;
% initialize presentation window on your device's second monitor
initWindow(2);
% display the text 'Please press key '1'!' on the presentation window
showText('Please press key ''1''!');
% wait for 10 seconds or until key '1' has been pressed
total=keyBuffer(10,'goodKey',1,1);
% changing the output based on if a response was made
iftotal.goodKey>0
% display the text 'Thanks for pressing '1'!' on the presentation window
showText('Thanks for pressing ''1''!');
% wait for 1 second
WaitSecs(1);
elseiftotal.goodKey==0
% display the text 'You didn't press '1'!' on the presentation window
This example makes use of the function keyBuffer, which is used for animal experiments mostly. Because you have no hardware like response keys or IO devices installed you can use the keyboard to test your experiments. The keyboard as response device is defined in myHardwareSetup.m in section 2 by default. If you would like to use an IO hardware device that is supported by our toolbox all you have to do is change the setting in section 2 and make sure the response keys is connected to pin 1 (or input 1).
The third example shows a similar experiment using the function getAnswer, which is mostly used in human experiments. In this example the program asks the user to press a key and presents the pressed key on the screen.
This example makes use of the function [keyBuffer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/keyBuffer.m), which is used for animal experiments mostly. Because you have no hardware like response keys or IO devices installed you can use the keyboard to test your experiments. The keyboard as response device is defined in [myHardwareSetup.m](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myHardwareSetup.m) in section 2 by default. If you would like to use an IO hardware device that is supported by our toolbox all you have to do is change the setting in section 2 and make sure the response keys is connected to pin 1 (or input 1).
The third example shows a similar experiment using the function [getAnswer](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/IO/getAnswer.m), which is mostly used in human experiments. In this example the program asks the user to press a key and presents the pressed key on the screen.
~~~matlab
% Initialize toolbox
initOTBR;
% Initialize presentation window (second screen in this example)
initWindow(2);
% Display some text
showText('Please press a key of your choice');
% Wait 10 seconds or continue after a key was pressed
answer=getAnswer(10,'anyKey');
% Decide how to continue
if(answer.answer==1)
% Display text and present the key that was pressed
@@ -116,15 +194,15 @@ Depending on your device initWindow and [closeWindow](https://gitlab.ruhr-uni-bo
## Function tree
The functions of this toolbox are organized hierarchically. Some functions need to be called before you can use others. The following list displays this dependency. The keywords on the right in the oval-shaped bubbles mark functions that belong together. They can be used to find the respective headers in this documentation. On the left, mostly in boxes, you can see the functions of this toolbox as a flow chart. When writing a script make sure to follow the arrows of the chart. When you open a branch by calling the initialization function for a group of functions (e.g. initVideo for video display) make sure to follow this path until the end and call a close function if needed (e.g. closeVideo). Close functions can be identified by an arrow pointing downwards. If a function group does not have a close function (e.g. Text options) then there is nothing specific to call when you want to exit this group. Every function mentioned will also be explained below in this documentation.
At the very beginning of every script you always have to call the initOTBR function to initialize the use of the OTBR Toolbox. At the end of scripts you always have to call stopExperiment. The myHardwareSetup and myParadigmSetup functions will be called internally. If you want to use visual stimuli (Text, Images, Videos) you always need to call initWindow before, to initialize a presentation window. After finishing visual output call closeWindow to shut down the presentation window again. If you want to use network communication that is more flexible than the options mentioned in Device Interface please read section 2.2. Coding device interfaces first.
The functions of this toolbox are organized hierarchically. Some functions need to be called before you can use others. The following list displays this dependency. The keywords on the right in the oval-shaped bubbles mark functions that belong together. They can be used to find the respective headers in this documentation. On the left, mostly in boxes, you can see the functions of this toolbox as a flow chart. When writing a script make sure to follow the arrows of the chart. When you open a branch by calling the initialization function for a group of functions (e.g. initVideo for video display) make sure to follow this path until the end and call a close function if needed (e.g. [closeVideo](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Video/closeVideo.m)). Close functions can be identified by an arrow pointing downwards. If a function group does not have a close function (e.g. [Text options](Text Options)) then there is nothing specific to call when you want to exit this group. Every function mentioned will also be explained below in this documentation.
At the very beginning of every script you always have to call the [initOTBR](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/initOTBR.m) function to initialize the use of the OTBR Toolbox. At the end of scripts you always have to call stopExperiment. The [myHardwareSetup](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myHardwareSetup.m) and [myParadigmSetup](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/myParadigmSetup.m) functions will be called internally. If you want to use visual stimuli (Text, Images, Videos) you always need to call [initWindow](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Screen/initWindow.m) before, to initialize a presentation window. After finishing visual output call [closeWindow](https://gitlab.ruhr-uni-bochum.de/ikn/OTBR/-/blob/master/Video/closeVideo.m) to shut down the presentation window again. If you want to use network communication that is more flexible than the options mentioned in Device Interface please read [section 2.2. Coding device interfaces](/How-tos#using-a-raspberry-pi-as-local) for further information) first.
This document contains descriptions of every function included in this toolbox (starting with chapter 3. Initialization). The general structure of these descriptions is as follows (even though not every description contains all points):
This document contains descriptions of every function included in this toolbox (starting with [chapter 3. Initialization](Initialization)). The general structure of these descriptions is as follows (even though not every description contains all points):
1. general call of the function: syntax of the function, variable names represent input or output arguments explained below, the word ‘varargin’ represents variable optional input arguments that can be found beneath
2. general description: contains use of the functions, important things to know and sometimes tips for the use of the function
3. mandatory input arguments: input arguments necessary for the execution of the function, in most cases the function won’t work without these arguments
