Task Reference
Everything a task can use: the methods you write, the methods you can call, the attributes of the task and the Bpod primitives. Most of it is the same with Bpod, with an Arduino or with the Raspberry Pi alone; what only works with one of them is marked. For how to write a task, see Tasks (Bpod), Tasks (Arduino) and Tasks (Raspberry Only).
The methods you write
Method |
Called |
Use it to |
|---|---|---|
|
When the task is loaded. |
Call |
|
Once, before the first trial. |
Compute what the whole session needs: valve times, sounds, stimulus positions… Without Bpod, also open the connections the task needs (the serial port of the Arduino…). |
|
At the start of every trial. |
With Bpod: build the state machine of the trial with |
|
After every trial. |
Read |
|
Once, after the last trial (session finished, stopped, or error). |
Close files or connections. Usually |
Register water in every trial
Call self.register_value("water", ...) in every after_trial, with the microliters
delivered in the trial (0 if none). The system adds them up to know how much each
subject drinks, and raises an alarm if it is too little.
Methods you can call
All controllers
Method |
Use |
|---|---|
|
Saves a value in the trial’s row of the session file (a column named |
|
Records an event that happened on the Raspberry Pi (a camera detection, a touch…) with |
|
Runs direct function |
time_utils is imported with from village.scripts.time_utils import time_utils.
Without Bpod
With an Arduino, or with the Raspberry Pi alone (BEHAVIOR_CONTROLLER set to
OTHER), the task records the trial itself:
Method |
Use |
|---|---|
|
Required at the start of every trial, in |
|
Ends the trial. Optional: if |
|
Enters a state: closes the previous one and opens this one, as Bpod does. |
|
An event detected and timed by the controller (e.g. |
These methods, and register_raspberry_event, only record what happens between
register_start_trial and the end of the trial: anything registered outside that
window is ignored.
With Bpod
Method |
Use |
|---|---|
|
Adds a state to the trial’s state machine, see Bpod primitives. |
|
Configures a global timer, see Global timers. |
|
Configures a global counter. |
|
Configures a condition. |
|
Sends softcode |
Attributes
Attribute |
Type |
Description |
|---|---|---|
|
|
The subject’s training settings, defined in the training protocol (e.g. |
|
|
Calibrations, e.g. |
|
|
Everything that happened in the trial, available in |
|
|
The Bpod interface (see the methods above). Only with Bpod. |
|
|
Description of the task, shown when it is selected in the GUI. Set it in |
|
|
The name of the task, which is the name of its class (e.g. |
|
|
The name of the subject ( |
|
|
The number of the current trial, starting from 1. |
|
|
The name of the system ( |
|
|
The date and time the session started ( |
|
|
|
|
|
|
|
|
Set it to |
|
|
|
|
|
|
|
|
The state of the system, e.g. |
|
|
The box camera (see Camera). |
|
|
The GPIO output pin: |
|
|
The detection areas with a custom shape, if the project defines any (see Camera). |
You can also add your own attributes (self.side = "left"): they are kept from one
method to the next, and the triggers and direct functions can read them through
self.task.
Bpod primitives
BpodEvent and BpodOutput are imported together with TaskBase:
from village.custom_classes.task_base import BpodEvent, BpodOutput, TaskBase
A state is added with:
self.bpod.add_state(
state_name="light_on", # any name; "exit" ends the trial
state_timer=5, # seconds until the Tup event (0: no timer)
state_change_conditions={ # event -> next state
BpodEvent.Port2In: "reward",
BpodEvent.Tup: "exit",
},
output_actions=[(BpodOutput.PWM2, 255)], # what is on during the state
)
The trial starts in the first state added and ends when a transition goes to
"exit". Every state turns off all the outputs of the previous one and turns on only
its own output_actions, so there is no need to turn anything off. A state with
state_timer=0 and no Tup condition waits for its events indefinitely; with
state_timer=0 and a Tup condition, it fires its outputs and moves on at once.
Events
Used as keys of state_change_conditions:
Event |
When it happens |
|---|---|
|
The state’s timer ( |
|
The animal pokes into port N (its infrared beam is broken). |
|
The animal leaves port N. |
|
A TTL signal on a BNC input goes high or low. |
|
The Raspberry Pi sent that softcode with |
|
A global timer starts or ends. |
|
A global counter reaches its threshold. |
|
A condition is true. |
Outputs
Used in output_actions:
Output |
What it does |
|---|---|
|
Turns on the LED of port N with an intensity from 0 to 255. |
|
Opens the valve of port N during the state: use the valve time as |
|
Sets a BNC output high (a TTL to another device) during the state. |
|
Makes the Raspberry Pi run direct function N, at the moment the state starts. |
|
Starts a global timer. |
|
Cancels a global timer. |
|
Resets a global counter to 0. |
bpod_outputs_and_events.py shows the ports, LEDs, valves and softcodes in a single task.
Softcodes
While Bpod runs a trial, the task’s Python code is waiting. Softcodes connect the Raspberry Pi and Bpod during the trial, in both directions:
Bpod → Raspberry Pi:
BpodOutput.SoftCodeNin theoutput_actionsof a state runs direct function N on the Raspberry Pi when the state starts: to play a sound, show an image… See Playing a sound and Direct Functions.Raspberry Pi → Bpod:
self.bpod.send_softcode_to_bpod(N)produces the eventBpodEvent.SoftCodeNin the state machine, so the trial can react to something only the Raspberry Pi sees. It is usually sent from a trigger (which reaches the task asself.task). For example, to give water when the animal enters box area 1, incamera_trigger.py:class CameraTrigger(CameraTriggerBase): def __init__(self) -> None: super().__init__() self.inside = False def trigger(self, cam: Camera) -> None: if cam.name != "BOX": return # only when the animal enters, not on every frame while it is inside if cam.area1_is_triggered and not self.inside: self.task.bpod.send_softcode_to_bpod(1) self.inside = cam.area1_is_triggered
and in the task, a state that waits for it:
self.bpod.add_state( state_name="wait_area1", state_timer=60, state_change_conditions={ BpodEvent.SoftCode1: "reward", # sent by camera_trigger.py BpodEvent.Tup: "exit", }, output_actions=[], )
See bpod_area2_sound.py for the camera, and bpod_touchscreen.py for the touchscreen.
Global timers, counters and conditions
They are configured in create_trial, before or after adding the states, and are
used by all the states of the trial:
Global timers (1 to 5): a timer that keeps running across states, independently of each state’s own timer, e.g. a deadline for the whole trial. Configure it with
self.bpod.set_global_timer(timer_id=1, timer_duration=10), start it with the outputBpodOutput.GlobalTimer1Trigand react toBpodEvent.GlobalTimer1End. See bpod_global_timer.py.Global counters (1 to 5): count an event across states. Configure it with
self.bpod.set_global_counter(counter_number=1, target_event=BpodEvent.Port2In, threshold=5)and react toBpodEvent.GlobalCounter1End, which happens when the event has happened 5 times.Conditions (1 to 16): check the current level of an input at the moment of a transition, instead of reacting to a change. Configure it with
self.bpod.set_condition(condition_number=1, condition_channel="Port2", channel_value=1)(true while the animal is in port 2) and useBpodEvent.Condition1instate_change_conditions.
For more details and for Bpod modules, see the Bpod documentation.
Ending the session from the task
Set self.force_stop = True to end the session. The session ends at once, so set it
in after_trial, when the trial is already complete: set during a trial (from a
trigger or a direct function), it cuts that trial. It works in Auto mode too: the
session is saved and the subject is let out, as when maximum_duration is reached,
even before minimum_duration. For example, to stop after a maximum number of trials
(max_trials defined in the training protocol):
def after_trial(self):
...
if self.current_trial >= self.settings.max_trials:
self.force_stop = True
The same works for any criterion: an amount of water, a number of correct trials…