Getting started / Making an experiment

Experiment results output, Record properties

Results output variables and files

When you run an experiment with the command runExperiment it outputs results in several variables, and optionally saves them to .mat and .csv files at the end of each trial. First is a cell array that is meant to be easy to read in MATLAB’s visual variable editor. You can double-click it in the MATLAB workspace to open it there. Second is a variable that compresses trial results into a numeric matrix or other arrays with uniform data types, which lets you extract and analyze data in MATLAB without needing to convert from cell. Third is a struct array containing some basic information about the experiment run (date/time, etc.). You add your own information for this when you call runExperiment.

Specifying what to see in results – Run info, info, report

When you call runExperiment you can input your own information about the experiment run (e.g. subject ID, etc.) to add to the struct output—type help runExperiment for usage.

Aside from that, everything in results comes from objects in the experiment. For any object you can specify what to see in results using two properties that all objects have: info and report. These properties don't affect how an object works—they just specify what to see in results. Both are optional—if you leave both at default, the object won’t show in results.

Custom information – info

info sets custom information to see about the object—e.g. test condition values associated with the object. You can set info to a struct with any fields containing any values you want. Field names go to headings in the results table and field values go under those headings. Note sometimes it's convenient to add a trial object and set info fields there—this groups those columns near the front of the results table, not specific to any other object in the trial. [In the visual method you can use # in a property/variable heading (heading row 2) as a shortcut for setting info fields.]

Property values – report

report is an array of strings that are names of properties for the object to show. These can include input properties which you can set when making the experiment. More commonly they include record properties which you can't set but PsychBench uses to record information during the experiment. Common record properties to report are response, responseLatency, and others for response handler elements. The documentation for each object type lists both its input and record properties.

Example

We define four trials, eaching showing two rectangle elements with the following properties set for results output (other properties not shown). We want to see some custom information we make under n_condition for the trial and direction for each rectangle. We also want to see the value of input property rotation (which we set) and record property duration (which PsychBench fills in during the experiment) for each rectangle.

In the coding method:

rotations  = [30 -30];
directions = [<cdsm>"cw" "ccw"<cdsm>];

        c = 0;
<cdkm>for<cdkm> d1 = 1:2
    <cdkm>for<cdkm> d2 = 1:2
        c = c+1;
       
        rects = rectangleObject(2);
        rects(1).rotation       = rotations(d1);
        rects(1).info.direction = directions(d1);
        rects(2).rotation       = rotations(d2);
        rects(2).info.direction = directions(d2);
        for n = 1:2
            rects(n).report = [<cdsm>"rotation" "duration"<cdsm>];
        end
        ...
       
        trial = trialObject;
        trial.info.n_condition = c;
        ...
       
        addTrial(rects, trial);
    <cdkm>end<cdkm>
<cdkm>end<cdkm>

In the visual method:

If we ran the four trials in random order, the first results variable output would look something like this. You can see the information requested, plus some information PsychBench adds automatically: