bpod_6_delay.py
Poke the side that lights up first; the other side lights up after a random delay, which adapts to the animal’s performance.
import math
import random
from collections import deque
import numpy as np
from village.custom_classes.task_base import BpodEvent, BpodOutput, TaskBase
# Curriculum-based probability distribution over delay values, used by
# create_trial() to pick each trial's delay. The longer the delay between the
# two side LEDs, the easier the trial. As the difficulty p goes from 0 to 1,
# the shorter (harder) delays are introduced gradually instead of all at
# once: at p=0 only the easiest (longest) delays are likely, at p=1 every
# delay is equally likely. The delays and the p value at which each one
# starts being seriously considered come from settings.delay_thresholds (see
# training_protocol.py). tau controls how sharp that introduction is, gamma
# how strongly the curriculum favors easier delays below their threshold.
def get_delay_probabilities(
p: float, delay_thresholds: dict, tau: float = 0.08, gamma: float = 3
) -> tuple[np.ndarray, np.ndarray]:
"""Returns (delays, probabilities) -- probabilities sums to 1, same
order as delays -- for np.random.choice(delays, p=probabilities).
delay_thresholds maps each delay (seconds) to its threshold. Its keys may
be strings (settings are saved as JSON, whose keys are always strings),
so they are converted to numbers here.
"""
delays = np.array([float(d) for d in delay_thresholds])
weights = []
for t in delay_thresholds.values():
t = float(t)
# t == 0 (the easiest, longest delays) never fades out, it just
# slowly loses dominance to the others as p grows.
a = 1.0 if t == 0 else 1.0 / (1.0 + np.exp(-(p - t) / tau))
weights.append(a**gamma)
weights = np.array(weights)
return delays, weights / weights.sum()
class Bpod6Delay(TaskBase):
def __init__(self):
super().__init__()
self.info = """
Delayed Side-Cue Discrimination Task, easy version (Bpod)
-----------------------------------------------------------------------------
- Middle port LED turns ON until the animal pokes the middle port,
for up to c_led_on_time seconds. No poke: the trial ends as an
omission (it doesn't count for the difficulty adaptation).
- Middle LED turns OFF and:
* One lateral port LED (left/right, random) turns ON.
* After a random delay, the opposite lateral LED turns ON too.
- The animal has up to 40s total to respond. Correct choice: poke the
side that was illuminated first.
* Correct response: side LEDs OFF, reward at the reward port, 1s ITI.
* Incorrect response: side LEDs OFF, penalty tone, then silence
until the timeout is over.
* No response: trial aborted, sequence restarts.
The delay is drawn from a distribution controlled by self.p (0-1):
higher self.p allows shorter delays between the two cues, which are
harder to tell apart, making the trial harder. self.p is tuned
automatically after every trial based on a rolling accuracy window
(see after_trial).
"""
def start(self):
"""Use the calibration to get the valve opening times (in seconds) for
ports 1 (left) and 3 (right), for both the normal and large reward
volumes. Also initializes the rolling-accuracy bookkeeping used to
adapt the task's difficulty (self.p).
Required settings (defined in training_protocol.py):
- self.settings.reward_volume: normal reward volume delivered on a
correct poke
- self.settings.reward_volume_large: larger reward volume, given on
~10% of trials
- self.settings.led_intensity: port LED brightness (0-255)
- self.settings.c_led_on_time: max wait for the center poke, seconds
- self.settings.iti_time: inter-trial interval after a correct
response, seconds
- self.settings.noise_time: penalty tone duration after a wrong poke, seconds
- self.settings.timeout: total penalty duration (tone + silence),
seconds
- self.settings.p (optional, default 0.0): initial difficulty, 0-1
- self.settings.curve_power (optional, default 3.0): shape parameter
for the delay distribution, see get_delay_probabilities
- self.settings.delay_thresholds: the possible delays between the two
side cues (seconds) and, for each one, the p from which it starts
to appear (0: always)
Required calibrations:
- water, for ports 1 and 3
- the "tone_600" sound, for speaker 0 (left) at 70 dB: the penalty
tone loaded by direct_functions.function2
"""
self.valve_l_time = self.calibrations.water_calibration.get_valve_time(
port=1, volume=self.settings.reward_volume
)
self.valve_l_time_large = self.calibrations.water_calibration.get_valve_time(
port=1, volume=self.settings.reward_volume_large
)
self.valve_r_time = self.calibrations.water_calibration.get_valve_time(
port=3, volume=self.settings.reward_volume
)
self.valve_r_time_large = self.calibrations.water_calibration.get_valve_time(
port=3, volume=self.settings.reward_volume_large
)
self.p = getattr(self.settings, "p", 0.0)
# Rolling-window accuracy, used to adapt self.p after every trial.
self.correct_history: list[int] = []
self.adaptation_window: deque[int] = deque(maxlen=20)
def create_trial(self):
first_side = random.choice([0, 1]) # first-cued side: 0 left, 1 right
curve_power = getattr(self.settings, "curve_power", 3.0)
delay_values, delay_probs = get_delay_probabilities(
p=self.p, delay_thresholds=self.settings.delay_thresholds, gamma=curve_power
)
self.delay = np.random.choice(delay_values, p=delay_probs)
self.signed_delay = -self.delay if first_side == 0 else self.delay
large_reward = random.random() < 0.10
self.reward_volume = (
self.settings.reward_volume_large
if large_reward
else self.settings.reward_volume
)
if first_side == 0: # left
self.correct_side = "left"
correct_poke = BpodEvent.Port1In
wrong_poke = BpodEvent.Port3In
valvetime = self.valve_l_time_large if large_reward else self.valve_l_time
valve_action = BpodOutput.Valve1
first_led = (BpodOutput.PWM1, self.settings.led_intensity)
else: # right
self.correct_side = "right"
correct_poke = BpodEvent.Port3In
wrong_poke = BpodEvent.Port1In
valvetime = self.valve_r_time_large if large_reward else self.valve_r_time
valve_action = BpodOutput.Valve3
first_led = (BpodOutput.PWM3, self.settings.led_intensity)
# 'c_led_on': center LED on, waits for the trial-initiating center poke.
# SoftCode2 loads the penalty sound now (direct_functions.function2),
# well ahead of when it's actually needed in 'wrong_choice' below.
self.bpod.add_state(
state_name="c_led_on",
state_timer=self.settings.c_led_on_time,
state_change_conditions={
BpodEvent.Tup: "exit", # no center poke -> omission
BpodEvent.Port2In: "first_side_led",
},
output_actions=[
(BpodOutput.PWM2, self.settings.led_intensity),
BpodOutput.SoftCode2,
],
)
# 'first_side_led': only the first-cued side is lit, for self.delay seconds
self.bpod.add_state(
state_name="first_side_led",
state_timer=self.delay,
state_change_conditions={
correct_poke: "correct_choice",
wrong_poke: "wrong_choice",
BpodEvent.Tup: "both_side_leds",
},
output_actions=[first_led],
)
# 'both_side_leds': both sides lit, for the remainder of the 40s response window
self.bpod.add_state(
state_name="both_side_leds",
state_timer=40 - self.delay,
state_change_conditions={
correct_poke: "correct_choice",
wrong_poke: "wrong_choice",
BpodEvent.Tup: "exit", # no response -> restart trial
},
output_actions=[
(BpodOutput.PWM1, self.settings.led_intensity),
(BpodOutput.PWM3, self.settings.led_intensity),
],
)
# 'correct_choice': reward, then ITI
self.bpod.add_state(
state_name="correct_choice",
state_timer=valvetime,
state_change_conditions={BpodEvent.Tup: "iti"},
output_actions=[valve_action],
)
self.bpod.add_state(
state_name="iti",
state_timer=self.settings.iti_time,
state_change_conditions={BpodEvent.Tup: "exit"},
output_actions=[],
)
# 'wrong_choice': plays the sound loaded back in 'c_led_on'
# (SoftCode4 -> direct_functions.function4), then silent timeout for
# the rest of the penalty
self.bpod.add_state(
state_name="wrong_choice",
state_timer=self.settings.noise_time,
state_change_conditions={BpodEvent.Tup: "timeout"},
output_actions=[BpodOutput.SoftCode4],
)
self.bpod.add_state(
state_name="timeout",
state_timer=self.settings.timeout - self.settings.noise_time,
state_change_conditions={BpodEvent.Tup: "exit"},
output_actions=[],
)
def after_trial(self):
"""Work out response_side and outcome, then adapt self.p based on a
rolling accuracy window.
Both correct_poke and wrong_poke are wired as transitions in both
"first_side_led" and "both_side_leds" (see create_trial), so the
first poke on either side -- whichever state it happens in -- is the
animal's response.
"""
# 1. This is the moment the first cue turned on. If it never did (no
# center poke; Bpod lists a state not visited as [nan]), it's an
# omission: the animal didn't choose, so it doesn't count for the
# accuracy nor for adapting the difficulty.
t_first_side_led = self.trial_data.get(
"STATE_first_side_led_START", [math.nan]
)[0]
if math.isnan(t_first_side_led):
self.register_value("p", self.p)
self.register_value("water", 0)
self.register_value("outcome", "omission")
self.register_value("response_side", "none")
self.register_value("rewarded_side", self.correct_side)
self.register_value("delay_cues", self.signed_delay)
return
# 2 & 3. Pokes on the correct/wrong port, at or after the first cue.
correct_key, wrong_key = (
("Port1In", "Port3In")
if self.correct_side == "left"
else ("Port3In", "Port1In")
)
correct_pokes = [
t for t in self.trial_data.get(correct_key, []) if t >= t_first_side_led
]
wrong_pokes = [
t for t in self.trial_data.get(wrong_key, []) if t >= t_first_side_led
]
# 4 & 5. Whichever port got poked first, if any, decides the outcome.
if correct_pokes and (not wrong_pokes or correct_pokes[0] <= wrong_pokes[0]):
response_side = self.correct_side
outcome = "correct"
correct = 1
t_choice = correct_pokes[0]
elif wrong_pokes:
response_side = "right" if self.correct_side == "left" else "left"
outcome = "incorrect"
correct = 0
t_choice = wrong_pokes[0]
else:
response_side = "none"
outcome = "miss"
correct = 0
t_choice = None
water = self.reward_volume if outcome == "correct" else 0
# Adapt difficulty: raise self.p after a strong window, lower it
# after a weak one, based on the last 20 trials.
self.correct_history.append(correct)
self.adaptation_window.append(correct)
running_accuracy = np.mean(self.correct_history[-20:])
if len(self.adaptation_window) >= self.adaptation_window.maxlen:
window_accuracy = np.mean(self.adaptation_window)
if window_accuracy > 0.75:
self.p = min(self.p + 0.05, 1.0)
self.adaptation_window.clear()
elif window_accuracy < 0.50:
self.p = max(self.p - 0.05, 0.0)
self.adaptation_window.clear()
if t_choice is not None:
self.register_value("first_trial_response_time", t_choice)
self.register_value("running_accuracy", running_accuracy)
self.register_value("p", self.p)
self.register_value("water", water)
self.register_value("outcome", outcome)
self.register_value("response_side", response_side)
self.register_value("rewarded_side", self.correct_side)
self.register_value("delay_cues", self.signed_delay)
def close(self):
pass