API References

This is the reference for classes (CamelCase names) and functions (underscore_case names) of stimuli grouped thematically.

Audio

The audio module provides classes for generating standard audio stimuli and for loading existing files.

Sound generation

Standard sounds can be generated like noise, amplitude modulated sounds or pure tones.

Noise(color, volume, duration[, ...])	Colored noise stimulus.
SoundAM(frequency_carrier, ...[, ...])	Amplitude modulated sound.
Tone(frequency, volume, duration[, ...])	Pure tone stimulus at a given frequency.

Example usage:

from stimuli.audio import Noise

sound = Noise(color="pink", volume=50, duration=1)
sound.play(when=0.2)  # schedule in 200 ms

Sound files

For more complex stimuli, the sounds can be loaded from files.

Sound(fname[, device, backend, clock])

Auditory stimulus loaded from a file.

Example usage:

from stimuli.audio import Sound

sound = Sound("path/to/sound.wav")
sound.play(when=0.2)  # schedule in 200 ms

Backend

The audio module uses the sounddevice library with a callback function to play the sounds.

SoundSD(device, sample_rate, *[, clock])

Sounddevice backend for audio playback.

Trigger

To mark events in time during an experiment, you can use triggers. For instance, you can mark the onset of a sound. The triggers defined in stimuli uses one byte to encode the trigger value, i.e. the trigger value must be between 1 and 255 (except for the LSLTrigger which uses a trigger value between 1 and 127).

MockTrigger()	Mock trigger class.
LSLTrigger(name)	Trigger sending values on an LSL outlet.
ParallelPortTrigger(address[, port_type, delay])	Trigger using a parallel port (also called LPT port).

Example usage:

from stimuli.trigger import ParallelPortTrigger

trigger = ParallelPortTrigger("/dev/parport0")
trigger.signal(1)  # send trigger value 1

Arduino to Parallel Port converter

Parallel ports are less and less common on computers, and are not supported by macOS. Instead, the Fondation Campus Biotech Geneva developed a USB to parallel port converter using an arduino.

The details can be found on this repository: https://github.com/fcbg-platforms/arduino-trigger

This converter can be used with the ParallelPortTrigger class by specifying the path to the serial port connected to the arduino or by using the str "arduino" for automatic detection.

Time

The python time module is not accurate enough for precise timing in experiments. The stimuli package provides a more accurate clock, the Clock class, which uses time.perf_counter() or time.monotonic_ns() depending on which has the highest resolution. The sleeping function stimuli.time.sleep() replaces the standard time.sleep() function and make use of the clock from stimuli to achieve a better precision.

Clock()	Clock which keeps track of time in nanoseconds.
sleep(duration, *[, clock])	High precision sleep function.

Sleep performance (linux):

%timeit time.sleep(0.0005)
556 μs ± 131 ns per loop (mean ± std. dev. of 7 runs, 1,000 loops each)

%timeit stimuli.time.sleep(0.0005)
501 μs ± 77.5 ns per loop (mean ± std. dev. of 7 runs, 1,000 loops each)

Example usage:

from stimuli.audio import Tone
from stimuli.trigger import ParallelPortTrigger
from stimuli.time import sleep

sound = Tone(frequency=1000, volume=25, duratin=0.5)
trigger = ParallelPortTrigger("/dev/parport0")

sound.play(when=0.2)
sleep(0.2)
trigger.signal(1)

Regardless of the function used, stimuli is still limited by the accuracy of the on-board computer clock. If you have access to a more accurate clock, you can subclass the abstract class BaseClock to implement your own clock.

BaseClock()

Base class for high precision clocks.

Many objects and functions in stimuli have a clock argument which supports any BaseClock subclass.

Utilities

Logging utilities are available to interact with stimuli logger.

add_file_handler	Add a file handler to the logger.
set_log_level	Set the log level for the logger.

Development utilities are available to help debug a setup.

sys_info

Print the system information for debugging.