The user interface
Basics
When opening BITTSy, you will see a screen like this.
Version number - located in the top left. Main user interface buttons - Load Protocol File, Validate Protocol File, Event-Log Save Location, and Run Experiment; located in order on the left-hand side. Session information - Participant ID, Participant DOB, Experimenter Name (small boxes in the middle of the window) and Experimenter Comments (at the bottom left). These are filled by the experimenter with any necessary information, and make up the opening section of a run's log file. Protocol File - located on the right side. Once a protocol has been loaded, a copy is displayed here for reference. Errors in Protocol File - located in the middle left. Once a protocol is validated, any errors that BITTSy encounters will be displayed here. Run progress information - Current Phase, Current Trial, and Most Recent Key (located in the middle). This information is updated throughout the execution of the experiment and displayed for the experimenter's reference.
Loading a protocol file
Click Load Protocol File and browse to the correct folder. Select your protocol file and open it. Once a protocol is open, it will be displayed in the Protocol File box. This allows the experimenter to verify that they have selected the correct protocol, or review if there are special key assignments for live coding. (You can include comments at the beginning of your protocols with instructions or reminders for the experimenters in your lab; they will see them at this point!)
Validating a protocol
Validating a protocol checks that it is properly formed. This includes: that it has the necessary sections, that optional settings have been defined in a valid way, the devices named in your starting definitions are available (connected to your computer, powered on, and being recognized), your files are located in the indicated folders, steps of your experiment are properly formatted, and that tags that are referenced in action statements were previously defined. In other words, validation checks for things that would make your experiment crash in the middle if they weren't fixed before starting to run it!
Whenever BITTSy encounters a validation error, the error message(s) will be displayed in the Errors in Protocol File box to the left. For example, in the screenshot below, in its DISPLAYS ARE starting definition, the protocol defines one display for stimulus presentation and names it CENTER, but when the protocol was validated, the display was not powered on, so Windows reported to BITTSy that there was no additional display available to be assigned the CENTER label.
Whenever BITTSy encounters validation errors, it will prevent you from running the protocol. You will need to close out of BITTSy, fix the error(s), and reopen BITTSy to reload the protocol file and try validating it again.
When there are no errors found, a pop-up will tell you validation was successful, and you can move on with prepping to run the experiment.
What kinds of errors does validation not catch?
Validation primarily checks for formatting, and that the individual lines of your protocol have been specified with all of their fields being valid. Because protocol files can be written flexibly, and BITTSy doesn't recognize any particular protocol as a template of an established experimental paradigm, it will not display any warning or error about whether your protocol properly implements a specific paradigm.
Trial and phase start and end flags are considered optional, so BITTSy will not warn users when protocols lack them. However, misplaced or missing start/end flags for trials and phases can affect the execution of your experiment, particularly for habituation studies, and trial markers define sections in which key presses for live-coding should be expected and logged. Reviewing your protocol to ensure these are correctly placed is very important for any such experiment.
It is also important to verify that selection from groups, particularly via loops, produces valid available selections for the entirety of the experiment. For example, if a loop includes a TAKE statement from a group with 5 items, but the looped section can execute a total of more than 5 times, your experiment will encounter an error and halt when there are no valid selections remaining. Loops that are nondeterministic in the number of times that the looped steps are repeated (e.g. loops with an UNTIL condition that depends on the participant's looking time) should have an additional UNTIL condition that would limit the maximum number of iterations to an appropriate amount, preventing any error that could occur when no new stimulus could be selected.
It is also possible to specify a loop or step whose terminating condition cannot be satisfied, or could run for an impractical amount of time when certain conditions are met. BITTSy does not check for these during validation. For example, a step could require the participant to accumulate a set amount of time to a tag, but that tag is not active during that step - so they cannot accumulate any looking time at all. This step will run forever, and you will have to end execution by pressing escape. You could also test a particularly fussy child, and at a certain point wish to just throw out that trial and move on to the next part of the experiment - unless you specify an alternative end condition, such as a maximum amount of elapsed time or the experimenter pressing a key, the step will continue until the participant can accumulate the required looking time.
Why is it necessary to validate a protocol every time you load it?
Once your experiment is all set up and ready to be run, you might wonder why you still need to validate the protocol file every time you want to run it. Since the file is no longer changing, shouldn't it be okay to run without checking the protocol for errors, and shouldn't you be able to bypass validation?
We feel that it's a lot safer to require validation every time. Your protocol file could have been edited unintentionally, or a required file for your experiment could have been moved - or you could have simply forgotten to turn on the displays or lights used in your experiment. Without a validation step, BITTSy would not find these errors until it came time to execute that line that had a typo in it, or display a file that it couldn't find, or send a signal to a monitor or light that can't receive it - and each of these things would be a serious error in an experiment or could cause BITTSy to crash and the session to end early. Validation does a good job of checking the things that are most likely to change while a study is already finalized and running - namely, having the appropriate devices on and recognized by your computer at the time of running a session, and not having any files or folders accidentally moved or renamed - and gives you a chance to fix them while you're still getting ready for your participant, rather than having to drop the session for a technical error.
Filling in session information
The following information is saved automatically by BITTSy into the header of the log file from running your experiment, and does not need to be specified by the experimenter before starting the run:
filename and path of the protocol file (typically specifying the study and study version)
date and time that the experiment was started
BITTSy version that was used to run the protocol
The following fields can be filled in by the experimenter with whatever information is important for your lab/study:
participant ID
participant date of birth
experimenter's name/initials
additional comments (e.g. study version, task order, participant group)
Each of these boxes on the main BITTSy screen can be filled in or changed prior to running the experiment, but once the experiment starts, they will be locked from editing.
Saving the event log file
After validating, the next button to use is to specify where the event log will be saved, and what to call it. This log file will contain all of the information about the run, including the session information above, timing and stimulus presentation order, and looking times (if your experiment is live-coded). Click this and navigate to the folder you would like to save the log into, and specify a name for it. Typically, logs would be saved as something that uniquely identifies that session, such as a participant number. This run of the setup protocol is just being named "test". There is no need to specify a file extension - ".txt" will automatically be added.
Every log file will have a time stamp added to the end of its name that is the date and time the experiment was started. For example, the first text file in the file view above was a log file that was generated on 9/14/19 at 11:15 AM. This makes it impossible for any two log files to have the same name, and prevents new logs from overwriting or being confused with older logs in the same folder.
The log file is created as soon as Run Experiment is clicked, and BITTSy saves the basic session information into it. As the experiment progresses, BITTSy saves information to the log file automatically. When the experiment ends, no additional action is required to save the data.
Information is saved to the log file in chunks, so if BITTSy encounters an error during execution, it is possible for the in-progress step to not be logged. When the experimenter ends the study early by pressing escape, all lines that are waiting to be logged are pushed out at that time, so that no information from the end is missing. The log file will also record the time that the experiment was ended, and whether it was halted prematurely by the experimenter.
Running your experiment
Once these earlier steps have been completed, you are ready to start by clicking the run experiment button. This will start the execution of your experiment, beginning at STEP 1.
Throughout the run, BITTSy will display the most recent key that the experimenter has pressed. Whenever a trial or phase is ongoing, that information will also be displayed so that the experimenter can see how the study is progressing.
When you reach the end of the experiment, and do not encounter any errors along the way, you will see this pop-up.
If you need to stop the experiment early, you can do so by pressing the escape key.
Click OK, and then exit out of BITTSy.
Do not exit out of BITTSy while running an experiment without first pressing the escape key and waiting for the pop-up. This is important for two reasons. First, this ensures that any information from the run that has not yet been saved is written to the log file, and that the log file is properly saved and closed without risking file corruption. When the pop-up appears, you know that the process of writing information has been completed, and you can safely close the program. Second, this can cause a problem with controlling the lights on subsequent runs of BITTSy experiments, because BITTSy does not fully stop running when you close its window without also having stopped the experiment. (See here for info on how to fix this, if you accidentally do this!)
Last updated