The Expyriment library follows a strict modular and object-oriented structure. It is organized into five packages, focusing on different areas of an experimental setting. After importing Expyriment in a Python script or interactive session, the following subpackages become available: design, stimuli, io, misc, and control. Each package consists of classes, methods, or further modules. Figure 1 provides a graphical overview of the library.
In Expyriment, all subpackages have a defaults module that contains variables describing the default values for most classes and certain global settings within that package. That is, for each class, the default values of optional arguments that can be specified during instantiation are set via variables in the default module. Importantly, these default values can be overwritten by the user in order to make specific global settings for each experiment.
The design, stimuli, and io packages allow for the integration of user-written plugins (called extras) in order to extend Expyriment with, for example, specific randomization procedures, more advanced stimuli or custom-made response devices. The role and functionality of each package can be summarized as follows.
The design package provides classes describing experimental structures. The main role of this package lies in the specification of experimental designs. This is done by building a hierarchical relation between an experiment, the experimental blocks, and the experimental trials, and by specifying between- as well as within-subjects factors. On the basis of this specification, the design package is further capable of randomizing or permuting the experimental blocks or trials within the defined experiment. As a simple example, consider that you want to create an experiment with two blocks, each containing 60 randomized trials of three different conditions A, B, C:
Importantly, designs can be exported to text files [by calling in the example above]. When specified without using any Expyriment presentation feature, such as stimulus objects,Footnote 4 the design package can be used in combination with other Python libraries or programming environments for stimulus presentation that either do not offer experimental design structures (e.g., Vision Egg) or that rely mainly on importing externally created designs (e.g., PsychoPy, using its function). Using an interactive Python session, Expyriment can therefore also help researchers to formalize and review complex designs or randomizations.
The stimuli package provides classes for a variety of experimental visual as well as auditory stimuli. The role of this package thus lies in the definition and creation of stimuli. Once a stimulus is created, it can be integrated into the hierarchical design structure, completing the definition of the experiment. Importantly, stimuli can be automatically presented on the display and do not rely on a separate external presenter—for example,
To create more complex visual scenes, visual stimuli can also be plotted on other stimuli. The resulting combined stimulus can then be preloaded and/or presented as a whole. This always ensures precise timing, even for complex stimuli:
Another way to achieve the simultaneous presentation of several stimuli is to consecutively present them without clearing the display contents and only to update the display after the presentation of the last stimulus:
Although the first method is often preferable, since it allows for reducing visual scenes into a single object, the second method can be useful when a screen has to be built up by incrementally adding stimuli—for instance, on the basis of user input.
Updating the screen can also be done explicitly by calling the method of the screen object (see the Expyriment.control section below). If you want to maximize the speed with which your stimulus appears on the screen, in some cases this might require updating only that part of the screen on which the stimulus appears. This is possible by calling the method of the screen object and specifying a list of stimuli to update as an argument. Note, however, that this will only work as expected when OpenGL mode is switched off (see the Software evaluation and timing section below).
The io package provides classes for handling input and output. Its main role is to facilitate communication with external devices (e.g., keyboard, button box, etc.), as well as to handle log files. Most io classes can also be used independently from the other Expyriment packages—for example,
The main role of the misc package is to provide additional functionality that goes beyond the scope of the other packages—for instance, the functionality to preprocess the acquired data files for use in further statistical software (see the Additional features section below). This functionality does not depend on Expyriment-specific data and thus can easily be integrated into existing Python code—for example,
The task of the control package is to control the implementation of a formerly defined experiment. It provides the three important functions to initialize, start, and end an experiment and facilitates interaction with the display, clock, and keyboard, as well as with data and event files, by automatically integrating them into the current experiment definition. With a complete hierarchically structured definition of an experiment, conducting the experiment consists of nothing more than sequentially iterating over the hierarchical structure.
The control package plays a central role for the processing of experiment code, since it is involved in the building of the scaffolding of each Expyriment program. A typical script comprises three central commands, which can be described as the crucial landmarks for the flow of the experimental control program:
Landmark 1 initializes an experiment. If no object is given as a parameter, a new experiment is automatically created and returned by this function. Experiment initialization will create a screen object representing the computer’s display (available as ), a keyboard input device object to receive input from the keyboard (available as ), an event log file object that automatically logs stimulus presentation times and device communication in the background (available as ), and an experimental clock object providing timing functionality (available as ). After this landmark, the experimental design hierarchy and the experimental stimuli can be created. Landmark 2 starts the currently initialized experiment. This will ask for a subject ID on the display (afterward available as ) and create a data file object that can be used to log experimental variables on a trial-by-trial basis (available as ). After this landmark, the experiment can be conducted by iterating over the hierarchical design (see below). Landmark 3 ends an experiment, which will close the screen and save all unwritten log files to disk.
The control package also includes the Expyriment test suite (see the Additional features section below), as well as some global settings concerning the execution of the experiment (e.g., display, audio, and event-logging settings, set via the defaults module).
When using software to control the implementation of a scientific experiment, it is absolutely necessary to guarantee proper functioning. The Expyriment test suite is a visually guided tool for testing several aspects of Expyriment on a specific system. The tests include timing accuracy of visual stimulus presentation, audio playback functionality, mouse functionality, and serial port functionality/use. Eventually, all test results can be saved as a protocol, together with various information about the system that Expyriment is running on. The test suite can be started by calling . We strongly recommend always using the test suite before testing participants, in order to guarantee proper functioning.
During the development of an experiment, it can be convenient to change some of the default settings in the control package—such as starting the experiment in a small window (instead of occupying the full screen), suppressing the startup and ending messages, automatically creating successive subject IDs (without asking for one), and switching off time stamps for output files. To conveniently activate all of these common settings at once, the control package allows for switching into a dedicated development mode by calling before initializing an experiment.
Command line interface
Expyriment comes with a command line interface that allows for starting the test suite, a graphical tool to browse the application programming interface reference, as well as making specific settings (e.g., running in develop mode) for a single execution of an Expyriment script, without manipulating the script file. A full description of the available options can be obtained by typing from a command line.
In most cases, the data acquired by Expyriment needs to be processed further before a statistical analysis can be performed. This processing entails aggregation of the dependent variables over all factor-level combinations of the experimental design. Expyriment provides an easy, but flexible way to automatize this process with the data preprocessing module included in the misc package (). Further information can be found in the Expyriment online documentation. The Expyriment website also provides an R script for conveniently reading the Expyriment data files of several subjects into a single R data frame.