Stimulus playlists

Define outputs for NI-daq.

Playlist format

Playlists are tables saved as tab-delimited text files:

stimFileName	silencePre	silencePost	intensity	freq
superstimulus.wav	1000	1000	1.0	100
SIN_100_0_3000	1000	1000	1.0	100
[mediocre_stim.wav, MIRROR_LED]	1000	1000	1.0	100
[PUL_5_10_10_0, SIN_200_0_2000]	1000	1000	1.0	100
[SIN_100_0_3000, SIN_200_0_2000]	1000	1000	1.0	100
[SIN_100_0_3000, SIN_200_0_2000]	[1000, 1000]	[1000, 1000]	[1.0, 1.0]	[100, 100]
[SIN_100_0_3000, SIN_200_0_2000]	[1000, 2000]	[2000, 1000]	[1.0, 2.0]	[100, 200]

The first row is a header that contain the following column names:

• stimFileName: If not a magic name, full filename (w/ extension but w/o directory). File needs to be single-channel *.wav, placed in the stimfolder defined in the global configuration file. Currently defined magic names are: SIN*, PUL*, MIRROR_LED, CLOCK, SI_START, SI_STOP, SCANIMAGE_NEXT (see below for details). If you specified multiple output channels (analog and digital) in your protocol, you must provide one stimulus filename per channel.

• silencePre (ms): zeros pre-pended to the stimulus

• silencePost (ms): zeros post-pended to the stimulus

• intensity (mm/s or dB for sound, mW/mm2 for light): Stimulus intensity.

• freq (Hz for sound or nm for light): Used as a key into the calibration files

Each row in the playlist defines one trial, with a total duration of silencePre + “duration of stimulus” + silencePost. For multi-channel outputs in which the stimuli have different durations, the total duration is set by the duration of the longest stimulus across all channels. Shorter stimuli will be zero-padded the end.

Defining multi-channel stimulation

• For the stimFileName column: One entry per channel, as a bracketed, comma-separated list, [stim_on_chan1, stim_on_chan2, ...]. Analog and digital output channels are concatenated, starting with the analog outputs and ending with the digital outputs. E.g. if you define two analog output channels and one digital output channel in your protocol, then the stimuli will map as follow [stim_first_analog_out, stim_second_analog_out, stim_digital_out]. Whitespace surrounding stimulus names is stripped.

• The remaining columns in the playlist can be provided as as bracketed comma-separated lists of values, [1, 0.2, 2], to set different intensities etc. for each channel. If fewer entries than channels, then the list will be padded to the number of channels with the last entry in the list.

Magic stimulus names

The stimulus name can point to a wav file with the predefined waveform in the ethoconfig/stim. However, there are magic names for stimuli that are created on demand. They start with prefix and allow you to specify stimulus parameters in the filename:

• SIN_frequency_phase_duration: Generate sinusoid with frequency (Hz), phase (rad), and duration (ms) specified in the stimulus name. Will start after silencePre and end before silencePost. E.g. SIN_100_0_1000 will produce a sinusoid with a frequency of 100Hz, a phase of 0, and duration of 1000ms.

• PUL_pulseDur_pulsePau_pulseNumber_pulseDelay: Generate pulse train (square pulses) with pulse duration, pause, number and intial delay specified in stimulus name (all time units in ms). Will start after silencePre and end before silencePost.

• MIRROR_LED: Will mirror the stimulus in the first channel that does not as a pulse train (pdur & ppau 5ms). Will start after silencePre and end before silencePost.

• CLOCK_pulseDur_pulsePau: Create a clock signal (for instance for continuously triggering frames). Generate continuous pulse train with pulse duration and pause specified in stimulus name (all time units in ms). Will start after sample 0 (not silencePre) and end at the last sample (not before silencePost).

• SI_START, SI_STOP, SI_NEXT: Will add start acquisition, stop acquisition and next file triggers for remote controlling scanimage to the channel. All three stimuli should be specified in the playlist for each stimulus, not just the first or the last one. This will make sure that e.g. starts are triggered even with shuffled playback:

  • SI_START will set the digital output to 1 for the first 2ms of the trial (starting at sample 0, not at silencePre)

  • SI_STOP and SI_NEXT will set the last 2ms of the trial (not before silencePost) to 1. Scanimage should be configured for external triggering with the correct digital channels. The start trigger should be set to “rising”, the stop and next triggers to “falling”. See ScanImage docs for details.