task

Classes

BpodEvent()	Enumeration of Bpod event names.
BpodOutput()	Enumeration of Bpod output channels.
Task()	Base class for defining behavioral tasks.

Exceptions

TaskError(message)

Exception raised for errors in the Task class.

exception TaskError(message)

Bases: Exception

Exception raised for errors in the Task class.

class BpodEvent

Bases: EventName

Enumeration of Bpod event names.

class BpodOutput

Bases: OutputChannel

Enumeration of Bpod output channels.

class Task

Bases: object

Base class for defining behavioral tasks.

Subclass Task to implement your own task. You must override four methods and may optionally call helper methods and read certain attributes during execution.

────────────────────────────────────────────────────────── METHODS YOU MUST OVERRIDE ──────────────────────────────────────────────────────────

start(self) -> None

Called once before the trial loop begins. Use it to configure hardware, pre-compute stimuli, open files, etc.

create_trial(self) -> None

Called at the beginning of every trial. Build and send the Bpod state machine here (or set up stimuli for non-Bpod controllers). The state machine runs to completion before after_trial is called.

after_trial(self) -> None

Called immediately after each trial finishes. Use it to score the animal’s performance, update adaptive parameters, and call register_value to save custom columns to the data file. self.trial_data is already populated at this point.

close(self) -> None

Called once after the trial loop ends (session finished, forced stop, or error). Use it to close files, stop hardware, release resources.

────────────────────────────────────────────────────────── METHODS YOU CAN CALL (do not override) ──────────────────────────────────────────────────────────

register_value(name: str, value: Any) -> None

Saves a custom value to the current trial row in the CSV. Call this inside after_trial.

Example:

self.register_value("correct", 1)
self.register_value("response_time", 0.432)

────────────────────────────────────────────────────────── ATTRIBUTES YOU CAN READ INSIDE YOUR TASK ──────────────────────────────────────────────────────────

self.trial_datadict

Dictionary populated automatically after each trial with Bpod event timestamps and any values previously registered via register_value. Available inside after_trial to drive adaptive logic.

Typical keys: "trial", "subject", "task", "date", "system_name", plus every key you have registered with register_value.

Example:

def after_trial(self):
    if self.trial_data.get("correct") == 1:
        self.settings.difficulty += 1

self.current_trialint

1-based index of the trial that just ran (available in both create_trial and after_trial).

self.subjectstr

Name of the subject running the session.

self.settingsSettings

Object that holds all the session parameters defined in the training protocol. Read and write its attributes to implement adaptive training.

self.sound_calibration.get_sound_gain(speaker, dB, sound_name)

to convert a target dB level into a hardware gain value.

Example:

gain = self.sound_calibration.get_sound_gain(
    speaker=1, dB=65.0, sound_name="white_noise"
)

self.water_calibration.get_valve_time(port, volume)

to convert a target volume (µl) into the valve open time (seconds).

Example:

valve_time = self.water_calibration.get_valve_time(
    port=1, volume=5.0  # 5 µl
)

self.bpodBpodController

Low-level Bpod interface (state machine construction, sending, etc.). Primarily used inside create_trial.

self.arduinoArduinoController

Arduino interface for tasks that use an Arduino instead of Bpod.

self.cam_boxCamera | NullCamera

Camera attached to the behaviour box (NullCamera if not configured).

start() → None

Starts the task. Must be overridden by subclasses.

create_trial() → None

Creates the state machine for the current trial. Must be overridden.

after_trial() → None

Executed after each trial completes. Must be overridden.

close() → None

Closes the task and releases resources. Must be overridden.

register_value(name: str, value: Any) → None

Registers a custom value to be saved with the trial data.

Parameters:

• name (str) – The name of the value (column header).

• value (Any) – The value to store.

execute_function(i: int) → None

Executes a registered function.

Parameters:

i (int) – The function index (1-99).

run_in_thread(daemon: bool = True) → None

Runs the task in a separate background thread.

Parameters:

• daemon (bool, optional) – Whether to run as a daemon thread.

• True. (Defaults to)

run() → None

Runs the task in the main thread until completion or forced stop.

do_trial() → None

Executes a single trial.

Initializes the state machine, runs it, collects data, and performs post-trial updates.

concatenate_trial_data() → None

Appends the current trial’s data to the session DataFrame.

disconnect_and_save(run_mode: str) → Tuple[Save, float, int, int, str]

Stops the task, disconnects devices, and saves session data.

Parameters:

run_mode (str) – The mode in which the task was run (e.g., “Manual”).

Returns:

A tuple containing the save status, session duration, number of trials, water consumed, and settings string.

Return type:

Tuple[Save, float, int, int, str]

save_json(run_mode: str) → str

Saves the session settings to a JSON file.

Parameters:

run_mode (str) – The execution mode string.

Returns:

The JSON string containing the settings.

Return type:

str

save_csv(run_mode: str) → Tuple[float, int, int, bool]

Saves the session data to CSV files.

Processes raw data, saves raw and clean session files, and updates the subject’s cumulative data file.

Parameters:

run_mode (str) – The execution mode string.

Returns:

Duration, trial count, water consumed, and success status.

Return type:

Tuple[float, int, int, bool]

classmethod get_name() → str

Returns the name of the task class.

create_paths() → None

Sets up file and directory paths for the session.