Task Logic

task_logic

__semver__ module-attribute

__semver__ = pep440_to_semver(__version__)

logger module-attribute

logger = getLogger(__name__)

PatchUpdateFunction module-attribute

PatchUpdateFunction = Union[
    ClampedRateFunction,
    ClampedMultiplicativeRateFunction,
    SaturatingMultiplicativeRateFunction,
    SetValueFunction,
    LookupTableFunction,
    CtcmFunction,
]

RewardFunction module-attribute

RewardFunction = Union[
    PatchRewardFunction,
    OutsideRewardFunction,
    OnThisPatchEntryRewardFunction,
    PersistentRewardFunction,
]

OdorMixture module-attribute

OdorMixture = List[NonNegativeFloat]

PatchTerminator module-attribute

PatchTerminator = Union[
    PatchTerminatorOnRejection,
    PatchTerminatorOnChoice,
    PatchTerminatorOnReward,
    PatchTerminatorOnTime,
    PatchTerminatorOnDistance,
    PatchTerminatorOnRewardSite,
]

Environment module-attribute

Environment = TypeAliasType(
    "Environment",
    Union[MarkovEnvironment, SequenceEnvironment],
)

BlockEndCondition module-attribute

BlockEndCondition = Union[
    BlockEndConditionDuration,
    BlockEndConditionDistance,
    BlockEndConditionChoice,
    BlockEndConditionReward,
    BlockEndConditionPatchCount,
]

Size pydantic-model

Bases: BaseModel

Represents 2D dimensions with width and height.

Fields:

• width (float)
• height (float)

width pydantic-field

width = 0

Width of the texture

height pydantic-field

height = 0

Height of the texture

Vector3 pydantic-model

Bases: BaseModel

Represents a 3D vector with float coordinates.

Fields:

• x (float)
• y (float)
• z (float)

x pydantic-field

x = 0

X coordinate of the vector

y pydantic-field

y = 0

Y coordinate of the vector

z pydantic-field

z = 0

Z coordinate of the vector

Task

Bases: Task

Base class for task schemas.

task_parameters class-attribute instance-attribute

task_parameters = Field(
    description="Parameters of the task",
    validate_default=True,
)

version class-attribute instance-attribute

version = Field(
    pattern=SEMVER_REGEX, description="task schema version"
)

coerce_version classmethod

coerce_version(v)

Source code in .venv/lib/python3.13/site-packages/aind_behavior_services/task/__init__.py

@field_validator("version", mode="before", check_fields=False)
@classmethod
def coerce_version(cls, v: str) -> str:
    return coerce_schema_version(cls, v)

TaskParameters

Bases: TaskParameters

Base class for storing parameters for the task.

rng_seed class-attribute instance-attribute

rng_seed = Field(
    default=None,
    description="Seed of the random number generator",
)

aind_behavior_services_pkg_version class-attribute instance-attribute

aind_behavior_services_pkg_version = Field(
    default=__semver__,
    pattern=SEMVER_REGEX,
    title="aind_behavior_services package version",
    frozen=True,
)

coerce_version classmethod

coerce_version(v, ctx)

Source code in .venv/lib/python3.13/site-packages/aind_behavior_services/task/__init__.py

@field_validator("aind_behavior_services_pkg_version", mode="before", check_fields=False)
@classmethod
def coerce_version(cls, v: str, ctx) -> str:
    return coerce_schema_version(cls, v, ctx.field_name)

NumericalUpdaterOperation

Bases: str, Enum

Enumeration of operations that can be performed by numerical updaters.

These operations define how parameter values are modified during task execution, allowing for dynamic adjustment of task parameters based on performance or other criteria.

NONE class-attribute instance-attribute

NONE = 'None'

Does not perform any update

OFFSET class-attribute instance-attribute

OFFSET = 'Offset'

Adds (or subtracts) the update value to the current value. The update value can be positive or negative.

GAIN class-attribute instance-attribute

GAIN = 'Gain'

Multiplies the current value by the update value. The update value can be greater or less than 1.

SET class-attribute instance-attribute

SET = 'Set'

Sets the current value to the update value.

NumericalUpdaterParameters pydantic-model

Bases: BaseModel

Parameters that control how numerical updates are applied to task values.

These parameters define the bounds and increments for updating numerical values during task execution, ensuring values stay within acceptable ranges.

Fields:

• initial_value (float)
• on_success (float)
• on_failure (float)
• increment (float)
• decrement (float)
• minimum (float)
• maximum (float)

Validators:

• _ensure_backwards_compatibility
• _ensure_backwards_compatibility_after

initial_value pydantic-field

initial_value = 0.0

Initial value of the parameter

on_success pydantic-field

on_success = 0.0

Value used to update the parameter by on success

on_failure pydantic-field

on_failure = 0.0

Value used to update the parameter by on failure

increment pydantic-field

increment = 0.0

Value to increment the parameter by

decrement pydantic-field

decrement = 0.0

Value to decrement the parameter by

minimum pydantic-field

minimum = 0.0

Minimum value of the parameter

maximum pydantic-field

maximum = 0.0

Minimum value of the parameter

NumericalUpdater pydantic-model

Bases: BaseModel

A numerical updater that modifies task parameters during execution.

This class combines an operation type with parameters to define how values should be updated dynamically during the task, enabling adaptive behavior based on animal performance or other criteria.

Fields:

• operation (NumericalUpdaterOperation)
• parameters (NumericalUpdaterParameters)

operation pydantic-field

operation = NONE

Operation to perform on the parameter

parameters pydantic-field

parameters = NumericalUpdaterParameters()

Parameters of the updater

UpdaterTarget

Bases: str, Enum

Enumeration of parameters that can be targeted by numerical updaters.

These targets define which task parameters can be dynamically modified during task execution to adapt to animal performance or experimental needs.

STOP_DURATION_OFFSET class-attribute instance-attribute

STOP_DURATION_OFFSET = 'StopDurationOffset'

STOP_VELOCITY_THRESHOLD class-attribute instance-attribute

STOP_VELOCITY_THRESHOLD = 'StopVelocityThreshold'

REWARD_DELAY_OFFSET class-attribute instance-attribute

REWARD_DELAY_OFFSET = 'RewardDelayOffset'

Texture pydantic-model

Bases: BaseModel

Defines visual texture properties for VR environment surfaces.

Textures are applied to walls, floors, and other surfaces in the virtual environment to provide visual cues and context for the foraging task.

Texture name must correspond to a valid texture asset loaded in the workflow.

Fields:

• name (str)
• size (Size)

name pydantic-field

name = 'default'

Name of the texture

size pydantic-field

size = Size(width=40, height=40)

Size of the texture

WallTextures pydantic-model

Bases: BaseModel

Defines textures for all walls of a visual corridor in the VR environment.

This class specifies the visual appearance of corridor surfaces including floor, ceiling, and side walls, allowing for complex visual environments with different textures on each surface.

Fields:

• floor (Texture)
• ceiling (Texture)
• left (Texture)
• right (Texture)

floor pydantic-field

floor

The texture of the floor

ceiling pydantic-field

ceiling

The texture of the ceiling

left pydantic-field

left

The texture of the left

right pydantic-field

right

The texture of the right

VisualCorridor pydantic-model

Bases: BaseModel

Defines a visual corridor segment in the VR environment.

Visual corridors are the basic building blocks of the VR environment, defining spatial regions with specific textures, dimensions, and positions.

Fields:

• id (int)
• size (Size)
• start_position (float)
• length (float)
• textures (WallTextures)

id pydantic-field

id = 0

Id of the visual corridor object

size pydantic-field

size = Size(width=40, height=40)

Size of the corridor (cm)

start_position pydantic-field

start_position = 0

Start position of the corridor (cm)

length pydantic-field

length = 120

Length of the corridor site (cm)

textures pydantic-field

textures

The textures of the corridor

OperantLogic pydantic-model

Bases: BaseModel

Defines operant conditioning logic for reward delivery in the VR foraging task.

This class controls when and how rewards are delivered based on animal behavior, implementing stopping requirements, collection timeouts, and spatial constraints.

Fields:

• is_operant (bool)
• stop_duration (Distribution)
• time_to_collect_reward (float)
• grace_distance_threshold (float)

is_operant pydantic-field

is_operant = True

Will the trial implement operant logic

stop_duration pydantic-field

stop_duration = scalar_value(0)

Duration (s) the animal must stop for to lock its choice

time_to_collect_reward pydantic-field

time_to_collect_reward = 100000

Time(s) the animal has to collect the reward

grace_distance_threshold pydantic-field

grace_distance_threshold = 10

Virtual distance (cm) the animal must be within to not abort the current choice

_PatchUpdateFunction pydantic-model

Bases: BaseModel

Base class for patch update functions.

This is an internal base class that defines the common interface for all patch update function types. Should not be instantiated directly.

Fields:

• function_type (str)

function_type pydantic-field

function_type

LookupTableFunction pydantic-model

Bases: _PatchUpdateFunction

A patch update function that uses lookup table interpolation.

Update in the form of x = lut_values[lerp(lut_keys, lut_values, tick_value)]. This function maps input values to output values using a lookup table with linear interpolation between defined points. Useful for complex, non-linear reward schedules or parameter updates.

Fields:

• function_type (Literal['LookupTableFunction'])
• lut_keys (List[float])
• lut_values (List[float])

Validators:

• _validate_lut

function_type pydantic-field

function_type = 'LookupTableFunction'

lut_keys pydantic-field

lut_keys

List of keys of the lookup table

lut_values pydantic-field

lut_values

List of values of the lookup table

ClampedRateFunction pydantic-model

Bases: _PatchUpdateFunction

A patch update function that applies a clamped rate-based update.

Update in the form of x = clamp(x + rate * tick_value). This function updates values at a specified rate while keeping results within defined minimum and maximum bounds. The rate is applied per rule unit (e.g., time, distance, choices).

Fields:

• function_type (Literal['ClampedRateFunction'])
• minimum (Optional[float])
• maximum (Optional[float])
• rate (Distribution)

function_type pydantic-field

function_type = 'ClampedRateFunction'

minimum pydantic-field

minimum = 0

Minimum value of the rate

maximum pydantic-field

maximum

Maximum value of the rate

rate pydantic-field

rate

Rate of the replenishment, in value per rule unit.

ClampedMultiplicativeRateFunction pydantic-model

Bases: _PatchUpdateFunction

A patch update function that applies multiplicative rate updates with bounds.

Update in the form of x = clamp(x * rate ** tick_value). This function multiplies the current value by the rate parameter, maintaining the result within specified minimum and maximum bounds. Useful for percentage- based changes and exponential decay/growth patterns.

Fields:

• function_type (Literal['ClampedMultiplicativeRateFunction'])
• minimum (Optional[float])
• maximum (Optional[float])
• rate (Distribution)

function_type pydantic-field

function_type = 'ClampedMultiplicativeRateFunction'

minimum pydantic-field

minimum = 0

Minimum value of the rate

maximum pydantic-field

maximum

Maximum value of the rate

rate pydantic-field

rate

Rate of the replenishment, in value per rule unit.

SaturatingMultiplicativeRateFunction pydantic-model

Bases: _PatchUpdateFunction

Multiplicative updater with configurable out-of-bounds rectification.

The raw update is computed as x_raw = x * rate ** tick_value. If x_raw is within bounds, it is returned unchanged. If it falls below minimum or above maximum, the output is rectified to below_minimum_to or above_maximum_to respectively when provided; otherwise it falls back to the corresponding bound.

Fields:

• function_type (Literal['SaturatingMultiplicativeRateFunction'])
• minimum (Optional[float])
• maximum (Optional[float])
• below_minimum_to (Optional[float])
• above_maximum_to (Optional[float])
• rate (Distribution)

function_type pydantic-field

function_type = 'SaturatingMultiplicativeRateFunction'

minimum pydantic-field

minimum = 0

Minimum value of the rate

maximum pydantic-field

maximum

Maximum value of the rate

below_minimum_to pydantic-field

below_minimum_to = None

If the value is below minimum, it will be set to this value instead of the minimum

above_maximum_to pydantic-field

above_maximum_to = None

If the value is above maximum, it will be set to this value instead of the maximum

rate pydantic-field

rate

Rate of the replenishment, in value per rule unit.

SetValueFunction pydantic-model

Bases: _PatchUpdateFunction

A patch update function that sets the target to a specific value.

Update in the form of x = value. This function directly sets the target parameter to a value drawn from the specified distribution, ignoring the current value. Useful for resetting parameters or applying discrete changes.

Fields:

• function_type (Literal['SetValueFunction'])
• value (Distribution)

function_type pydantic-field

function_type = 'SetValueFunction'

value pydantic-field

value

Sets the value of the target to this value.

CtcmFunction pydantic-model

Bases: _PatchUpdateFunction

A patch update function that uses a continuous-time Markov chain (CTMC) to determine patch updates based on a transition probability matrix.

It expects a transition matrix that takes the current value of the variable of interest (e.g. Probability), and outputs a new value based on the defined stochastic process in the transition matrix.

Fields:

• function_type (Literal['CtcmFunction'])
• transition_matrix (List[List[NonNegativeFloat]])
• rho (float)
• dt (Literal[0.1])
• rate (Optional[float])
• minimum (float)
• maximum (float)

Validators:

• validate_transition_matrix → transition_matrix

function_type pydantic-field

function_type = 'CtcmFunction'

transition_matrix pydantic-field

transition_matrix

Transition matrix between states

rho pydantic-field

rho

The underlying value governing the stochastic process

dt pydantic-field

dt = 0.1

Sampling time step (s)

rate pydantic-field

rate = None

Rate of the replenishment used to generate the matrix. This value is used for metadata keep sake only

minimum pydantic-field

minimum

Minimum value after update

maximum pydantic-field

maximum

Maximum value after update

validate_transition_matrix pydantic-validator

validate_transition_matrix(value)

Ensures matrix is of valid format and normalized to 1 within rows

Source code in src/packages/aind_behavior_vr_foraging/src/aind_behavior_vr_foraging/task_logic.py

@field_validator("transition_matrix", mode="after")
@classmethod
def validate_transition_matrix(cls, value):
    """Ensures matrix is of valid format and normalized to 1 within rows"""
    if not value:
        raise ValueError("Transition matrix must not be empty.")
    if any(len(row) != len(value) for row in value):
        raise ValueError("Transition matrix must be square (same number of rows and columns).")
    for row in value:
        row_sum = sum(row)
        for col in row:
            col /= row_sum
    return value

serialize_transition_matrix

serialize_transition_matrix(value)

Round to 15 significant digits for deterministic serialization across platforms.

Source code in src/packages/aind_behavior_vr_foraging/src/aind_behavior_vr_foraging/task_logic.py

@field_serializer("transition_matrix")
def serialize_transition_matrix(self, value: List[List[NonNegativeFloat]]) -> List[List[NonNegativeFloat]]:
    """Round to 15 significant digits for deterministic serialization across platforms."""
    return [[round(v, 15) for v in row] for row in value]

from_replenishment_rate classmethod

from_replenishment_rate(
    n_states, replenishment_rate, rho, dt=0.1
)

Computes the replenishment transition probability matrix for each patch Parameters

---

n_states: int number reward states per patch. replenishment_rate: float replenishment rate. rho: float The underlying value governing the stochastic process dt: float experiment time step

Returns

CtcmFunction Instance of CtcmFunction with computed transition matrix.

Source code in src/packages/aind_behavior_vr_foraging/src/aind_behavior_vr_foraging/task_logic.py

@classmethod
def from_replenishment_rate(
    cls, n_states: int, replenishment_rate: float, rho: float, dt: Optional[float] = 0.1
) -> "CtcmFunction":
    """
    Computes the replenishment transition probability matrix for each patch
    Parameters
    -----------
    n_states: int
        number reward states per patch.
    replenishment_rate: float
        replenishment rate.
    rho: float
        The underlying value governing the stochastic process
    dt: float
        experiment time step


    Returns
    -------
    CtcmFunction
        Instance of CtcmFunction with computed transition matrix.
    """
    import numpy as np
    from scipy.linalg import expm

    if dt is None:
        dt = cls.model_fields["dt"].default
    q = np.zeros((n_states, n_states))
    np.fill_diagonal(q, -replenishment_rate)
    np.fill_diagonal(q[:, 1:], replenishment_rate)
    q[-1, -1] = 0

    p_t = expm(q * dt)
    assert p_t.ndim == 2
    transition_matrix = cast(list[list[float]], p_t.tolist())
    return cls(
        transition_matrix=transition_matrix,
        rho=rho,
        dt=dt,
        rate=replenishment_rate,
    )

RewardFunctionRule

Bases: str, Enum

Enumeration of rules that trigger reward function updates.

These rules define when and how reward replenishment occurs, with different triggers based on animal behavior, time passage, or spatial navigation.

ON_REWARD class-attribute instance-attribute

ON_REWARD = 'OnReward'

Triggers after a reward is delivered. The tick value is always 1.

ON_REWARD_AMOUNT class-attribute instance-attribute

ON_REWARD_AMOUNT = 'OnRewardAmount'

Triggers after a reward is delivered. The tick value is the amount of reward.

ON_CHOICE class-attribute instance-attribute

ON_CHOICE = 'OnChoice'

Triggers after a choice is made. The tick value is always 1.

ON_TIME class-attribute instance-attribute

ON_TIME = 'OnTime'

Triggers periodically. The tick value is the elapsed time since the last update (s).

ON_DISTANCE class-attribute instance-attribute

ON_DISTANCE = 'OnDistance'

Triggers periodically. The tick value is the distance traveled since the last update (cm).

ON_THIS_PATCH_ENTRY class-attribute instance-attribute

ON_THIS_PATCH_ENTRY = 'OnThisPatchEntry'

Triggers when the animal enters the patch. The tick value is always 1.

ON_PATCH_ENTRY class-attribute instance-attribute

ON_PATCH_ENTRY = 'OnPatchEntry'

Triggers when the animal enters any patch. The tick value is always 1.

ON_CHOICE_ACCUMULATED class-attribute instance-attribute

ON_CHOICE_ACCUMULATED = 'OnChoiceAccumulated'

Triggers after a choice is made. The tick value is the accumulated number of choices.

ON_REWARD_ACCUMULATED class-attribute instance-attribute

ON_REWARD_ACCUMULATED = 'OnRewardAccumulated'

Triggers after a reward is delivered. The tick value is the accumulated number of rewarded events.

ON_TIME_ACCUMULATED class-attribute instance-attribute

ON_TIME_ACCUMULATED = 'OnTimeAccumulated'

Triggers periodically. The tick value is the accumulated elapsed time since patch creation (s).

ON_DISTANCE_ACCUMULATED class-attribute instance-attribute

ON_DISTANCE_ACCUMULATED = 'OnDistanceAccumulated'

Triggers periodically. The tick value is the accumulated distance traveled since patch creation (cm).

_RewardFunction pydantic-model

Bases: BaseModel

Base class for reward functions.

This is an internal base class that defines the common interface for all reward function types. Should not be instantiated directly.

Fields:

• function_type (str)
• amount (Optional[PatchUpdateFunction])
• probability (Optional[PatchUpdateFunction])
• available (Optional[PatchUpdateFunction])

function_type pydantic-field

function_type

amount pydantic-field

amount = None

Defines the amount of reward replenished per rule unit.

probability pydantic-field

probability = None

Defines the probability of reward replenished per rule unit.

available pydantic-field

available = None

Defines the amount of reward available replenished in the patch per rule unit.

PatchRewardFunction pydantic-model

Bases: _RewardFunction

A RewardFunction that is applied when the animal is inside the patch. For the purposes of this function post-patch and inter-patch are excluded.

Fields:

• amount (Optional[PatchUpdateFunction])
• probability (Optional[PatchUpdateFunction])
• available (Optional[PatchUpdateFunction])
• function_type (Literal['PatchRewardFunction'])
• rule (Literal[ON_REWARD, ON_REWARD_AMOUNT, ON_CHOICE, ON_TIME, ON_DISTANCE, ON_CHOICE_ACCUMULATED, ON_REWARD_ACCUMULATED, ON_TIME_ACCUMULATED, ON_DISTANCE_ACCUMULATED])

function_type pydantic-field

function_type = 'PatchRewardFunction'

rule pydantic-field

rule = ON_REWARD

Rule to trigger reward function

amount pydantic-field

amount = None

Defines the amount of reward replenished per rule unit.

probability pydantic-field

probability = None

Defines the probability of reward replenished per rule unit.

available pydantic-field

available = None

Defines the amount of reward available replenished in the patch per rule unit.

OutsideRewardFunction pydantic-model

Bases: _RewardFunction

A RewardFunction that is applied when the animal is outside of the patch.

Fields:

• amount (Optional[PatchUpdateFunction])
• probability (Optional[PatchUpdateFunction])
• available (Optional[PatchUpdateFunction])
• function_type (Literal['OutsideRewardFunction'])
• rule (Literal[ON_TIME, ON_DISTANCE, ON_TIME_ACCUMULATED, ON_DISTANCE_ACCUMULATED])
• delay (float)

function_type pydantic-field

function_type = 'OutsideRewardFunction'

rule pydantic-field

rule = ON_TIME

Rule to trigger reward function

delay pydantic-field

delay = 0

Delay (s) before the replenishment starts after the rule is triggered.

amount pydantic-field

amount = None

Defines the amount of reward replenished per rule unit.

probability pydantic-field

probability = None

Defines the probability of reward replenished per rule unit.

available pydantic-field

available = None

Defines the amount of reward available replenished in the patch per rule unit.

OnThisPatchEntryRewardFunction pydantic-model

Bases: _RewardFunction

A RewardFunction that is applied when the animal enters the patch.

Fields:

• amount (Optional[PatchUpdateFunction])
• probability (Optional[PatchUpdateFunction])
• available (Optional[PatchUpdateFunction])
• function_type (Literal['OnThisPatchEntryRewardFunction'])
• rule (Literal[ON_THIS_PATCH_ENTRY])

function_type pydantic-field

function_type = 'OnThisPatchEntryRewardFunction'

rule pydantic-field

rule = ON_THIS_PATCH_ENTRY

Rule to trigger reward function

amount pydantic-field

amount = None

Defines the amount of reward replenished per rule unit.

probability pydantic-field

probability = None

Defines the probability of reward replenished per rule unit.

available pydantic-field

available = None

Defines the amount of reward available replenished in the patch per rule unit.

PersistentRewardFunction pydantic-model

Bases: _RewardFunction

A RewardFunction that is always active.

Fields:

• amount (Optional[PatchUpdateFunction])
• probability (Optional[PatchUpdateFunction])
• available (Optional[PatchUpdateFunction])
• function_type (Literal['PersistentRewardFunction'])
• rule (Literal[ON_REWARD, ON_CHOICE, ON_TIME, ON_DISTANCE, ON_CHOICE_ACCUMULATED, ON_REWARD_ACCUMULATED, ON_TIME_ACCUMULATED, ON_DISTANCE_ACCUMULATED, ON_PATCH_ENTRY])

function_type pydantic-field

function_type = 'PersistentRewardFunction'

rule pydantic-field

rule

amount pydantic-field

amount = None

Defines the amount of reward replenished per rule unit.

probability pydantic-field

probability = None

Defines the probability of reward replenished per rule unit.

available pydantic-field

available = None

Defines the amount of reward available replenished in the patch per rule unit.

RewardSpecification pydantic-model

Bases: BaseModel

Specifies reward parameters and behavior for a patch.

This class defines all aspects of reward delivery including amounts, probabilities, delays, operant logic, and dynamic update functions. It serves as the complete specification for how rewards are managed in a given Patch.

Fields:

• operant_logic (Optional[OperantLogic])
• delay (Distribution)
• amount (Distribution)
• probability (Distribution)
• available (Distribution)
• reward_function (List[RewardFunction])

operant_logic pydantic-field

operant_logic = None

The optional operant logic of the reward

delay pydantic-field

delay = scalar_value(0)

The optional distribution where the delay to reward will be drawn from

amount pydantic-field

amount = scalar_value(5)

Initial amount of reward in microliters

probability pydantic-field

probability = scalar_value(1)

Initial probability of reward delivery

available pydantic-field

available = scalar_value(10)

Initial amount of reward available in the patch in microliters

reward_function pydantic-field

reward_function = []

Reward function of the patch

VirtualSiteLabels

Bases: str, Enum

Enumeration of virtual site types in the VR foraging environment.

These labels categorize different regions of the virtual environment, each serving different functional roles in the foraging task.

UNSPECIFIED class-attribute instance-attribute

UNSPECIFIED = 'Unspecified'

Placeholder

INTERPATCH class-attribute instance-attribute

INTERPATCH = 'InterPatch'

Region rendered before entering a patch

POSTPATCH class-attribute instance-attribute

POSTPATCH = 'PostPatch'

Region rendered after leaving a patch

REWARDSITE class-attribute instance-attribute

REWARDSITE = 'RewardSite'

Region where rewards are delivered

INTERSITE class-attribute instance-attribute

INTERSITE = 'InterSite'

Region between sites within a patch

RenderSpecification pydantic-model

Bases: BaseModel

Defines visual rendering properties for virtual environment elements.

This class controls the visual appearance of virtual sites, including contrast and other visual parameters that affect how elements are rendered in the VR environment.

Fields:

• contrast (Optional[float])

contrast pydantic-field

contrast = None

Contrast of the texture

TreadmillSpecification pydantic-model

Bases: BaseModel

Defines treadmill friction properties for virtual sites.

This class controls the friction experienced by the animal when moving through different virtual sites, allowing for varied locomotion dynamics across different regions of the environment.

Fields:

• friction (Optional[Distribution])

friction pydantic-field

friction = None

Friction of the treadmill (0-1). The drawn value must be between 0 and 1

VirtualSiteGenerator pydantic-model

Bases: BaseModel

Generates virtual site specifications with randomized properties.

This class defines templates for creating virtual sites with variable properties like length and rendering specifications. It's used to generate diverse virtual environments for the foraging task.

Fields:

• render_specification (RenderSpecification)
• label (VirtualSiteLabels)
• length_distribution (Distribution)
• treadmill_specification (Optional[TreadmillSpecification])

render_specification pydantic-field

render_specification = RenderSpecification()

Contrast of the environment

label pydantic-field

label = UNSPECIFIED

Label of the virtual site

length_distribution pydantic-field

length_distribution = scalar_value(20)

Distribution of the length of the virtual site

treadmill_specification pydantic-field

treadmill_specification = None

Treadmill specification

PatchVirtualSitesGenerator pydantic-model

Bases: BaseModel

Defines the generation specifications for all virtual site types within a patch.

This class contains generators for all the different types of virtual sites that can appear within a patch environment. Each generator defines how sites of that type should be created with their properties and distributions.

Fields:

• inter_site (VirtualSiteGenerator)
• inter_patch (VirtualSiteGenerator)
• post_patch (Optional[VirtualSiteGenerator])
• reward_site (VirtualSiteGenerator)

inter_site pydantic-field

inter_site = VirtualSiteGenerator(label=INTERSITE)

Generator of the inter-site virtual sites

inter_patch pydantic-field

inter_patch = VirtualSiteGenerator(label=INTERPATCH)

Generator of the inter-patch virtual sites

post_patch pydantic-field

post_patch = None

Generator of the post-patch virtual sites

reward_site pydantic-field

reward_site = VirtualSiteGenerator(label=REWARDSITE)

Generator of the reward-site virtual sites

VirtualSiteRewardSpecification pydantic-model

Bases: BaseModel

THIS CLASS IS NOT MEANT TO BE DIRECTLY INSTANTIATED. Specifies reward parameters and behavior for a virtual site.

Note: This class is primarily used internally for runtime site generation and is not meant to be directly instantiated in task configuration DSL.

Fields:

• operant_logic (OperantLogic)
• delay (Distribution)

operant_logic pydantic-field

operant_logic

The optional operant logic of the reward

delay pydantic-field

delay = scalar_value(0)

The optional distribution where the delay to reward will be drawn from

_OdorSpecification pydantic-model

Bases: BaseModel

Specifies odor delivery parameters for olfactory cues in the VR environment.

Odors can be delivered at specific locations to provide additional sensory information for navigation and foraging decisions.

Fields:

• index (int)
• concentration (float)

index pydantic-field

index

Index of the odor to be used

concentration pydantic-field

concentration = 1

Concentration of the odor

VirtualSite pydantic-model

Bases: BaseModel

THIS CLASS IS NOT MEANT TO BE DIRECTLY INSTANTIATED. Represents a specific virtual site instance in the VR environment.

This class defines a concrete virtual site with specific properties like position, length, and associated specifications. It is typically generated from VirtualSiteGenerator templates rather than being directly instantiated in the DSL.

Note: This class is primarily used internally for runtime site generation and is not meant to be directly instantiated in task configuration DSL.

Fields:

• id (int)
• label (VirtualSiteLabels)
• length (float)
• start_position (float)
• odor_specification (Optional[OdorMixture])
• reward_specification (Optional[VirtualSiteRewardSpecification])
• render_specification (RenderSpecification)
• treadmill_specification (Optional[TreadmillSpecification])

id pydantic-field

id = 0

Id of the virtual site

label pydantic-field

label = UNSPECIFIED

Label of the virtual site

length pydantic-field

length = 20

Length of the virtual site (cm)

start_position pydantic-field

start_position = 0

Start position of the virtual site (cm)

odor_specification pydantic-field

odor_specification = None

The optional odor specification of the virtual site

reward_specification pydantic-field

reward_specification = None

The optional reward specification of the virtual site

render_specification pydantic-field

render_specification = RenderSpecification()

The optional render specification of the virtual site

treadmill_specification pydantic-field

treadmill_specification = None

Treadmill specification

_PatchTerminator pydantic-model

Bases: BaseModel

Fields:

• terminator_type (str)

terminator_type pydantic-field

terminator_type

PatchTerminatorOnRejection pydantic-model

Bases: _PatchTerminator

Terminates the patch after a reward site where the animal does not stop in "count" reward sites.

Fields:

• terminator_type (Literal['OnRejection'])
• count (Distribution)

terminator_type pydantic-field

terminator_type = 'OnRejection'

count pydantic-field

count = scalar_value(1)

Number of reward sites the animal must not stop in to terminate the patch

PatchTerminatorOnChoice pydantic-model

Bases: _PatchTerminator

Terminates the patch after "count" choices.

Fields:

• terminator_type (Literal['OnChoice'])
• count (Distribution)

terminator_type pydantic-field

terminator_type = 'OnChoice'

count pydantic-field

count = scalar_value(1)

Number of choices the animal must make to terminate the patch

PatchTerminatorOnReward pydantic-model

Bases: _PatchTerminator

Terminates the patch after "count" rewards.

Fields:

• terminator_type (Literal['OnReward'])
• count (Distribution)

terminator_type pydantic-field

terminator_type = 'OnReward'

count pydantic-field

count = scalar_value(1)

Number of rewards the animal must collect to terminate the patch

PatchTerminatorOnTime pydantic-model

Bases: _PatchTerminator

Terminates the patch after a "count" seconds.

Fields:

• terminator_type (Literal['OnTime'])
• count (Distribution)

terminator_type pydantic-field

terminator_type = 'OnTime'

count pydantic-field

count

Number of seconds to wait before terminating the patch

PatchTerminatorOnDistance pydantic-model

Bases: _PatchTerminator

Terminates the patch after a "count" distance.

Fields:

• terminator_type (Literal['OnDistance'])
• count (Distribution)

terminator_type pydantic-field

terminator_type = 'OnDistance'

count pydantic-field

count

Number of distance units to wait before terminating the patch

PatchTerminatorOnRewardSite pydantic-model

Bases: _PatchTerminator

Terminates the patch after visiting a specific site count.

Fields:

• terminator_type (Literal['OnRewardSite'])
• count (Distribution)

terminator_type pydantic-field

terminator_type = 'OnRewardSite'

count pydantic-field

count

Number of sites the animal visits before terminating the patch.

Patch pydantic-model

Bases: BaseModel

Represents statistics for a patch in the VR foraging task.

Fields:

• label (str)
• state_index (int)
• odor_specification (OdorMixture)
• reward_specification (RewardSpecification)
• patch_virtual_sites_generator (PatchVirtualSitesGenerator)
• patch_terminators (List[PatchTerminator])

Validators:

• _ensure_backwards_compatibility

label pydantic-field

label = ''

Label of the patch

state_index pydantic-field

state_index = 0

Index of the state

odor_specification pydantic-field

odor_specification = [1.0, 0.0, 0.0]

A list of odor concentrations for the patch, where the index of the list corresponds to the odor channel

reward_specification pydantic-field

reward_specification = RewardSpecification()

The optional reward specification of the patch

patch_virtual_sites_generator pydantic-field

patch_virtual_sites_generator = PatchVirtualSitesGenerator()

Virtual site generation specification

patch_terminators pydantic-field

patch_terminators = [PatchTerminatorOnRejection()]

The optional termination specification of the patch

_Environment pydantic-model

Bases: BaseModel

Defines the statistical properties of the foraging environment.

This class specifies the patches available in the environment, their transition probabilities, and initial state occupancy. It forms the core specification for the foraging environment structure.

Fields:

• environment_type (str)
• patches (List[Patch])

environment_type pydantic-field

environment_type

patches pydantic-field

patches = [Patch()]

List of patches

MarkovEnvironment pydantic-model

Bases: _Environment

Defines the statistical properties of the foraging environment.

This class specifies the patches available in the environment, their transition probabilities, and initial state occupancy. It forms the core specification for the foraging environment structure.

Fields:

• patches (List[Patch])
• environment_type (Literal['Markov'])
• transition_matrix (List[List[NonNegativeFloat]])
• first_state_occupancy (Optional[List[NonNegativeFloat]])

Validators:

• _validate_transition_matrix → transition_matrix

environment_type pydantic-field

environment_type = 'Markov'

transition_matrix pydantic-field

transition_matrix = [[1]]

Determines the transition probabilities between patches

first_state_occupancy pydantic-field

first_state_occupancy = None

Determines the first state the animal will be in. If null, it will be randomly drawn.

patches pydantic-field

patches = [Patch()]

List of patches

SequenceEnvironment pydantic-model

Bases: _Environment

Defines a sequence-based foraging environment.

This class specifies a fixed sequence of patches that the animal will experience, without any probabilistic transitions. It is used for deterministic environment configurations where the order of patches is predefined.

Fields:

• patches (List[Patch])
• environment_type (Literal['Sequence'])
• patch_indices (List[int])
• sampling_mode (Literal['RandomWithoutReplacement', 'Ordered', 'RandomWithReplacement'])

Validators:

• _validate_patch_indices

environment_type pydantic-field

environment_type = 'Sequence'

patch_indices pydantic-field

patch_indices = [0]

Determines the sequence of patches the animal will experience. The index corresponds to Patch.state_index

sampling_mode pydantic-field

sampling_mode = 'RandomWithoutReplacement'

Determines how the sequence is sampled

patches pydantic-field

patches = [Patch()]

List of patches

MovableSpoutControl pydantic-model

Bases: BaseModel

Controls the movable water spout behavior for reward delivery.

This class configures how the movable spout operates, including when it's enabled, timing for reward collection, and retraction distance for operant conditioning protocols.

Fields:

• enabled (bool)
• time_to_collect_after_reward (float)
• retracting_distance (float)

enabled pydantic-field

enabled = False

Whether the movable spout is enabled

time_to_collect_after_reward pydantic-field

time_to_collect_after_reward = 1

Time (s) to collect after reward

retracting_distance pydantic-field

retracting_distance = 0

The distance, relative to the default position, the spout will be retracted by

PositionControl pydantic-model

Bases: BaseModel

Controls the position tracking and movement detection parameters.

This class manages the position control system including coordinate transformations, initial positioning, signal filtering, and movement detection thresholds for the virtual reality foraging task.

Fields:

• gain (Vector3)
• initial_position (Vector3)
• frequency_filter_cutoff (float)
• velocity_threshold (float)

gain pydantic-field

gain = Vector3(x=1, y=1, z=1)

Gain of the position control.

initial_position pydantic-field

initial_position = Vector3(x=0, y=2.56, z=0)

Initial position of the subject in the VR world.

frequency_filter_cutoff pydantic-field

frequency_filter_cutoff = 0.5

Cutoff frequency (Hz) of the low-pass filter used to filter the velocity signal.

velocity_threshold pydantic-field

velocity_threshold = 1

Threshold (cm/s) of the velocity signal used to detect when the animal is moving.

AudioControl pydantic-model

Bases: BaseModel

Controls audio feedback parameters for the task.

This class manages audio cue generation including tone duration and frequency for auditory feedback during the behavioral task.

Fields:

• duration (float)
• frequency (float)

duration pydantic-field

duration = 0.2

Duration

frequency pydantic-field

frequency = 1000

Frequency (Hz) of the audio cue

OdorControl pydantic-model

Bases: BaseModel

Controls the odor delivery system parameters.

This class manages the olfactory stimulus delivery system, including flow rates, valve timing, and carrier gas configuration. It ensures proper odor concentration and delivery timing for the behavioral task.

Fields:

• target_total_flow (int)
• target_odor_flow (int)

target_total_flow pydantic-field

target_total_flow = 1000

Target total flow (ml/s) of the odor mixture

target_odor_flow pydantic-field

target_odor_flow = 100

Target odor flow (ml/s) in the odor mixture

OperationControl pydantic-model

Bases: BaseModel

Master control class for all operational hardware systems.

This class aggregates all the hardware control specifications including movable spout, odor delivery, position tracking, and audio systems. It provides a centralized configuration point for all task hardware.

Fields:

• movable_spout_control (MovableSpoutControl)
• odor_control (OdorControl)
• position_control (PositionControl)
• audio_control (AudioControl)
• wait_to_start_duration (float)
• wait_to_finish_duration (float)

movable_spout_control pydantic-field

movable_spout_control = MovableSpoutControl()

Control of the movable spout

odor_control pydantic-field

odor_control = OdorControl(
    target_odor_flow=100, target_total_flow=1000
)

Control of the odor

position_control pydantic-field

position_control = PositionControl()

Control of the position

audio_control pydantic-field

audio_control = AudioControl()

Control of the audio

wait_to_start_duration pydantic-field

wait_to_start_duration = 0

Duration to wait before starting the task

wait_to_finish_duration pydantic-field

wait_to_finish_duration = 0

Duration to wait after finishing the task

_BlockEndConditionBase pydantic-model

Bases: BaseModel

Base class for block end conditions.

This is an internal base class that defines the common interface for all block end condition types. Should not be instantiated directly.

Fields:

• condition_type (str)

condition_type pydantic-field

condition_type

BlockEndConditionDuration pydantic-model

Bases: _BlockEndConditionBase

Block end condition based on time duration.

This condition ends a block after a specified amount of time has elapsed.

Fields:

• condition_type (Literal['Duration'])
• value (Distribution)

condition_type pydantic-field

condition_type = 'Duration'

value pydantic-field

value

Time after which the block ends.

BlockEndConditionDistance pydantic-model

Bases: _BlockEndConditionBase

Block end condition based on distance traveled.

This condition ends a block after the animal has traveled a specified distance.

Fields:

• condition_type (Literal['Distance'])
• value (Distribution)

condition_type pydantic-field

condition_type = 'Distance'

value pydantic-field

value

Distance after which the block ends.

BlockEndConditionChoice pydantic-model

Bases: _BlockEndConditionBase

Block end condition based on number of choices made.

This condition ends a block after the animal has made a specified number of choices (e.g., patch visits or reward attempts).

Fields:

• condition_type (Literal['Choice'])
• value (Distribution)

condition_type pydantic-field

condition_type = 'Choice'

value pydantic-field

value

Number of choices after which the block ends.

BlockEndConditionReward pydantic-model

Bases: _BlockEndConditionBase

Block end condition based on number of rewards obtained.

This condition ends a block after the animal has obtained a specified number of rewards.

Fields:

• condition_type (Literal['Reward'])
• value (Distribution)

condition_type pydantic-field

condition_type = 'Reward'

value pydantic-field

value

Number of rewards after which the block ends.

BlockEndConditionPatchCount pydantic-model

Bases: _BlockEndConditionBase

Block end condition based on number of patches visited.

This condition ends a block after the animal has visited a specified number of unique patches.

Fields:

• condition_type (Literal['PatchCount'])
• value (Distribution)

condition_type pydantic-field

condition_type = 'PatchCount'

value pydantic-field

value

Number of patches after which the block will end.

Block pydantic-model

Bases: BaseModel

Configuration for a single experimental block.

A block represents a period of the experiment with specific environment statistics and ending conditions. Each block defines the environmental parameters and termination criteria for that experimental phase.

Fields:

• environment (Environment)
• end_conditions (List[BlockEndCondition])

Validators:

• _migrate_legacy_environment

environment pydantic-field

environment = MarkovEnvironment()

Statistics of the environment

end_conditions pydantic-field

end_conditions = []

List of end conditions that must be true for the block to end.

BlockStructure pydantic-model

Bases: BaseModel

Structure defining the sequence and sampling of experimental blocks.

This class manages multiple experimental blocks and determines how they are presented during the experiment (sequentially or randomly).

Fields:

• blocks (List[Block])
• sampling_mode (Literal['Random', 'Sequential'])

blocks pydantic-field

blocks = [Block()]

Statistics of the environment

sampling_mode pydantic-field

sampling_mode = 'Sequential'

Sampling mode of the blocks.

AindVrForagingTaskParameters

Bases: TaskParameters

Complete parameter specification for the AIND VR Foraging task.

This class contains all configurable parameters for the VR foraging task, including environment structure, task mode settings, operation control, and numerical updaters for dynamic parameter modification.

updaters class-attribute instance-attribute

updaters = Field(
    default_factory=dict,
    description="Look-up table for numeric updaters",
)

environment class-attribute instance-attribute

environment = Field(
    default=BlockStructure(),
    description="Statistics of the environment",
    validate_default=True,
)

operation_control class-attribute instance-attribute

operation_control = Field(
    default=OperationControl(),
    description="Control of the operation",
    validate_default=True,
)

rng_seed class-attribute instance-attribute

rng_seed = Field(
    default=None,
    description="Seed of the random number generator",
)

aind_behavior_services_pkg_version class-attribute instance-attribute

aind_behavior_services_pkg_version = Field(
    default=__semver__,
    pattern=SEMVER_REGEX,
    title="aind_behavior_services package version",
    frozen=True,
)

coerce_version classmethod

coerce_version(v, ctx)

Source code in .venv/lib/python3.13/site-packages/aind_behavior_services/task/__init__.py

@field_validator("aind_behavior_services_pkg_version", mode="before", check_fields=False)
@classmethod
def coerce_version(cls, v: str, ctx) -> str:
    return coerce_schema_version(cls, v, ctx.field_name)

AindVrForagingTaskLogic

Bases: Task

Main task logic model for the AIND VR Foraging task.

This is the top-level class that encapsulates the complete task logic specification for the virtual reality foraging behavioral experiment. It includes all task parameters, environment specifications, and control settings.

version class-attribute instance-attribute

version = __semver__

name class-attribute instance-attribute

name = Field(
    default="AindVrForaging",
    description="Name of the task logic",
    frozen=True,
)

task_parameters class-attribute instance-attribute

task_parameters = Field(
    default=AindVrForagingTaskParameters(),
    description="Parameters of the task logic",
    validate_default=True,
)

coerce_version classmethod

coerce_version(v)

Source code in .venv/lib/python3.13/site-packages/aind_behavior_services/task/__init__.py

@field_validator("version", mode="before", check_fields=False)
@classmethod
def coerce_version(cls, v: str) -> str:
    return coerce_schema_version(cls, v)

scalar_value

scalar_value(value)

Helper function to create a scalar value distribution for a given value.

PARAMETER	DESCRIPTION
value	The value of the scalar distribution. TYPE: float

RETURNS	DESCRIPTION
Scalar	distributions.Scalar: The scalar distribution type.

Source code in src/packages/aind_behavior_vr_foraging/src/aind_behavior_vr_foraging/task_logic.py

def scalar_value(value: float) -> distributions.Scalar:
    """
    Helper function to create a scalar value distribution for a given value.

    Args:
        value (float): The value of the scalar distribution.

    Returns:
        distributions.Scalar: The scalar distribution type.
    """
    return distributions.Scalar(distribution_parameters=distributions.ScalarDistributionParameter(value=value))

_odor_mixture_from_odor_specification

_odor_mixture_from_odor_specification(value)

Source code in src/packages/aind_behavior_vr_foraging/src/aind_behavior_vr_foraging/task_logic.py

def _odor_mixture_from_odor_specification(value: Any):
    if isinstance(value, list):
        return value
    else:
        try:
            odor_spec = _OdorSpecification.model_validate(value)
            return [odor_spec.concentration if i == odor_spec.index else 0 for i in range(3)]
        except ValueError:
            pass
    return value