Detailed log files

Log files are created as you begin to run a protocol, and record the timing of every event in the study session. One of the steps before running a protocol is to specify the save location and name of the log file for that session.

What is in a log file?

Header section

The first portion of any log file contains information about the session, most of it input by the experimenter in the blanks for subject number, date of birth, experimenter name/initials, and comments. It also indicates which version of BITTSy was used to run the protocol, the name and location of the protocol file, and the test date and run time. This information is saved to the log file immediately upon clicking to run the protocol.

An example of the header section of a log file is below (personal information has been replaced with ▢ symbols).

Experiment settings

The next section of a log file records the experiment settings that are important for analyzing looking time and habituation. These can be a useful reference, especially when default values are used for some settings, as they may or may not be explicitly stated in the protocol file itself.

In the example below, the protocol did not specify any changes from the default settings. None of the habituation-specific settings were utilized in this study, but their values are consistently recorded in log files.

Experiment events

The main contents of the log file follow these two opening sections, and detail what happened in the study session and when.

The example log below is from the start of a headturn preference study similar to this example protocol.

Every line in a log file begins with a timestamp, accurate to the nearest millisecond. These are used by the reporting module to generate summaries of the events in the study session and calculate looking times. Some lines (particularly those for beginning the presentation of stimuli) also end in a number denoting the elapsed milliseconds since the start of the experiment, with an even higher degree of accuracy.

As soon as the protocol file begins execution, we define the start of a phase (called "Train"), and start the center light blinking. This continues until the experimenter presses the key C. (In the log below, you can see that it takes the infant a few seconds to orient - note the gap in timestamps between the first "stimuli light blink" line and "C pressed".) Then the center light is turned off, and we randomly select a side (LEFT or RIGHT) from a group called trainingsides, and start to blink the light on that side (here, LEFT was chosen).

There are a lot of events to log in a typical study - in the example above, we logged 20 before even starting the first trial! BITTSy does not make any assumptions about what information will be important or unimportant for later analyses, so we opt for logging all possible information. As a consequence, log files often are quite long, and not terribly human-readable. This is why we supply a set of standard reporting functions that read log files and output commonly-used measures suitable for analyzing HPP, preferential looking, central fixation, and habituation studies.

Important notes about log files

While you'll most often be working with summary reports rather than looking at log files directly, there are some important things to understand about how log files are generated and what they record.

1. Log files remain open throughout a session, and events are written to the log in real time (or with a slight delay). Writing to log files as events happen, rather than generating a full log file after the run, helps ensure that as much information on a study session as possible is available in case something unexpected occurs, such as encountering an error. Sometimes the most recent few long lines are held in a "buffer" and written to the log file in batches. The log file is not finished and closed until execution ends. This means it is important to always end execution properly (by pressing Escape) before closing out of BITTSy - it ensures that the final batch of lines can be written to the log.

2. Header information is written immediately, and cannot subsequently be changed within the user interface's text boxes. The text fields on the user interface for the subject number, date of birth, experimenter, and comments should all be filled in with any necessary information prior to running the study so that they are included in the log file.

3. The last lines of a log file denote how execution stopped (ended, by reaching the end of the protocol; prematurely, by the experimenter pressing the Escape key; or unexpectedly, by BITTSy encountering an error) This can be reviewed to verify that an experiment ran fully to completion, especially in the case of missing lab-internal notes from an experimenter about how a session went. Note that the line specifying an unexpected end can only be written by BITTSy if the error is not so critical that it causes the program to close or lose access to the log file. Execution errors will typically end in BITTSy displaying a pop-up with an explanation of the error as the session is ended. (For example, this will occur if your protocol attempts to make a selection from a group in which no items are eligible for selection.) However, issues such as closing out of BITTSy without first ending the experiment, having your computer suddenly shut down due to power loss, or encountering an uncaught validation error that causes BITTSy to crash can result in this final line not being written to the log (see #1 above). Any log file that is missing a line denoting how the experiment ended should be assumed to be unexpected, and may be additionally missing experiment events that happened immediately beforehand.