Goxpyriment: Go Framework for Behavioral Experiments
- Goxpyriment is an open-source framework designed to compile experiments into a single binary, ensuring cross-platform deployment and precise stimulus timing.
- It uses Go and SDL3 to provide an experimenter-oriented API with embedded assets and robust event-handling for reliable data collection.
- The framework emphasizes timing accuracy by leveraging hardware-synchronized timestamps and controlled garbage collection, ideal for lab-based studies.
Searching arXiv for the Goxpyriment paper and closely related framework context. Goxpyriment is an open-source software framework for programming behavioral and cognitive experiments in the Go programming language. It is designed for researchers in psychology, cognitive neuroscience, psychophysics, and related behavioral sciences who need laboratory experiments that are easy to deploy across testing machines while remaining attentive to stimulus timing and reaction-time measurement. The framework’s defining claim is that an entire experiment, including code and assets, can be compiled into a single, self-contained executable binary with zero runtime dependencies, while its programming interface remains explicitly experimenter-oriented and is inspired by Expyriment (Pallier et al., 16 Apr 2026).
1. Origins and design rationale
Goxpyriment was introduced in response to a practical problem in experimental laboratories: acceptable timing does not by itself solve the difficulties of installing, packaging, and reliably deploying experiments across multiple computers or collaborating laboratories. The framework is therefore positioned not merely as another stimulus-presentation library, but as a system that combines experimenter-friendly programming, deployment simplicity, and timing reliability (Pallier et al., 16 Apr 2026).
The paper situates Goxpyriment against three established ecosystems. MATLAB with Psychtoolbox historically provided a standard route for laboratory experiments and can offer good timing on well-configured hardware, but portability across operating systems is not seamless and MATLAB licensing can be expensive outside settings with academic access. Python, through frameworks such as Expyriment and PsychoPy, has become the dominant language for experiment programming and can achieve high-precision timing, including through the psychtoolbox Python module, but it introduces operational complexity through package managers, virtual environments, binary wheels, and cross-platform breakage. The paper gives as a concrete example the possibility that PsychoPy installation on Linux can fail when wxPython must be compiled and no prebuilt wheel exists. Web frameworks such as jsPsych and lab.js extend experimental reach to online settings, but browser event loops make sub-frame timing difficult or impossible.
Go was selected because it offers a distinct engineering profile. According to the paper, it compiles to native machine code for each target platform, can natively embed assets such as graphics, audio files, fonts, and stimulus lists, and produces self-contained binaries. The paper also presents Go as simple, strongly typed, and predictable, with fewer moving parts than Python and with an enforced coding style that reduces runtime debugging. On the timing side, Go’s garbage collector is concurrent and can be suspended during timing-critical sections. This suggests that Goxpyriment was conceived as much as a deployment and runtime-control strategy as a stimulus API.
2. Software architecture and programming model
Goxpyriment is centered on an Experiment object that manages the window, renderer, and audio subsystems. Program execution is wrapped in an Run callback that functions as a safety layer: if the participant presses Escape or closes the window, the framework catches the internal signal, flushes the data file safely to disk, and shuts down SDL subsystems cleanly. The paper presents this behavior as important for preventing silent data loss in aborted sessions (Pallier et al., 16 Apr 2026).
The framework supports, but does not require, a hierarchical organization into blocks and trials. This organization is directly inspired by Expyriment: trials are collections of factors that can be randomized and logged, and the programmer can iterate over blocks and trials in a structured way. Data output is handled by an exp.Data object that writes CSV files and includes metadata headers with operating system, hardware information, timestamps, and participant or session parameters. Participant information can be collected before the experiment window opens through an optional graphical GetParticipantInfo dialog, which supports subject IDs, condition choices from discrete menus, and settings such as fullscreen mode. The same information can also be supplied through command-line arguments.
The programming interface is explicitly described as inspired by Expyriment. Shared design elements include a central experiment object, a present()-based stimulus API, a structured trial-loop model, and CSV output with metadata. The principal differences are the use of Go instead of Python and SDL3 instead of the older Pygame/SDL2 stack. Goxpyriment also adds stream objects for tightly controlled stimulus sequences. A practical consequence is that the programmer does not need to construct and maintain an explicit event loop such as while True with manual polling and cleanup; exp.Run handles the event loop and cleanup internally. The paper characterizes this interface as “human friendly,” and it further argues that its linear and straightforward structure is advantageous for AI-assisted code generation. At the same time, the paper does not provide a full package-by-package module inventory, so a more detailed internal architecture is not specified.
3. Stimulus presentation, response handling, and hardware interfaces
The framework includes an array of visual stimuli, with the abstract naming text, shapes, images, Gabor patches, and motion clouds. The examples described in the paper suggest support for paradigms such as RSVP, masked priming, and retinotopy, although the paper does not enumerate every visual class in a formal API table (Pallier et al., 16 Apr 2026).
Presentation is tied to SDL3. The paper states that screen.Update() calls SDL’s SDL_RenderPresent; when VSYNC is enabled, this blocks until vertical retrace, and when VSYNC is disabled, the call returns immediately, which also allows support for variable refresh rate monitors. Beyond standard presentational primitives, Goxpyriment provides stream functions such as PresentStreamOfImages for dense, high-speed stimulus sequences, including retinotopic stimulation. These functions disable garbage collection, drain the event queue, and busy-wait at the sub-frame level to keep onsets accurate. They also generate a TimingLog containing target and actual onset times as well as the timing of keypresses during the stream.
Audio support includes WAV playback and tone generation. The timing tests described in the paper use repeated 50 ms tones presented at 2 Hz. No broader multichannel or general-purpose synthesis API is described. For response collection, Goxpyriment uses SDL3’s event system and presents a unified response device API. The technical discussion concentrates on keyboard input through GetKeyEventTS, whose return value includes KeyboardEvent.Timestamp. SDL3 is said to populate this timestamp from the operating system’s input subsystem at hardware-interrupt time, expressed as nanoseconds since SDL initialization. Generic support for mouse, joystick, and other input hardware is implied through SDL itself, but the paper does not attempt an exhaustive device-by-device survey.
The framework also includes generic functions for reading and writing parallel and serial ports, and it provides specific TTL input/output support for the DLP-IO-8 and for an Arduino Mega 2560 using a custom protocol. The paper additionally notes that Ethernet-based devices such as the LabJack T4 could avoid USB latency concerns and can be controlled from Go through a modbus library. This places Goxpyriment within the class of laboratory frameworks intended not only for screen-and-keyboard experiments, but also for experiments requiring triggers and external-device coordination.
4. Timing model and empirical characterization
Timing reliability is a major technical emphasis. The paper’s most distinctive claim is that response timing uses OS-level event timestamps rather than continuous polling loops. In practical terms, reaction time is computed from a response-event timestamp and a stimulus-presentation timestamp returned by Screen.FlipTS(), with both timestamps derived from the same clock. The standard formulation is therefore
The important point is not the arithmetic but the provenance of the timestamps: both are hardware- or OS-derived. Because the event retains its original timestamp in the queue, substantial computation can occur between stimulus onset and response handling without degrading the recorded response time. The paper nevertheless notes that hardware-level lags in the keyboard or mouse can still exist (Pallier et al., 16 Apr 2026).
Garbage collection is treated as a second timing hazard. Goxpyriment uses Go’s runtime API to suspend garbage collection during timing-critical loops, particularly in stream presentation functions. The paper does not present a formal latency model for the collector, but it clearly identifies explicit garbage-collector control as one of the framework’s differentiating technical features.
The repository includes a timing verification suite in tests/Timing-Tests/ for frame-interval jitter, single-frame flash reliability via photodiode, audiovisual stimulus onset asynchrony latencies, audio hardware-buffer pipeline latency, and USB-serial jitter of trigger devices. The benchmark table in the paper was obtained on a Raspberry Pi 4 with 2 GB RAM running Linux/arm64, connected over HDMI to a Dell 1905FP monitor at and 60 Hz. A Black Box Toolkit v3 captured optical, microphone, and TTL signals, and the only reported performance tweak was setting the usb_serial polling latency to its minimum possible value.
For the visual frames test, the target sequence was one frame on and two frames off, corresponding to a target duration of about 16.6 ms plus a 20 ms smoothing correction and a 50 ms SOA. Over 5000 samples, measured duration had median 37.5 ms, mean 37.6 ms, SD 0.23 ms, and range 1.5 ms; SOA had median 50.0 ms, mean 50.0 ms, SD 0.19 ms, and range 1.0 ms. The authors interpret this as evidence that not a single frame was skipped during five minutes of cycling. For the tones test, the target duration was 50 ms plus the same 20 ms smoothing correction and the target SOA was 500 ms. Measured duration was centered around 70.0 ms with SD 0.11 ms, but SOA varied from 490.5 to 512.2 ms with a bimodal distribution around approximately 490 and 510 ms; the paper states explicitly that this requires further investigation. For trigger output through the DLP-IO8-G device, target duration was 10 ms and target SOA 100 ms; measured duration mean was 10.3 ms with SD 0.11 ms and SOA mean 100.0 ms with SD 0.06 ms. Finally, simultaneous TTL, visual, and auditory lag measurements yielded TTL-to-optical lag around 31.4 ms mean with SD 1.89 ms and TTL-to-audio lag around 116.8 ms mean with SD 6.26 ms. The authors conclude that such lags are relatively stable and can be compensated in actual experiments, but they stress that lag values depend on the specific hardware and software configuration and must be measured for each setup.
5. Packaging, reproducibility, and the example corpus
Asset management is presented as one of Goxpyriment’s central advantages. Go can embed stimuli, experimental lists, fonts, graphics, and sound files directly into the executable. Combined with the fact that go-sdl3 embeds the prebuilt SDL3 runtime libraries into the binary, a Goxpyriment experiment can be shipped as a single statically linked executable with no external runtime dependencies. In operational terms, installation can be as simple as copying one file to the target machine (Pallier et al., 16 Apr 2026).
The paper frames this as a substantial reduction in overhead relative to Python workflows that depend on pip, conda, virtual environments, interpreter versions, and OS-specific packaging issues. Cross-compilation to target platforms is noted, although the paper does not provide a detailed build matrix or release-engineering pipeline. The reproducibility claim is correspondingly practical rather than formal: distribution is simplified because the executable contains the exact code and assets used in the experiment, thereby minimizing environment drift.
The repository includes more than forty example experiments and demos. The paper explicitly names Stroop, attentional blink using RSVP, masked priming, retinotopic mapping for fMRI, and adaptive threshold estimation using the QUEST algorithm. These examples function both as templates for human users and as a capability gallery for AI-assisted coding. The paper argues that Goxpyriment is “AI-friendly” because Go is simple and predictable, the language is strongly typed, exp.Run hides event-loop boilerplate, and asset embedding removes a common source of file-path errors. It also reports that some example-gallery experiments were largely generated by Claude or Gemini. The same discussion, however, explicitly warns that AI-generated code still requires human supervision, and it illustrates this warning with examples of incorrect AI-generated stimuli.
6. Comparative position and current limitations
Within the paper’s comparison table, Goxpyriment is placed alongside Expyriment, PsychoPy, Psychtoolbox for MATLAB, and jsPsych. Relative to Expyriment, it is the closest philosophical match: both provide a central experiment object, structured trials, present-based stimulus presentation, metadata-rich CSV output, and support for hardware triggers. The main differences are Go plus SDL3 rather than Python plus Pygame/SDL2, together with explicit garbage-collection control, variable refresh rate support, a unified response device API, and stream presentation objects (Pallier et al., 16 Apr 2026).
Relative to PsychoPy, the paper presents Goxpyriment as more limited in stimulus breadth and lacking a GUI experiment builder, but simpler in single-binary deployment and more explicit in garbage-collector control. Relative to Psychtoolbox, it avoids MATLAB licensing and emphasizes self-contained distribution, while making no claim to surpass Psychtoolbox’s timing capabilities in all situations. Relative to jsPsych, it offers stronger low-level timing, VSYNC synchronization, triggers, and local hardware integration, but it does not support online deployment. The comparison table rates its stimulus set as “moderate,” in contrast to the “extensive” stimulus sets attributed to PsychoPy and Psychtoolbox.
The paper is similarly explicit about current limitations. Video playback does not yet provide frame-accurate timestamps or hardware trigger outputs, and the authors identify precise onset timestamps plus trigger support during video playback as the highest priority for the next release, especially for EEG and fMRI use cases. There is currently no eye-tracker support. There is also no support for recording audio responses or videos, so naming-time paradigms that require speech-onset detection are not yet supported. Online deployment is unavailable; although Go can in principle compile to WebAssembly and SDL3 supports Emscripten, the authors state that the toolchain was too immature for practical use. A further limitation is sociotechnical rather than architectural: most researchers do not know Go, so adopting Goxpyriment requires learning a new language. The paper points to tutorials, examples, and a migration guide to mitigate that barrier. The framework is released under the GNU General Public License v3 and is freely available through its public repository.
