Bpod¶

class bpod_core.bpod.Bpod ¶

Bases: SerialDevice, AbstractBpod

Class for interfacing with a Bpod Finite State Machine.

close() ¶

Close the connection to the Bpod.

Waits for any running trial to finish before closing the serial port.

Raises:: SerialException – If the port could not be closed.
Return type:: None

get_data(*, concat=True, rechunk=False, lazy=False) ¶

Return trial data from the data queue.

Parameters:

concat (bool, default: True) – If True, pop and concatenate all DataFrames currently in the queue into a single DataFrame, blocking until at least one is available. If False, pop and return one DataFrame, blocking until one is available.
rechunk (bool, default: False) – If True, make sure that the result data is in contiguous memory. Only applies when concat=True.
lazy (bool, default: False) – If True, return a polars.LazyFrame. If False, return a polars.DataFrame.

Returns:

One trial’s data, or all available trials concatenated when concat=True.

Columns:

time (Datetime) – absolute Bpod timestamp.
trial (UInt16) – zero-based trial index.
state machine (Categorical) – state machine hash, see hash().
state (Categorical) – state name.
type (Enum) – event type.
event (Categorical) – input event name.
channel (Categorical) – channel name.
value (UInt8) – channel value.

Return type:

polars.DataFrame or polars.LazyFrame

Raises:

BpodError – If the queue is empty and no state machine is currently running.

open() ¶

Open the connection to the Bpod.

Raises:

SerialException – If the port could not be opened.
BpodError – If the handshake fails.

Return type:

None

peek_data(trigger_states=None, *, lazy=False) ¶

Return a snapshot of the current trial’s data.

Parameters:

trigger_states (Collection of str, optional) – Block until at least one of the given states has been entered, then return the snapshot. If None (default), returns immediately.
lazy (bool, default: False) – If True, return a polars.LazyFrame. If False (default), return a polars.DataFrame.

Returns:

Events recorded so far in the current trial. Returns an empty DataFrame if no trial is running.

Return type:

polars.DataFrame or polars.LazyFrame

Raises:

ValueError – If one or several of the trigger states are not part of the state machine.

reset_session_clock() ¶

Reset the Bpod session clock.

Returns:: True if the Bpod acknowledged the command.
Return type:: bool
Raises:: BpodError – When the method is called while a state machine is running.

run(state_machine=None, *, trial_number=None, validate=True) ¶

Run a state machine on the Bpod.

Validates, compiles, sends, and queues a state machine for immediate execution. If the Bpod is currently running a state machine, the new one is queued to run as soon as the current one finishes, with no inter-trial gap.

If called without an argument, the previously sent state machine is re-sent from the compilation cache and queued for immediate back-to-back execution.

Parameters:

state_machine (StateMachine, optional) – The state machine to run. If not provided, the previously sent state machine is repeated.
trial_number (int, optional) – The trial number to assign to the state machine. If not provided, the trial number is automatically incremented with each run.
validate (bool, default: True) – If False, the state machine will not be validated prior to compilation. This will speed up the process, but may result in errors or unexpected behavior if the state machine is invalid. Use with caution.

Raises:

RuntimeError – If called without an argument and no state machine has been run yet.
ValueError – If the state machine is invalid or exceeds hardware limitations.
ValidationError – If function arguments don’t match type hints.

Return type:

None

Notes

This method returns once the state machine has been queued on the Bpod. The Bpod will then begin executing the state machine as soon as possible — immediately if the device is idle or right after the current state machine finishes. Subsequent calls of this method will result in continuous acquisition and zero inter-trial downtime (as long as the Bpod’s run queue stays filled).