# Live coding

Throughout runs of protocols, BITTSy is capable of receiving keypresses from an experimenter to indicate when and where the participant is paying attention. During the run, BITTSy will use this experimenter input to track the amount of time spent looking toward/away from active stimuli, and use this information to evaluate when looking-time controlled steps or loops should end. In the log file produced by the run, the precise timing of each keypress is logged, as well as a running record of durations spent attending in the direction of the currently-active stimuli within each trial.

Experiments that use [looking-time controlled terminating conditions for steps](../../creating-protocols/step-terminating-conditions#looking-based-conditions) and [loops](../../creating-protocols/loops#looking-controlled-end-conditions), as is typical in [visual fixation/habituation](../goals-and-capabilities/paradigms/visual-fixation-procedure) and [headturn preference procedure](../goals-and-capabilities/paradigms/the-headturn-preference-procedure) studies, must necessarily have the experimenter observing the session and live-coding the participant's attention via keypresses. In these paradigms, live-coded looking time is not only the primary data collected, but controls the progression of the experiment during its execution.

Experiments that use fixed-length trials and loops do not require live coding, but BITTSy will log experimenter keypresses in the same way regardless of whether the execution of the experiment depends upon looking time. Paradigms such as [preferential looking procedure](../goals-and-capabilities/paradigms/preferential-looking-procedure) typically rely on finer-grained analysis of looking time than can be achieved with live coding, and are coded offline from a video of the session. However, for any study where live coding is desired or appropriate, BITTSy will record keypresses, and the experimenter's recorded looking times can be obtained after the fact from the log file.

## Key assignments

Keys that the experimenter presses during live coding are typically meant to denote which direction the participant is looking. In BITTSy, individual keys can be assigned to the [SIDES](../../creating-protocols/starting-definitions#sides) defined in your experiment, so that when the experimenter presses a key that denotes a particular direction, the duration of that look will be logged as a look toward the stimuli being presented on that side. See the section on [key assignments](../../creating-protocols/optional-experiment-settings#key-assignments) for how to define these in your protocol file.

BITTSy will still log and respond to keys that are not assigned to a `SIDE` in your protocol. This is useful when you wish to have experimenter input progress the experiment without associating this action with any active stimuli. For example, you can play an attention-getting video on loop as an inter-trial period, and have the experimenter press a particular key to terminate that step and begin a trial. In the logs, you could recover the time a participant spent in this period before the experimenter started the trial, if you wished. As another example, you could specify a key as an alternative terminating condition that allows the experimenter to skip ahead to another independent section of the experiment if they judge the participant is too fussy to complete the current section.

However, this can cause problems in live coding if the experimenter accidentally presses the wrong key. Keys that are not assigned to a side are assumed when pressed to mean _not any side_ (i.e. `AWAY`), and are treated as time spent looking away from all active stimuli. Coding mistakes from accidental keypresses can be corrected by inspecting the log file afterwards (as long as what the experimenter intended is known), but when they occur in a step or loop that is looking-time controlled, they will affect the way the experiment progresses. When deciding which keys will be used for live coding a protocol, it is important to consider what set of keys will be easiest and least confusing for experimenters to use, and to ensure that study runners have adequate practice live coding with that set of keys before running any test sessions.

## Timing of keypresses

**The time of a keypress is recorded as the time it is pressed down** (as opposed to the time it is released, or "key up"). Pressing and holding down a key is therefore not any different from pressing it and immediately releasing it - BITTSy only cares about the initial pressing. Once a key is pressed, BITTSy assumes that looking continues in that direction until the experimenter presses a different key. We call this an "explicit away" coding scheme because the experimenter must explicitly press a new key to mean the participant has looked away.

Some other experimental software packages will allow you to code with a single key, where anytime that a key is pressed denotes looking in that direction and anytime it is released denotes looking away from that direction. BITTSy does not currently support this. Instead, the experimenter would need to press a different key that was set to mean a different direction, or a more general `AWAY`, to end the look.

## Recommendations

Setting up live coding and training experimenters to live code depends entirely on your requirements and preferences for your experiment. We do have a few general recommendations:

1. We recommend training coders to live-code in the same way (e.g. using the same number of fingers, having the same starting/resting locations.) Work with your team of experimenters to determine what they find easiest and most comfortable, and best limits coding mistakes.
2. Be consistent across live-coded studies in your lab as to whether the experimenter is coding looking directions from their _own_ perspective or from the _participant's_ perspective, whenever these differ.
3. Make sure that your key assignments relate to your BITTSy side names and actual physical locations in your testing room in a way that is clear and consistent for coders, as well as for you as you process data.
4. If you are setting up a cross-site study, coordinate with partner labs to use the same key assignments across testing sites to help experimenters be as consistent as possible.
5. If you are new to running visual fixation/HPP studies in your lab, your study runners will need to practice and typically meet a set reliability standard before testing subjects. Check with collaborators if they can share session videos and their coder data for training purposes. Ideally, these are videos of sessions run in BITTSy, where they can also share the protocol for your coders to use for practice.
