Phases, trials, and steps

Steps

BITTSy runs with a series of STEPS. The steps run in order, and everything that occurs in the experiment itself is part of a step. Steps allow you to LOOP back, which is how you repeat sections of execution (such as trials) - and thus steps are a fundamental way in which the program is structured.

The first line that defines a STEP marks an important division in the protocol file. Everything in a protocol file discussed thus far, with the exception of dynamic tags - starting definitions, optional settings, file path definitions for tags, group definitions - must all precede the first STEP. All of these are fully validated and processed by BITTSy prior to the start of an experiment. Once the experimenter clicks to run a protocol, the portion of the protocol file being executed is what follows STEP 1.

SIDES ARE {CENTER, RIGHT, LEFT}
LIGHTS ARE {LEFT, CENTER, RIGHT}

LET passage1 = "C:\BITTSy-Stimuli\passage1.wav"
LET passage2 = "C:\BITTSy-Stimuli\passage2.wav"

STEP 1
Phase Test Start

STEP 2
LIGHT CENTER BLINK 200
UNTIL KEY C

STEP 3
LIGHT CENTER OFF
LIGHT LEFT BLINK 200
UNTIL KEY L

STEP 4
Trial Start
AUDIO LEFT passage1 ONCE
UNTIL SINGLELOOKAWAY passage1 GREATERTHAN 2000
UNTIL FINISHED

Note that everything in the example above happens within a STEP. These STEPs provide important reference points in your protocol, and all statements should be placed inside the structure of STEPs.

STEPs should be numbered in ascending order with no duplicates or missing values. Misnumbering steps will not necessarily result in any problems executing your protocol. But when loops are involved, there may be serious issues jumping back to an indicated STEP and executing intervening steps if the LOOP references steps that have been misnumbered.

Protocols can be split into as many STEPs as needed or desired.

STEPs can optionally end in step terminating conditions, which specify conditions that must be met before execution can proceed from one STEP to the next STEP. These are the UNTIL statements in the example above. When thinking about how to divide the progression of your experiment into STEPs, the most important thing to consider will be the necessity for these terminating conditions, and which actions in your experiment need to occur before you wait for one to be met. (How to structure STEPs and protocols will become clearer as you learn more in the upcoming sections, and look through example protocols.)

Phases and Trials

While STEPs provide internal structure to your protocol and are essential to BITTSy's execution of it, phases and trials are optional divisions within your protocol, whose chief importance is for marking sections that you wish to analyze.

Trials

Trials are the basic unit of your experiment that you wish to analyze, and can span across multiple STEPs.

For most experimenters, "trials" are the natural subdivision in an experiment - that is, we generally tend to think about experiments as consisting of trials. As such, a trial is probably a more intuitive concept than a STEP. But since multiple things could happen in a trial, trials will often contain multiple STEPs. Crucially, trials typically proceed until some sort of condition is met, such as a stimulus finishing playing, a certain amount of time elapsing, or the participant reaching a particular looking time requirement. These conditions will be step terminating conditions that then allow the trial to end in another, immediately following STEP.

Trial Start

Trial End

Trials are not explicitly numbered or named within the protocol - you merely specify where one should start and where it should end. All trials should have a start and end, and trials should not overlap with other trials.

The below example is what a trial could look like in a standard PLP study.

STEP 1
VIDEO CENTER attentiongetter LOOP
UNTIL KEY C

STEP 2
VIDEO CENTER OFF

STEP 3
Trial Start
VIDEO CENTER cat_dog ONCE
UNTIL FINISHED

STEP 5
Trial End

Note that the video being presented as an attention-getter is not included within a trial, because we don't have any intention of analyzing this section. Rather, the trial starts immediately before the first stimulus video, and ends immediately afterward.

When reporting looking time across trials, BITTSy will number trials within each phase, and restart numbering when a new phase is defined.

Phases

Phases can contain multiple trials, and mark divisions between groups of trials or STEPs that should be analyzed completely separately from each other, because they reflect some difference in the task the participant is doing (as in training and test phases; or pre-test, habituation, test and post-test).

Phase <name> Start

Phase End

Phases have a name that you can customize and specify in their start flags. These names are displayed to the experimenter when running the experiment, and listed in reports of study data. Phase names cannot contain any spaces. Phase end flags do not specify the name of the phase, but simply end the phase that was most recently started (i.e. the current phase).

The below example is what phases and trials could look like in a simple visual fixation study, with a fixed-length familiarization passage followed by two test trials in a fixed order.

STEP 1
Phase Familiarization Start
VIDEO CENTER attentiongetter LOOP
UNTIL KEY C

STEP 2
VIDEO CENTER OFF

STEP 3
Trial Start
VIDEO CENTER checkerboard ONCE
AUDIO CENTER passage ONCE
UNTIL FINISHED

STEP 4
Trial End
Phase End

STEP 6
Phase Test Start
VIDEO CENTER attentiongetter LOOP
UNTIL KEY C

STEP 7
Trial Start
VIDEO CENTER checkerboard ONCE
AUDIO CENTER familiar_words LOOP
UNTIL SINGLELOOKAWAY familiar_words GREATERTHAN 2000
UNTIL TIME 25000

STEP 8
Trial End
VIDEO CENTER OFF
AUDIO CENTER OFF
VIDEO CENTER attentiongetter LOOP
UNTIL KEY C

STEP 9
Trial Start
VIDEO CENTER checkerboard ONCE
AUDIO CENTER unfamiliar_words LOOP
UNTIL SINGLELOOKAWAY unfamiliar_words GREATERTHAN 2000
UNTIL TIME 25000

STEP 10
Trial End
Phase End

Marking divisions between phases is helpful for analyses of looking time through BITTSy's reporting module: phases are listed separately in these reports. Trials can always be looked at individually, but trials within the same phase can also be summed/averaged across automatically in reports. Thus, phase definitions should be placed to demarcate which trials can be analyzed together.

In some cases, the placement of phase definitions can impact the execution of protocols. For example, cumulative looking time can be calculated within the current phase, and exclude other trials previous to that phase. In habituation, phase definitions allow BITTSy to "know" to reject windows containing trials from two different phases (i.e. not including a pre-test trial as part of a basis window, as the pre-test should be considered completely separately from habituation phase trials).

Without placing any phase start and stop markers in your protocol files, your experiment will be considered to be a single phase, with all its trials analogous to each other.