JUMP

JUMP basics

What is JUMP?

JUMP clauses are a very powerful option introduced in BITTSy version 1.5. Ordinarily, BITTSy protocols progress linearly through the STEPs that you write - the entire protocol is executed (with the exception of LOOPs) line-by-line, in the order they appear in the protocol file. JUMP clauses allow there to be new and different paths through an experiment: STEPs can be skipped over, repeated, or executed out of order. Different participants can experience different parts of the protocol in different orders, depending on conditions that you specify. This opens up a wide new range of possible experiments in BITTSy.

JUMP clauses are an optional part of UNTIL statements, which are used by both step terminating conditions and loop terminating conditions. These statements must always be the last lines of the STEP that contains them, and cause execution to either remain within that step or loop through a series of steps until the specified conditions are met.

By default, once the UNTIL conditions of a STEP are met, the experiment progresses to the next step of the protocol, in order. Adding an optional JUMP clause to the UNTIL statement allows you to change this, and specify a different step in the experiment that should be executed next, after that condition is satisfied.

UNTIL <terminating condition> JUMP STEP <number>

When can a JUMP clause be used?

JUMP clauses can be utilized in any UNTIL statement, whether it is a step terminating condition or a loop terminating condition. The jump to the specified step does not occur until the UNTIL statement that contains it is satisfied. (Note that loop terminating conditions are checked only when the loop step is reached - see explanation here.)

JUMP clauses must always be embedded in UNTIL statements. They cannot occur on their own, to mean that execution should always jump to the specified step - they must depend on a condition being met. But you can achieve the same goal (a JUMP that always executes, immediately) by having that condition be something that you know will already be true at that point in your experiment, or specifying a wait time of a single millisecond.

UNTIL TIME 1 JUMP STEP <number>

Where can a JUMP go to?

The specified step to JUMP to can be either before or after the current STEP number. That is, a JUMP that is specified in an UNTIL statement at the end of STEP 5 could cause execution to skip backwards to an earlier step, or to anywhere later in the protocol.

It is possible to specify a jump to the same step that the JUMP clause itself is in - in this case, the same step is restarted from its beginning. However, this is rarely a desired behavior, and may have unintended consequences during steps in which stimuli are active and participants' looking time is being tracked. More commonly, to repeat the most recent part of an experiment, you would jump back to at least one STEP prior.

JUMP usage in complex terminating conditions

In combinations of terminating conditions (AND and OR types), one JUMP clause can be used per UNTIL line. For an AND type UNTIL statement such as this one,

UNTIL KEY X and TOTALLOOK stim LESSTHAN 5000 JUMP STEP 11

both terminating conditions would need to be met in order for a jump to the specified step to occur. (That is, the experimenter would have to press the X key during a trial in which the participant had looked at the stimulus for less than 5 seconds. Only then would STEP 11 be the next step to be executed.)

OR combinations are composed of two terminating conditions listed on consecutive lines. Whichever is satisfied first is where execution will jump to.

UNTIL KEY X JUMP STEP 15
UNTIL KEY Y JUMP STEP 22

JUMP clauses are optional - not having one always means to simply progress to the next STEP in order. You can always leave them out when that is the intended behavior, including within a combination of terminating conditions.

STEP 5
VIDEO CENTER attentiongetter LOOP
UNTIL KEY C
UNTIL KEY X JUMP STEP 31
UNTIL TIME 10000 JUMP STEP 4

STEP 6
Trial Start
...

Sometimes in combinations of terminating conditions, a human reader might find it clearer what's happening if you still include a JUMP statement that just goes to the next step (i.e.,UNTIL KEY C JUMP STEP 6 in the example above), even though you could equivalently leave it out. You may see some examples like this in this manual!

Potential pitfalls with JUMP

JUMP is a very powerful command that can achieve very useful new effects, but it also introduces the possibility to create new types of errors if you are not careful! When validating protocols, BITTSy is not able to check for errors that could occur because steps are executed out of order. Instead, these errors could cause unintended behavior, or could make your experiment crash.

You will need to be careful to think through all of the ways you've set your experiment to progress, and make sure that all of these are well-formed. Below are some of types of errors that you should look for when using JUMP:

• Placement of start and stop flags for trials and phases. These primarily function to mark sections for analysis, so if one path through the experiment does not have starts and stops happening at all the right times, or has some skipped or missing, it is not always obvious when testing the study's execution. Whenever a JUMP is specified in a step where a phase and/or trial is currently in-progress, check that all possible next steps lead to a Stop statement for that trial or phase. You can also label and save logs from tests of running through different possible paths in the study, and generate reports from them to check whether phase and trial information was recorded like you intended. If you're missing start or stop flags, you may have missing trials, trials that last far too long or contain stimuli that they shouldn't, or you can get a trial embedded within another trial, or a phase within another phase (these last two possibilities could make the reporting program crash.)

• Dynamic tag selections and use in action statements. A tag cannot be used in an action statement before it has been defined in a previously-executed STEP. So if a JUMP clause can allow your steps to happen out of order, ensure that steps where dynamic tags are created occur beforehand in all possible orderings. Otherwise, some runs of the experiment will end abruptly with an error message about the tag not existing. Whenever possible, it is easiest to prevent this type of error by establishing persistent group selections and tag assignments (such as the condition assignment for the participant) at the very beginning of an experiment, and making trial stimuli selections immediately before they are presented.

• Creating an experiment that doesn't end. If your JUMP clauses allow you to jump backwards or repeat sections of the study, check that you don't accidentally create an infinite repetition, or make any series of jumps that will result in never reaching the end of the protocol!

• For OR combinations of terminating conditions, where different conditions result in jumping to different parts of the experiment, be careful that they are checked in the correct order. UNTIL conditions are checked in the order that they are listed. See below about skipping a phase based on habituation status for an example of where this can be extremely important!

Example uses of JUMP

This section walks through a variety of cases in which JUMP clauses are particularly useful, or create experiment structures that cannot be achieved with a BITTSy protocol that progresses through steps in a strictly linear fashion. These examples are meant to illustrate some possibilities opened up by using JUMP, but are by no means exhaustive!

Ending a phase or loop early

Sometimes you want an option to abort a phase or loop, but not by pressing the Escape key, which ends the whole experiment - just to stop what's currently happening and move on to a different point in the protocol. In a simple loop, you may be able to do this with an alternate loop terminating condition. But in other cases, this will be best achieved using JUMP.

The example below runs three trials, each selecting a video to play out of a different group. The pattern is looped an additional 8 times, for a total of 27 trials.

STEP 1
Trial Start
LET stim1 = (TAKE group1 RANDOM)
VIDEO CENTER stim1 ONCE
UNTIL FINISHED

STEP 2
Trial End

STEP 3
Trial Start
LET stim2 = (TAKE group2 RANDOM)
VIDEO CENTER stim2 ONCE
UNTIL FINISHED

STEP 4
Trial End

STEP 5
Trial Start
LET stim3 = (TAKE group3 RANDOM)
VIDEO CENTER stim3 ONCE
UNTIL FINISHED

STEP 6
Trial End

STEP 7
LOOP STEP 1
UNTIL 8 TIMES

STEP 8
...

If a participant is fussy or inattentive, we might want to let an experimenter skip to a different phase and see how that one goes instead, just by pressing X on the keyboard. If that decision should only be made at the end of one of these sequences of three trials, we could specify that as an alternative loop terminating condition:

STEP 7
LOOP STEP 1
UNTIL 8 TIMES
UNTIL KEY X

But since loop terminating conditions are only checked when the loop step is reached, the experimenter could press the X key during trial #4 but not have the loop end until after trial #6 was complete. That might not be acceptable, particularly if the trial videos are quite long. Instead, adding a keypress with a JUMP statement as new step terminating conditions within the loop would let the experimenter end the loop immediately by jumping outside it, to STEP 8. This change to STEP 1 is shown below; the change would also be made to steps 3 and 5.

STEP 1
LET stim1 = (TAKE group1 RANDOM)
VIDEO CENTER stim1 ONCE
UNTIL KEY X JUMP STEP 8
UNTIL FINISHED

Repeating a trial

Sometimes you may want the ability to repeat the same trial again, for example in a familiarization or training phase of an experiment if the participant isn't paying attention or if a trial is started early by an experimenter mistake. A JUMP clause can be used to repeat trials according to an experimenter's decision during the study session (i.e. a particular key is pressed to repeat the trial) or according to external or looking-time criteria.

In the example below, the experimenter must decide after a trial to continue the experiment normally (by pressing C) or to repeat the trial (by pressing X). Because the jump goes to STEP 2 and does not repeat STEP 1, where the stimulus video is randomly selected, the same stimulus will be shown again on the repeated trial.

STEP 1
LET trialstim = (TAKE alltrials RANDOM)

STEP 2
Trial Start
VIDEO CENTER trialstim ONCE
UNTIL FINISHED

STEP 3
Trial End
UNTIL KEY X JUMP STEP 2
UNTIL KEY C

STEP 4
...

Rather than deciding after a trial is over, you could specify criteria that can be met during a trial to end the trial early and then repeat it. Here, it is important to ensure that Trial Start and Trial End flags are placed properly with respect to JUMP statements. We'll need to make sure that the initial presentation still properly ends with a Trial End flag, even when it is cut off early, so that we don't end up with a trial starting inside of another trial (which is problematic for making reports!) To do this, we can adapt the example from before to make two separate steps that end the trial, one to go to when the trial ends normally (STEP 5) and one that is only executed when the experimenter decides to end the trial early, and otherwise skipped over (STEP 4). A second JUMP clause in STEP 4 happens effectively immediately to restart the trial by going back to the start of STEP 2.

STEP 1
LET trialstim = (TAKE alltrials RANDOM)

STEP 2
Trial Start
VIDEO CENTER trialstim ONCE
UNTIL KEY X
UNTIL FINISHED JUMP STEP 5

STEP 4
Trial End
UNTIL TIME 1 JUMP STEP 2

STEP 5
Trial End
...

It is important to note that trials that are repeated are not distinguished in any way in standard BITTSy reports of session information or looking time. BITTSy simply numbers each trial with how many Trial Start flags it has encountered so far within the session - so if trials were repeated like in these examples, they would show up in reports as trials with consecutive numbers and the same stimulus displayed, and both would be included in reported summary measures. If your protocols allow for cut-short or repeated trials that you would want to exclude, you must recalculate summary measures manually - or you can write a custom reporting function that handles trials differently whenever the log file records a JUMP step being executed, in any way that is appropriate for your study.

Repeating a phase

Similar to repeating a trial, there may be situations where you'd like to repeat a whole phase of the experiment - for example, to re-run a familiarization phase if the experimenter feels the participant is not yet comfortable with how the task works.

In the example below, four familiarization trials are played. At the end of the phase, the screen stays blank until the experimenter selects whether to continue on to the test phase as normal (pressing C) or to repeat the familiarization phase (pressing X).

STEP 1
Phase Familiarization Start

STEP 2
Trial Start
LET stim = (FROM familiarizationvideos RANDOM)
VIDEO CENTER stim ONCE
UNTIL FINISHED

STEP 3
Trial End

STEP 4
LOOP STEP 2
UNTIL 3 TIMES

STEP 5
Phase End
UNTIL KEY X JUMP STEP 1
UNTIL KEY C

STEP 6
Phase Test Start
...

In the above example, it's important for the experimenter to know that they are supposed to make a choice when the phase ends, and which keys to press for which phase! Reminders can be put in comment lines (any line that begins with a #, which is ignored by BITTSy when validating and executing protocols) at the beginning of a protocol, so that they are visible after the protocol is loaded. The name of the current phase is also displayed in the experimenter's window, so signaling them with a new phase name may make the timing of this choice more obvious.

STEP 5
Phase End
Phase Choose_Repeat Start
UNTIL KEY X JUMP STEP 1
UNTIL KEY C

STEP 6
Phase End
Phase Test Start
...

If you wanted instead to let the experimenter decide mid-trial to stop and restart the familiarization phase, you could adapt the example like below. Like the second example in the previous section on repeating a trial, we define two separate steps that end the trial, with STEP 3, the option that also ends the phase and restarts it, only happening if the experimenter presses X during a trial.

STEP 1
Phase Familiarization Start

STEP 2
Trial Start
LET stim = (FROM familiarizationvideos RANDOM)
VIDEO CENTER stim ONCE
UNTIL FINISHED JUMP STEP 4
UNTIL KEY X

STEP 3
Trial End
Phase End
UNTIL TIME 1 JUMP STEP 1

STEP 4
Trial End

STEP 5
LOOP STEP 2
UNTIL 3 TIMES

STEP 6
Phase End

STEP 7
Phase Test Start
...

Skipping a phase

Sometimes, when a particular condition is met, a phase or section of the experiment can be skipped entirely. For example, in habituation studies, participants who do not meet criteria for habituation are typically excluded from all analyses of looking time in the test phase. Sometimes it is desirable to show the test trials anyway if there are only a couple of them, so that the parent observing the study can see it end as originally described. But if it would be preferable in your study to not make the participant go through any extra trials when you know the data won't be used, you can use a JUMP statement to skip to the end of the study depending on the participant's habituation status.

The example below is the habituation phase of the word-object mapping habituation example walk-through. The only change is the JUMP clause added to the first loop terminating condition in STEP 12, which specifies when the habituation phase should stop if the criterion is not yet reached. If twenty habituation trials have been displayed and the participant has not reached the specified looking time reduction criteria, we can skip to the very end of the protocol without playing any test or post-test trials.

STEP 7
Phase Habituation Start
LET pair = (FROM habit_pairs RANDOM)

STEP 8
LIGHT CENTER BLINK 250
UNTIL KEY C

STEP 9
LIGHT CENTER OFF
Trial Start

STEP 10
VIDEO CENTER pair LOOP
AUDIO CENTER pair LOOP
UNTIL SINGLELOOKAWAY pair GREATERTHAN 1000
UNTIL TIME 20000

STEP 11
Trial End
VIDEO CENTER OFF
AUDIO CENTER OFF

STEP 12
LOOP STEP 8
UNTIL CRITERIONMET
UNTIL 19 TIMES JUMP STEP 26

STEP 13
Phase End

STEP 14
Phase Test Start

...

STEP 26
Phase End

Remember that terminating conditions in an OR combination (like those in STEP 12 above) are always checked in order of which is written first, and the first one that is satisfied is the one that will progress the experiment. This can be extremely important when one of them has a JUMP statement! If the two UNTIL statements in STEP 12 were in the opposite order, whenever a participant met the habituation criteria in the last possible trial, we would check UNTIL 19 TIMES first, and end up skipping over the test phase without calculating that the participant had actually habituated, and should have gone into the test phase instead. Listing UNTIL CRITERIONMET first ensures that this end condition is always checked first, and habituation can still be achieved on the last possible trial.

Events based on participant choice or discrete behavior

You can use JUMP statements to take different actions depending on a participant's behavior during a particular step. This capability is the crux of conditioned headturn experiments, but can be used flexibly outside of this paradigm to reinforce a particular behavior or to respond to a selection that the participant makes.

The example below begins by having the experimenter press L or R to indicate when the participant turns to look to the left or right side of the testing booth. Whichever key is pressed first, a video will be displayed to a screen on the same side where the participant is now looking, and the video stops when they look away briefly. This lets us display stimuli in a way that is responsive to a cue from the participant.

STEP 1
UNTIL KEY L JUMP STEP 2
UNTIL KEY R JUMP STEP 4

STEP 2
VIDEO LEFT stimulus LOOP
UNTIL SINGLELOOKAWAY 1000

STEP 3
VIDEO LEFT OFF
UNTIL TIME 1 JUMP STEP 1

STEP 4
VIDEO RIGHT stimulus LOOP
UNTIL SINGLELOOKAWAY 1000

STEP 5
VIDEO RIGHT OFF
UNTIL TIME 1 JUMP STEP 1

This is a simple example, with only a couple steps in each of the two "branches" that can execute based on different criteria - but it is possible to construct much more complex sequences of steps that are skipped in one case and executed in another, with more than two branches, branches within other branches, etc. BITTSy's STEP numbers, which only label steps and do not reflect their order of execution when JUMP clauses are being used, can start to look confusing in these cases - and you'll want to keep track of which step numbers represent important events in your experiment, as well as the context of when they happen. Constructing a flowchart is very useful for this! This one represents the example above.

This kind of setup could be used similarly to "reveal what's behind a door" by having the experimenter record a child's selection (either from gaze direction or pointing behavior) with a keypress, then displaying an animation on the screen that the child picks.

Progressing based on consecutive criteria

Some experiments may require a particular sequence of conditions to be met, and other conditions to not be met in-between, before moving on to another phase of the experiment. For example, in a study with a "correct" or desired response, you might require three correct responses in a row before moving on from the training phase.

Often such studies will be constructed so that experimenters can remain blinded to which participant behaviors are considered correct. But for a simple example of this kind of protocol structure, imagine a study where during each training trial, the experimenter waits for one of two behaviors, and records either a C keypress for "correct" or M for "mistake." The participant must get three correct trials in a row to keep going in the study, and training trials continue until they achieve this, or get 10 wrong in a row.

STEP 1
Trial Start
...
UNTIL KEY C JUMP STEP 3
UNTIL KEY M

STEP 2
Trial End
LOOP STEP 1
UNTIL 9 TIMES JUMP STEP <number - end of experiment>

STEP 3
Trial End
Trial Start
...
UNTIL KEY C JUMP STEP 5
UNTIL KEY M

STEP 4
Trial End
UNTIL TIME 1 JUMP STEP 1

STEP 5
Trial End
Trial Start
...
UNTIL KEY C JUMP STEP 7
UNTIL KEY M

STEP 6
Trial End
UNTIL TIME 1 JUMP STEP 1

STEP 7
Trial End
Phase Test Start
...

STEP 3 is a trial like any other, yet it is only executed when the participant has a current streak of one correct response. Another correct response leads to a jump to STEP 5, which is only executed when the participant has a current score of two correct responses in a row. And a correct response recorded in STEP 5, bringing us to three correct responses in a row, is the only way to get to STEP 7, which begins the next phase of the experiment. But an incorrect response in either STEP 3 or STEP 5 breaks the streak and lands the execution back in STEP 1, which represents a current streak of zero.

This structure can be visualized in a flowchart like below:

Events based on accumulated looking time

Studies with familiarization or training phases often require the participant to accumulate a certain threshold of looking time toward a set of stimuli before moving to the next phase. Sometimes you only care about total time attending to the set as a whole, and it doesn't matter whether the participant looks much longer at some than others. But sometimes you want the looking time to end up relatively balanced. In these cases, once one stimulus reaches the threshold, you can use a JUMP statement to repeat another one that's below the threshold, until the participant meets the required looking time to that one too.

This is commonly needed in headturn preference procedure experiments with an initial exposure phase that involves a couple of passages. Typically the passages alternate trials or are ordered randomly - but if the participant reaches the required exposure for one passage very early on, we don't want them to keep hearing that passage more and more while trying to reach the threshold listening time on the other passage. The example below is based on the familiarization phase of this headturn preference example, but rather than alternating trials and looping in STEP 6 until both audio files achieve 25 seconds of listening time, we only alternate trials until one of them does, then execute either STEPs 7-10 or 11-14 depending on which audio file still needs more listening time.

LET passages = {passage1, passage2} 

...

STEP 1
Phase Train Start

STEP 2
LIGHT CENTER BLINK 250
UNTIL KEY C

STEP 3
LIGHT CENTER OFF
LET side1 = (FROM trainingsides RANDOM {with max 2 repeats in succession})
LIGHT side1 BLINK 250
UNTIL KEY L
UNTIL KEY R

STEP 4
Trial Start
LET trialaudio = (FROM passages RANDOM {with max 0 repeats in succession})
AUDIO side1 trialaudio ONCE
UNTIL FINISHED
UNTIL SINGLELOOKAWAY trialaudio GREATERTHAN 2000

STEP 5
Trial End
LIGHT side1 OFF
AUDIO side1 OFF

STEP 6
LOOP STEP 2
UNTIL TOTALLOOK passage1 GREATERTHAN 25000 THIS PHASE JUMP STEP 11
UNTIL TOTALLOOK passage2 GREATERTHAN 25000 THIS PHASE


# if passage2 meets looking time threshold first, continue and repeat passage1

STEP 7
LIGHT CENTER BLINK 250
UNTIL KEY C

STEP 8
LIGHT CENTER OFF
LET side2 = (FROM trainingsides RANDOM {with max 2 repeats in succession})
LIGHT side2 BLINK 250
UNTIL KEY L
UNTIL KEY R

STEP 9
Trial Start
AUDIO side2 passage1 ONCE
UNTIL FINISHED
UNTIL SINGLELOOKAWAY passage1 GREATERTHAN 2000

STEP 10
LOOP STEP 7
UNTIL TOTALLOOK passage1 GREATERTHAN 25000 THIS PHASE JUMP STEP 16


# if passage1 meets threshold first, jump to here and repeat passage2

STEP 11
LIGHT CENTER BLINK 250
UNTIL KEY C

STEP 12
LIGHT CENTER OFF
LET side3 = (FROM trainingsides RANDOM {with max 2 repeats in succession})
LIGHT side3 BLINK 250
UNTIL KEY L
UNTIL KEY R

STEP 13
Trial Start
AUDIO side3 passage2 ONCE
UNTIL FINISHED
UNTIL SINGLELOOKAWAY passage2 GREATERTHAN 2000

STEP 14
LOOP STEP 11
UNTIL TOTALLOOK passage2 GREATERTHAN 25000 THIS PHASE


# after the passage with lower looking time has been repeated enough to 
# meet the threshold, continue here

STEP 16
Phase End
...