Skip to content

The experiment protocol string

Jump to bottom
Sibo Wang edited this page Apr 24, 2025 · 2 revisions

In some experiments, one might want to precisely specify a schedule by which optogenetic lights should be turned on and off, or when the recording should stop. We call this schedule an experiment protocol and specify it as a string.

A complete protocol string consists of zero or more instructions, separated by semicolons (;). Each instruction follows the format:

<frameNumber>/<channel>/<action>

where

  • <frameNumber> is a non-negative integer. The action of this instruction will be applied after this many frames have been collected by the behavior camera.
  • <channel> indicates which optogenetic light channel this instruction is for. It is one of "ch1", "ch2", or "x" (which indicates that no specific channel is involved and it used only when the action "stop").
  • <action> is one of "on" (turn the light on the aforementioned channel on), "off" (turn it off), or "stop" (stop recording altogether).

Note that <channel> is "x" if and only if <action> is "stop". "on" and "off" must be associated with "ch1" or "ch2" only.

Warning

Due to technical reasons, when the action is "stop", <frameNumber> should be a multiple of 3. If it is not, only $3 \times \text{floor}(\text{frameNumber} / 3)$ images will be captured (for example, is <frameNumber> is 10, the last only 9 frames will be recorded). We do not have this restriction on "on" and "off" operations on "ch1" and "ch2".

A non-empty protocol is a list of valid instructions, separated by semicolons:

<instruction1>;<instruction2>;...;<instructionN>

An empty protocol is represented as a single semicolon:

;

Tip

The following are some examples of valid experiment protocols:

Example 1:

100/ch1/on;200/ch1/off;300/x/stop

Meaning: Turn light on channel 1 on after the 100th frame; turn light on channel off after the 200th frame; then stop recording after the 300th frame.

Example 2:

99/x/stop

Meaning: Record 99 behavior frames; then stop.

Example 3:

100/ch1/on;200/ch1/off;200/ch2/on;300/ch2/off;300/x/stop

Meaning: Turn light on channel 1 on after the 100th frame; turn light on channel 1 off and turn light on channel 2 on after the 200th frame; then turn light on channel 2 off and stop recording after the 300th frame. Note that multiple actions can be taken at the same frame as long as the instructions are sorted by the frame number.

Example 4:

;

Meaning: No experiment protocol specified. The program will record until the user presses "Stop recording" on the GUI.

Clone this wiki locally