Getting started / Making an experiment

Making and running an experiment – Coding method (optional)

In the coding method of making an experiment we write a MATLAB script that builds the experiment in memory directly. This alternative can be useful for unusual experiments, or just if you prefer it. It isn’t actually that much harder—an experiment script isn’t really code in the usual sense, more like setting a list of parameters. And the steps correspond pretty much directly to what you would do in the visual method. A few commands specific to the coding method are all in <><PsychBench folder><>/coding.

The best way to learn the coding method is by examples. Below is a basic example taken from Overview earlier. For many more realistic examples see <><PsychBench folder><>/docs/demos—every demo has both visual and coding versions.

newExperiment

fileNames = [<cdsm>"red cone.png" "green cylinder.png" "blue cube.png"<cdsm>];
<cdkm>for<cdkm> fileName = fileNames
    pic = pictureObject;
    pic.fileName = fileName;
    pic.height = 10;
    pic.start.t = 0;
    pic.end.response = true;
    pic.report = <cdsm>"fileName"<cdsm>;
‍
    recorder = keyPressObject;
    recorder.listenKeyNames = <cdsm>"space"<cdsm>;
    recorder.start.t = 0;
    recorder.report = <cdsm>"responseLatency"<cdsm>;

    addTrial(picture, recorder);
<cdkm>end<cdkm>

nn = randomOrder(rep(1:3, 2));
setTrialList(nn);

Following are the general steps. You can see most of these steps in the example above.

• Call newExperiment at the top of every experiment script. This tells PsychBench to set up for building an experiment in memory, including clearing any experiment already in memory.
• For each trial definition: Make all the element objects that can run in it. Optionally you can also make a trial object. Make objects using <><type><>Object functions (e.g. pictureObject), put them in any variables you want, and set properties that you want to change from default using standard dot syntax (Objects and properties). When you have all the objects for a trial, input them to the function addTrial. This adds the trial definition to the set of trial definitions the script is building in memory. By default PsychBench numbers trial definitions 1, 2, 3… as addTrial is called. You can also use custom numbering or names using an input to addTrial.

Like in the visual method, the usual approach is to ignore trial repetition and order to run in when defining trials. Instead just define each distinct trial once, and in any order. In the coding method, distinct refers to property values of objects in trials. Since you can define trials in any order, you can use for loops through condition values to automate it, calling addTrial once per iteration. You can use nested for loops for combinations of conditions.

• You can add trial repetition and order to run in by making a trial list variable: either a vector of trial definition numbers or a mixed array of numbers/names. Call the function setTrialList once and input the trial list. Or for unusual cases you can set trial numbers to run as during the experiment directly in trial definitions instead using an input to addTrial.
• If you need objects not specific to trial like an experiment object, screen or other device objects, staircase objects, etc., make them like element objects. Call the function addToExperiment once and input them there.
• Save the script. This is equivalent to saving an experiment spreadsheet file.
• Run the script to build the experiment in memory. Generally re-run the script for each experiment run/subject in order to redo any randomization in the script. This is equivalent to loading an experiment spreadsheet file (loadExperiment).
• Follow with commands like viewExperiment, runExperiment, etc. as usual.