Before looking at the visual and coding methods in more detail, we need to introduce the main concept of objects. An easy way to do this is actually at the MATLAB command line…
Virtually everything in a PsychBench experiment is represented by objects. For example, each stimulus is an object, the functionality that listens for subject response is another object, devices like screens are objects if you need to change any of their settings from default, etc.
Each object has an object type, e.g. picture, cross, sound, keyPress, fixedStepStaircase, etc. If you’re working in MATLAB you can make objects using commands <><type><>Object, e.g. pictureObject, crossObject, etc. For example, type the following at the MATLAB command line:
cross = crossObject;
masks = linearDotMaskObject(2);
This makes one object of type cross and puts it in a variable called cross, and two objects of type linearDotMask in a 1×2 array called masks. Object variables can have any names you want. The only rule is that if an array contains more than one object, they must all be the same type.
Now input these objects to the command showElements to quickly see them:
showElements(cross, masks)
Note PsychBench uses its own framework for objects, which are just represented by structs. You don’t need to know anything about MATLAB’s object-oriented framework.
Each object has properties which you can set for options and parameters. In keeping, each object is represented by a struct variable (multiple objects by a struct array) and its properties correspond to fields. Objects have a lot of flexibility, which means a lot of properties you can set. However, most properties have useful default values. To leave any property at default, just don’t set it (or leave it = empty <cd>[]<cd> if the object is in an array with other objects that have the property set). It’s common for an object to have many properties and you only need to set a few of them to get the effect you want.
What we saw above were cross and linearDotMask objects with all properties at default. Now let’s change some properties. We use standard dot syntax, as well as indexes if multiple objects are in a variable. Here colors are RGB vectors with numbers between 0–1 and sizes are dimensions in deg visual angle, which is the default screen distance unit in PsychBench:
cross.color = [1 0 0];
masks(1).size = [3 6];
masks(1).numDots = 50;
masks(2).dotDirection = [90 0];
showElements(cross, masks)
Which properties an object can have depends on its type. The properties we set above are specific to cross and linearDotMask object types. In addition, there are some properties which some or all object types have in common. For example, try adding the following to shift each of these objects 2 deg right and down from its default position of screen center:
cross.position = [2 2];
masks(1).position = [2 2];
masks(2).position = [2 2];
showElements(cross, masks)
Depending on the property, values could be any data type, e.g. numeric (number, vector, matrix, etc.), text (generally both character array <cds>''<cds> and string <cds>""<cds> work), cell array, etc. Some complex properties are further structs or struct arrays. For example, try this:
cross.vary.what = <cdsm>"position"<cdsm>;
cross.vary.setExpr = <cdsm>"[-5+mod(2*t, 10) 2*sin(pi*t)]"<cdsm>;
showElements(cross)
How do you know what object types there are, what properties each one has, and what all their default property values are? This is all in the reference documentation online. You can also just type pb at the MATLAB command line to see a list with links, or pb <><object type><> to go straight to a specific type.
Most objects in PsychBench fall under the umbrella of element objects. Elements are all the stimuli as well as functionality (e.g. recording response from subject) that can run in trials. There are many different element object types, e.g. picture, cross, linearDotMask, keyPress, etc. etc. We also add new element types regularly—if you have requests, please email contact@psychbench.org. You can also make your own element types or receive them from other people.
Aside from elements, there are also other object types that are useful in some cases. All these other objects are optional. You only need to add them in an experiment if you want to change an option from default or need special functionality like a VR headset or staircase.
An object of type trial lets you change options for a whole trial, e.g. pre-trial interval (default = 0.75 sec).
Similarly, an object of type experiment lets you change options for a whole experiment, e.g. background color (default = black).
An object of type screen represents the screen and window the experiment shows in. This lets you set options like window size and position, timing precision / compatibility tradeoffs, color/luminance calibration, etc. Aside from screen, other device objects allow options for other devices, e.g. vrhmd, speaker, microphone, port, cedrusPad, etc.
Various staircase object types let you run staircase experiments.