The codes that you write will almost always be based around trials that contain phases.  Therefore, it is important to be able to run a trial (or phase) after you have defined it.  For that reason, we have the “run” command.

Runing-trials-and-phases-EBNF-diagram

You can use the “run” command to run either trials or phases.  The “expression” above is the name of the trial or phase that you want to run.

Examples

The following are all different examples of using the  run trial  command:

The first one ( run trial MasterTrial) will run the master trial just once.

The second one ( run trial MasterTrial for 5 min ) will continue running the master t1rial for 5 minutes, but will not interrupt or stop the trial if a trial runs over 5 minutes; that is, it keeps re-running the master trial as long as 5 minutes haven’t passed.  If a trial ends at 4:59 it will start a new trial and that trial will run normally without being interrupted.  If a trial ends at 5:00 or 5:01 a new trial would not be started.

The last three uses above should be pretty self explanatory, assuming that there is some variable “ someValue” that your trial is modifying in some way; of course you could call your variable whatever you with.  :-)

A more complex example

Of course, you may not know which trial or phase you want to run.  For example, let’s say we want to randomly run one of three phases; using the random() function we can do the following:

This will print out one of three different things each time we run the experiment.

Target duration

All codes can define a special variable called “ targetDuration “.  For example:

If the run command has a test expression then it will also check that the session has not running longer the codes’s target duration.  That is, if you have specified a target duration with the “targetDuration” variable somewhere in the code, then the run command will not run a trial (or phase) after the session has been running for longer than the target duration.

So even if you have:

The “someTrial” trial may be run fewer times if the time the session has been active is longer than the target duration.  So for example, if you have a really stubborn bird that takes twice as long to complete a trial as any other bird (Subject 19 I’m looking at you here!) this feature helps keep the duration of each session the same at the expense of running fewer trials.  If you don’t want this behaviour, then don’t set the “targetDuration” property and the run command will always run the number of times you specify.

Note however that this feature will not cancel an in-progress trial (or phase) that was started before the target duration was exceeded.