Task

Bases: object

Base class for defining and running behavioral tasks using Bpod.

This class provides the infrastructure for task management, including communication with Bpod, data logging, session management, and integration with other devices like cameras and sound systems.

__init__() → None[source]: Initializes the Task instance with default settings and components.

Methods

`__init__`()	Initializes the Task instance with default settings and components.
`after_trial`()	Executed after each trial completes.
`close`()	Closes the task and releases resources.
`concatenate_trial_data`()	Appends the current trial's data to the session DataFrame.
`create_paths`()	Sets up file and directory paths for the session.
`create_trial`()	Creates the state machine for the current trial.
`disconnect_and_save`(run_mode)	Stops the task, disconnects devices, and saves session data.
`do_trial`([send_to_cam])	Executes a single trial.
`get_name`()	Returns the name of the task class.
`get_trial_data`()	Retrieves and processes data from the last executed trial.
`register_default_values`()	Registers standard session metadata values (task, subject, system, date).
`register_value`(name, value)	Registers a custom value to be saved with the trial data.
`run`()	Runs the task in the main thread until completion or forced stop.
`run_in_thread`([daemon])	Runs the task in a separate background thread.
`save_csv`(run_mode)	Saves the session data to CSV files.
`save_json`(run_mode)	Saves the session settings to a JSON file.
`send_softcode_to_bpod`(code)	Sends a softcode to the Bpod device.
`start`()	Starts the task.
`transform`(df)	Transforms raw session data into a wide format suitable for analysis.

bpod: PyBpodBase

name: str

subject: str

current_trial: int

current_trial_states: list

touch_response: list

system_name: str

date: str

info: str

filename: str

sessions_directory: str

raw_session_path: str

session_path: str

session_settings_path: str

video_directory: str

video_path: str

video_data_path: str

subject_path: str

rt_session_path: str

settings: Settings

training: TrainingProtocolBase

trial_data: dict

raw_df: pandas.DataFrame

session_df: pandas.DataFrame

subject_df: pandas.DataFrame

force_stop: bool

maximum_number_of_trials: int

sound_calibration: Collection

water_calibration: Collection

start() → None[source]: Starts the task. Must be overridden by subclasses.

create_trial() → None[source]: Creates the state machine for the current trial. Must be overridden.

after_trial() → None[source]: Executed after each trial completes. Must be overridden.

close() → None[source]: Closes the task and releases resources. Must be overridden.

send_softcode_to_bpod(code: int) → None[source]

Sends a softcode to the Bpod device.

Parameters:: code (int) – The softcode value to send.

run_in_thread(daemon: bool = True) → None[source]

Runs the task in a separate background thread.

Parameters:: daemon (bool, optional) – Whether to run as a daemon thread. Defaults to True.

run() → None[source]: Runs the task in the main thread until completion or forced stop.

do_trial(send_to_cam: bool = False) → None[source]

Executes a single trial.

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

Parameters:: send_to_cam (bool, optional) – Whether to update the camera with the trial number. Defaults to False.

get_trial_data() → None[source]

Retrieves and processes data from the last executed trial.

Extracts timestamps, events, and states from the Bpod session and updates self.trial_data.

concatenate_trial_data() → None[source]: Appends the current trial’s data to the session DataFrame.

register_value(name: str, value: Any) → None[source]

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.

register_default_values() → None[source]: Registers standard session metadata values (task, subject, system, date).

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

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[source]

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][source]

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]

transform(df: pandas.DataFrame) → pandas.DataFrame[source]

Transforms raw session data into a wide format suitable for analysis.

Parameters:: df (pd.DataFrame) – Raw dataframe.
Returns:: Transformed dataframe.
Return type:: pd.DataFrame

classmethod get_name() → str[source]: Returns the name of the task class.

create_paths() → None[source]: Sets up file and directory paths for the session.