goxpyriment

module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 24, 2026 License: GPL-3.0

README

goxpyriment

goxpyriment is a high-level Go framework for building behavioral and psychological experiments.

If you are looking for a simpler, no-code experiment generator, check Gostim2.

Goxpyriment relies on the libsdl library through the go-sdl3 bindings. (While Python is easy, Go is simple: read Go-vs-Python). The code was mostly written using Claude Sonnet 4.6, with some input from Gemini 2.5 flash.

As its name suggests, goxpyriment was inspired by expyriment.org, a nice, light-weight Python library for cognitive and neuroscientic experiments (See Krause, F., & Lindemann, O. (2014). Behavior Research Methods, 46(2), 416–428. https://doi.org/10.3758/s13428-013-0390-6). The API should feel very familiar to expyriment users.

If you use this softawre in a scientific paper, please cite as:

⚠ This software is in beta-testing: although it is certainly possible to use it to implement real experiments in the lab, users should (as always) very carefully check their behavior, for example with a bbtk. Please report bugs and suggestions at https://github.com/chrplr/goxpyriment/issues

chrplr

How to write your own experiment, in a nutshell

  1. Install Go on your machine (see https://go.dev/doc/install).
  2. Clone this repository (git clone https://github.com/chrplr/goxpyriment.git or download ZIP).
  3. Browse ./examples/ to see source code of experiments and the documentation :
  4. Create a folder for your experiment and start coding in a main.go file. You can test it by running go run main.go.

[!TIP] Vibe-coding: Launch an AI coding agent (Claude, Gemini, etc.) inside the goxpyriment folder and ask it to add a new experiment to the examples folder — this leads the agent to read the existing examples for context. Describe the experiment (stimuli, design, etc.) in plain language and enjoy. Recommendation: save your prompt in a description.md file alongside the code. 5. Once satisfied with the code, compile your experiment into an executable with go build .. This executable will run on any machine with the same OS and architecture. 6. If you need to distribute your experiment to colleagues who use another operating system or architecture, you can cross-compile. For example, to produce code for a Raspberry-Pi:

env GOOS=linux GOARCH=arm64 go build .
Demos
Binaries

There are many programs, my suggestion is to start with Memory_span, Change_Blindess, retinotopy,...

Most examples accept -d (windowed 1024×768 developer mode) and -s <id> (subject ID written to the .xpd data file).

Source code

The source code of these demos can be browsed at ./examples/.

If Go is installed on your computer, and you have run go get github.com/chrplr/goxpyriment, you can run any example directly from a clone of the goxpyriment repository, for example:

go run ./examples/parity_decision/ -d -s 1

Or:

cd examples/hello_world
go run .            # fullscreen by default
go run . -d         # windowed 1024×768 (developer mode)
go run . -d -s 1    # windowed, subject ID = 1
go build .          # build a standalone binary

To build all examples at once:

cd examples
./build.sh

📝 Report bugs and suggestions at https://github.com/chrplr/goxpyriment/issues

License

This project is licensed under the GNU Public License v3 - see the LICENSE file for details.

Directories

Path Synopsis
Package clock provides timing helpers: Wait, GetTime, and a Clock for measuring durations and sleeping until a target offset.
 Package clock provides timing helpers: Wait, GetTime, and a Clock for measuring durations and sleeping until a target offset.
cmd
get-display-info command
get-display-info queries every connected display via SDL3 and prints its properties: name, bounds, current mode, desktop mode, content scale, orientation, and the full list of available fullscreen resolutions.
 get-display-info queries every connected display via SDL3 and prints its properties: name, bounds, current mode, desktop mode, content scale, orientation, and the full list of available fullscreen resolutions.
Package control manages the overall state and initialization of an experiment.
 Package control manages the overall state and initialization of an experiment.
Package design provides experiment structure types (trials, blocks, factors) and randomization helpers for building experiment designs.
 Package design provides experiment structure types (trials, blocks, factors) and randomization helpers for building experiment designs.
Package geometry provides point/distance and coordinate conversion helpers (Euclidean distance, Cartesian–polar conversion, degree–radian).
 Package geometry provides point/distance and coordinate conversion helpers (Euclidean distance, Cartesian–polar conversion, degree–radian).
Package io provides the low-level input/output subsystems for goxpyriment:
 Package io provides the low-level input/output subsystems for goxpyriment:
Package staircase implements adaptive psychophysical threshold estimation.
 Package staircase implements adaptive psychophysical threshold estimation.
Package triggers provides hardware trigger interfaces for synchronising stimuli with external recording equipment (EEG amplifiers, oscilloscopes, photodiodes).
 Package triggers provides hardware trigger interfaces for synchronising stimuli with external recording equipment (EEG amplifiers, oscilloscopes, photodiodes).
Package units provides unit conversions for vision-science experiments.
 Package units provides unit conversions for vision-science experiments.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.