# Loops ## How loops work Experiments done with infants and toddlers usually consist of a series of trials, in which the stimuli used or side of presentation may vary from trial to trial, but the core structure of every trial is the same. Rather than writing a long protocol file that separately specifies every trial with a unique set of steps, you can specify the trial structure once, then use a **loop** to repeat it. A **LOOP statement** will cause the steps in between the specified step number and the step in which the `LOOP` statement is defined to be executed. This occurs repeatedly, until the loop statement's terminating conditions have been satisfied. ``` LOOP STEP UNTIL ``` The following example is the entire test phase of a preferential looking study with trials shown in a fixed order. The entire study runs via looping over a set of 3 steps that comprise an attention getter and a trial. ``` STEP 1 Phase Test Start STEP 2 VIDEO CENTER attentiongetter LOOP UNTIL KEY X STEP 3 VIDEO CENTER OFF STEP 4 Trial Start LET trial_stim = (TAKE stim_list FIRST) VIDEO CENTER trial_stim ONCE UNTIL FINISHED STEP 5 Trial End LOOP STEP 2 UNTIL 23 TIMES STEP 6 Phase End ``` When running the protocol, we begin, as always, at `STEP 1`. The test phase starts, and the first attention getter video plays until the experimenter indicates the participant is ready for a trial. The first trial stimulus is chosen from the list of stimuli, displayed, and played to the end. The **loop step** (the step that contains the `LOOP` statement) is `STEP 5`. When it is reached, execution jumps back to `STEP 2`, and proceeds again through steps 3 and 4, and onto 5. Upon reaching the `LOOP` statement again, it again jumps back to 2, and proceeds through the steps. This repeats a total of 23 times, displaying a total of 24 attention-getters and trials (the one original execution of steps 2-4, *plus* the 23 times it looped over that sequence.) Loops can be **nested** within each other, allowing for concise specification of experiments with a block structure. Below is the test phase of a headturn preference study that consists of 3 blocks. Each block is comprised of 4 trials, for a total of 12 trials. Before each trial, the participant is oriented to a neutral position (center), and then the trial begins once they reorient in the direction where the light has begun flashing and from which the audio will play. ``` ... STEP 9 Phase Test Start STEP 10 LET thisblock = (TAKE testblocks FIRST) STEP 11 LIGHT CENTER BLINK 200 UNTIL KEY C STEP 12 LIGHT CENTER OFF STEP 13 LET side1 = (FROM testsides RANDOM {with max 2 repeats in succession}) LIGHT side1 BLINK 200 UNTIL KEY L UNTIL KEY R STEP 14 Trial Start LET trialaudio = (TAKE thisblock RANDOM) AUDIO side1 trialaudio ONCE UNTIL FINISHED UNTIL SINGLELOOKAWAY trialaudio GREATERTHAN 2000 STEP 15 Trial End AUDIO side1 OFF LIGHT side1 OFF STEP 16 LOOP STEP 11 UNTIL 3 TIMES STEP 17 LOOP STEP 10 UNTIL 2 TIMES STEP 18 Phase End ``` Steps 11-15 specify a sequence of centering the participant and playing a trial, which is a unit that repeats throughout the experiment. These steps are looped over in `STEP 16`, which specifies to execute this sequence three additional times so that the first block contains four trials. Once the first block is finished, the `LOOP` statement in `STEP 17` is reached, which has it jump back to `STEP 10` to select the next block of stimuli to present. The inner loop in `STEP 16` is executed just as before, playing the four trials in this block also. `STEP 17` is reached again, and execution jumps back to `STEP 10` to select the third block, and the nested loops work in the same way to play four trials here. Now that `STEP 17` has had its loop repeated the required two times, we move to `STEP 18` and the phase ends. {% hint style="warning" %} Be careful with trial/phase start and stop flags, in relation to where loops are placed. In the above example, `STEP 9` contains only the flag to start the test phase, and we loop to `STEP 10` to repeat a block. If we had started the test phase in the step that was looped to, we would repeat it at every block - and we want the phase to only start once. Therefore, it should be outside the loop. {% endhint %} ## Loop terminating conditions Just like [step terminating conditions](/bittsy/creating-protocols/step-terminating-conditions.md), loop terminating conditions can be combined together for more complex end conditions. They can be joined by an AND, such that both conditions must be met: ``` LOOP STEP UNTIL and ``` Or by an OR, such that only one condition need be met before ending the loop. ``` LOOP STEP UNTIL UNTIL ``` ### TIMES looped ``` LOOP STEP UNTIL TIMES ``` This loops back to the specified step, executes all the intervening steps in order, and loops again until it has completed the entire loop the specified number of times. For example, ``` STEP 1 LET dog = (TAKE dogs RANDOM) IMAGE CENTER dog UNTIL 5000 STEP 2 LOOP STEP 1 UNTIL 5 TIMES ``` The above loop would execute `STEP 1` five times, in addition to the first execution before the loop step was reached. Therefore, we would select and display an image from the group `dogs` a total of 6 times. ### EMPTY Rather than specifying a set number of times to loop, you can also loop until a particular group has no remaining options for selection. ``` LOOP STEP UNTIL EMPTY ``` For example, ``` LET dogs = {dalmatian, deerhound, boxer, bulldog, beagle, whippet} STEP 1 LET dog = (TAKE dogs RANDOM) IMAGE CENTER dog UNTIL 5000 STEP 2 LOOP STEP 1 UNTIL dogs EMPTY ``` The above loop would run until all the tags in `dogs` have been marked as selected, and none are eligible to be chosen by the `TAKE` statement - in this case, the loop would repeat 5 times, in addition to the first selection, for a total of 6 items displayed. ### TIME elapsed It is also possible to execute a loop until *at least* a certain amount of time has elapsed since the looping began. ``` LOOP STEP UNTIL TIME