api.task_logic

_images/AindVrForagingTaskLogic.svg
pydantic model aind_behavior_vr_foraging.task_logic.AindVrForagingTaskLogic[source]

Bases: AindBehaviorTaskLogicModel

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.

Config:

  • extra: str = forbid

  • validate_assignment: bool = True

  • validate_default: bool = True

  • strict: bool = True

  • str_strip_whitespace: bool = True

Fields:
Validators:
field name: Literal['AindVrForaging'] = 'AindVrForaging'[source]

Name of the task logic

field task_parameters: AindVrForagingTaskParameters [Required][source]

Parameters of the task logic

field version: Literal[__version__] = '0.6.0-rc1'[source]
Validated by:

  • coerce_version

pydantic model aind_behavior_vr_foraging.task_logic.AindVrForagingTaskParameters[source]

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.

Config:

  • extra: str = allow

  • validate_assignment: bool = True

  • validate_default: bool = True

  • strict: bool = True

  • str_strip_whitespace: bool = True

Fields:
Validators:

field environment: BlockStructure [Required][source]

Statistics of the environment

field operation_control: OperationControl [Required][source]

Control of the operation

field updaters: Dict[UpdaterTarget, NumericalUpdater] [Optional][source]

Look-up table for numeric updaters

pydantic model aind_behavior_vr_foraging.task_logic.AudioControl[source]

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:
field duration: float = 0.2[source]

Duration

Constraints:

  • ge = 0

field frequency: float = 1000[source]

Frequency (Hz) of the audio cue

Constraints:

  • ge = 100

  • le = 9999

pydantic model aind_behavior_vr_foraging.task_logic.Block[source]

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:
field end_conditions: List[BlockEndCondition] = [][source]

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

field environment_statistics: EnvironmentStatistics [Required][source]

Statistics of the environment

pydantic model aind_behavior_vr_foraging.task_logic.BlockEndConditionChoice[source]

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:
field condition_type: Literal['Choice'] = 'Choice'[source]
field value: distributions.Distribution [Required][source]

Number of choices after which the block ends.

pydantic model aind_behavior_vr_foraging.task_logic.BlockEndConditionDistance[source]

Bases: _BlockEndConditionBase

Block end condition based on distance traveled.

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

Fields:
field condition_type: Literal['Distance'] = 'Distance'[source]
field value: distributions.Distribution [Required][source]

Distance after which the block ends.

pydantic model aind_behavior_vr_foraging.task_logic.BlockEndConditionDuration[source]

Bases: _BlockEndConditionBase

Block end condition based on time duration.

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

Fields:
field condition_type: Literal['Duration'] = 'Duration'[source]
field value: distributions.Distribution [Required][source]

Time after which the block ends.

pydantic model aind_behavior_vr_foraging.task_logic.BlockEndConditionPatchCount[source]

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:
field condition_type: Literal['PatchCount'] = 'PatchCount'[source]
field value: distributions.Distribution [Required][source]

Number of patches after which the block will end.

pydantic model aind_behavior_vr_foraging.task_logic.BlockEndConditionReward[source]

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:
field condition_type: Literal['Reward'] = 'Reward'[source]
field value: distributions.Distribution [Required][source]

Number of rewards after which the block ends.

pydantic model aind_behavior_vr_foraging.task_logic.BlockStructure[source]

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:
field blocks: List[Block] [Required][source]

Statistics of the environment

Constraints:

  • min_length = 1

field sampling_mode: Literal['Random', 'Sequential'] = 'Sequential'[source]

Sampling mode of the blocks.

pydantic model aind_behavior_vr_foraging.task_logic.ClampedMultiplicativeRateFunction[source]

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:
field function_type: Literal['ClampedMultiplicativeRateFunction'] = 'ClampedMultiplicativeRateFunction'[source]
field maximum: float | None [Required][source]

Maximum value of the rate

field minimum: float | None = 0[source]

Minimum value of the rate

field rate: distributions.Distribution [Required][source]

Rate of the replenishment, in value per rule unit.

pydantic model aind_behavior_vr_foraging.task_logic.ClampedRateFunction[source]

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:
field function_type: Literal['ClampedRateFunction'] = 'ClampedRateFunction'[source]
field maximum: float | None [Required][source]

Maximum value of the rate

field minimum: float | None = 0[source]

Minimum value of the rate

field rate: distributions.Distribution [Required][source]

Rate of the replenishment, in value per rule unit.

pydantic model aind_behavior_vr_foraging.task_logic.CtcmFunction[source]

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:
Validators:
field function_type: Literal['CtcmFunction'] = 'CtcmFunction'[source]
field maximum: float = 0[source]

Minimum value after update

field minimum: float = 1[source]

Maximum value after update

field rho: float [Required][source]

The underlying value goverining the stochastic process

field transition_matrix: List[List[NonNegativeFloat]] [Required][source]

Transition matrix between states

Validated by:
validator validate_transition_matrix  »  transition_matrix[source]

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

pydantic model aind_behavior_vr_foraging.task_logic.EnvironmentStatistics[source]

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:
Validators:
field first_state_occupancy: List[NonNegativeFloat] | None = None[source]

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

field patches: List[Patch] [Optional][source]

List of patches

Constraints:

  • min_length = 1

field transition_matrix: List[List[NonNegativeFloat]] = [[1]][source]

Determines the transition probabilities between patches

Validated by:

  • _validate_transition_matrix

pydantic model aind_behavior_vr_foraging.task_logic.LookupTableFunction[source]

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:
Validators:

  • _validate_lut » all fields

field function_type: Literal['LookupTableFunction'] = 'LookupTableFunction'[source]
Validated by:

  • _validate_lut

field lut_keys: List[float] [Required][source]

List of keys of the lookup table

Constraints:

  • min_length = 1

Validated by:

  • _validate_lut

field lut_values: List[float] [Required][source]

List of values of the lookup table

Constraints:

  • min_length = 1

Validated by:

  • _validate_lut

pydantic model aind_behavior_vr_foraging.task_logic.MovableSpoutControl[source]

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:
field enabled: bool = False[source]

Whether the movable spout is enabled

field retracting_distance: float = 0[source]

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

Constraints:

  • ge = 0

field time_to_collect_after_reward: float = 1[source]

Time (s) to collect after reward

Constraints:

  • ge = 0

pydantic model aind_behavior_vr_foraging.task_logic.NumericalUpdater[source]

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:
field operation: NumericalUpdaterOperation = NumericalUpdaterOperation.NONE[source]

Operation to perform on the parameter

field parameters: NumericalUpdaterParameters = NumericalUpdaterParameters(initial_value=0.0, increment=0.0, decrement=0.0, minimum=0.0, maximum=0.0)[source]

Parameters of the updater

class aind_behavior_vr_foraging.task_logic.NumericalUpdaterOperation(*values)[source]

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.

GAIN = 'Gain'[source]
NONE = 'None'[source]
OFFSET = 'Offset'[source]
OFFSETPERCENTAGE = 'OffsetPercentage'[source]
SET = 'Set'[source]
pydantic model aind_behavior_vr_foraging.task_logic.NumericalUpdaterParameters[source]

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:
field decrement: float = 0.0[source]

Value to decrement the parameter by

field increment: float = 0.0[source]

Value to increment the parameter by

field initial_value: float = 0.0[source]

Initial value of the parameter

field maximum: float = 0.0[source]

Minimum value of the parameter

field minimum: float = 0.0[source]

Minimum value of the parameter

pydantic model aind_behavior_vr_foraging.task_logic.OdorControl[source]

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:
field target_odor_flow: float = 100[source]

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

Constraints:

  • ge = 0

  • le = 100

field target_total_flow: float = 1000[source]

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

Constraints:

  • ge = 100

  • le = 1000

field use_channel_3_as_carrier: bool = True[source]

Whether to use channel 3 as carrier

field valve_max_open_time: float = 10[source]

Maximum time (s) the valve can be open continuously

Constraints:

  • ge = 0

pydantic model aind_behavior_vr_foraging.task_logic.OdorSpecification[source]

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:
field concentration: float = 1[source]

Concentration of the odor

Constraints:

  • ge = 0

  • le = 1

field index: int [Required][source]

Index of the odor to be used

Constraints:

  • ge = 0

  • le = 3

pydantic model aind_behavior_vr_foraging.task_logic.OnThisPatchEntryFunction[source]

Bases: _RewardFunction

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

Fields:
field function_type: Literal['OnThisPatchEntryFunction'] = 'OnThisPatchEntryFunction'[source]
field rule: Literal[RewardFunctionRule.ON_THIS_PATCH_ENTRY] = RewardFunctionRule.ON_THIS_PATCH_ENTRY[source]

Rule to trigger reward function

pydantic model aind_behavior_vr_foraging.task_logic.OperantLogic[source]

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:
field grace_distance_threshold: float = 10[source]

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

Constraints:

  • ge = 0

field is_operant: bool = True[source]

Will the trial implement operant logic

field stop_duration: float = 0[source]

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

Constraints:

  • ge = 0

field time_to_collect_reward: float = 100000[source]

Time(s) the animal has to collect the reward

Constraints:

  • ge = 0

pydantic model aind_behavior_vr_foraging.task_logic.OperationControl[source]

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:
field audio_control: AudioControl = AudioControl(duration=0.2, frequency=1000)[source]

Control of the audio

field movable_spout_control: MovableSpoutControl = MovableSpoutControl(enabled=False, time_to_collect_after_reward=1, retracting_distance=0)[source]

Control of the movable spout

field odor_control: OdorControl = OdorControl(valve_max_open_time=10, target_total_flow=1000, use_channel_3_as_carrier=True, target_odor_flow=100)[source]

Control of the odor

field position_control: PositionControl = PositionControl(gain=Vector3(x=1.0, y=1.0, z=1.0), initial_position=Vector3(x=0.0, y=2.56, z=0.0), frequency_filter_cutoff=0.5, velocity_threshold=1)[source]

Control of the position

pydantic model aind_behavior_vr_foraging.task_logic.OutsideRewardFunction[source]

Bases: _RewardFunction

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

Fields:
field delay: float = 0[source]

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

Constraints:

  • ge = 0

field function_type: Literal['OutsideRewardFunction'] = 'OutsideRewardFunction'[source]
field rule: Literal[RewardFunctionRule.ON_TIME, RewardFunctionRule.ON_DISTANCE, RewardFunctionRule.ON_TIME_ACCUMULATED, RewardFunctionRule.ON_DISTANCE_ACCUMULATED] = RewardFunctionRule.ON_TIME[source]

Rule to trigger reward function

pydantic model aind_behavior_vr_foraging.task_logic.Patch[source]

Bases: BaseModel

Represents statistics for a patch in the VR foraging task.

Fields:
field label: str = ''[source]

Label of the patch

field odor_specification: OdorSpecification | None = None[source]

The optional odor specification of the patch

field patch_terminators: List[PatchTerminator] = [PatchTerminatorOnRejection(terminator_type='OnRejection', count=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=1.0), truncation_parameters=None, scaling_parameters=None))][source]

The optional termination specification of the patch

field patch_virtual_sites_generator: PatchVirtualSitesGenerator = PatchVirtualSitesGenerator(inter_site=VirtualSiteGenerator(render_specification=RenderSpecification(contrast=None), label=<VirtualSiteLabels.INTERSITE: 'InterSite'>, length_distribution=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=20.0), truncation_parameters=None, scaling_parameters=None), treadmill_specification=None), inter_patch=VirtualSiteGenerator(render_specification=RenderSpecification(contrast=None), label=<VirtualSiteLabels.INTERPATCH: 'InterPatch'>, length_distribution=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=20.0), truncation_parameters=None, scaling_parameters=None), treadmill_specification=None), post_patch=None, reward_site=VirtualSiteGenerator(render_specification=RenderSpecification(contrast=None), label=<VirtualSiteLabels.REWARDSITE: 'RewardSite'>, length_distribution=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=20.0), truncation_parameters=None, scaling_parameters=None), treadmill_specification=None))[source]

Virtual site generation specification

field reward_specification: RewardSpecification = RewardSpecification(operant_logic=None, delay=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=0.0), truncation_parameters=None, scaling_parameters=None), amount=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=5.0), truncation_parameters=None, scaling_parameters=None), probability=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=1.0), truncation_parameters=None, scaling_parameters=None), available=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=5.0), truncation_parameters=None, scaling_parameters=None), reward_function=[])[source]

The optional reward specification of the patch

field state_index: int = 0[source]

Index of the state

Constraints:

  • ge = 0

pydantic model aind_behavior_vr_foraging.task_logic.PatchRewardFunction[source]

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:
field function_type: Literal['PatchRewardFunction'] = 'PatchRewardFunction'[source]
field rule: Literal[RewardFunctionRule.ON_REWARD, RewardFunctionRule.ON_CHOICE, RewardFunctionRule.ON_TIME, RewardFunctionRule.ON_DISTANCE, RewardFunctionRule.ON_CHOICE_ACCUMULATED, RewardFunctionRule.ON_REWARD_ACCUMULATED, RewardFunctionRule.ON_TIME_ACCUMULATED, RewardFunctionRule.ON_DISTANCE_ACCUMULATED] = RewardFunctionRule.ON_REWARD[source]

Rule to trigger reward function

pydantic model aind_behavior_vr_foraging.task_logic.PatchTerminatorOnChoice[source]

Bases: _PatchTerminator

Terminates the patch after “count” choices.

Fields:
field count: distributions.Distribution = Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=1.0), truncation_parameters=None, scaling_parameters=None)[source]

Number of choices the animal must make to terminate the patch

field terminator_type: Literal['OnChoice'] = 'OnChoice'[source]
pydantic model aind_behavior_vr_foraging.task_logic.PatchTerminatorOnDistance[source]

Bases: _PatchTerminator

Terminates the patch after a “count” distance.

Fields:
field count: distributions.Distribution [Required][source]

Number of distance units to wait before terminating the patch

field terminator_type: Literal['OnDistance'] = 'OnDistance'[source]
pydantic model aind_behavior_vr_foraging.task_logic.PatchTerminatorOnRejection[source]

Bases: _PatchTerminator

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

Fields:
field count: distributions.Distribution = Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=1.0), truncation_parameters=None, scaling_parameters=None)[source]

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

field terminator_type: Literal['OnRejection'] = 'OnRejection'[source]
pydantic model aind_behavior_vr_foraging.task_logic.PatchTerminatorOnReward[source]

Bases: _PatchTerminator

Terminates the patch after “count” rewards.

Fields:
field count: distributions.Distribution = Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=1.0), truncation_parameters=None, scaling_parameters=None)[source]

Number of rewards the animal must collect to terminate the patch

field terminator_type: Literal['OnReward'] = 'OnReward'[source]
pydantic model aind_behavior_vr_foraging.task_logic.PatchTerminatorOnTime[source]

Bases: _PatchTerminator

Terminates the patch after a “count” seconds.

Fields:
field count: distributions.Distribution [Required][source]

Number of seconds to wait before terminating the patch

field terminator_type: Literal['OnTime'] = 'OnTime'[source]
pydantic model aind_behavior_vr_foraging.task_logic.PatchVirtualSitesGenerator[source]

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:
field inter_patch: VirtualSiteGenerator = VirtualSiteGenerator(render_specification=RenderSpecification(contrast=None), label=<VirtualSiteLabels.INTERPATCH: 'InterPatch'>, length_distribution=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=20.0), truncation_parameters=None, scaling_parameters=None), treadmill_specification=None)[source]

Generator of the inter-patch virtual sites

field inter_site: VirtualSiteGenerator = VirtualSiteGenerator(render_specification=RenderSpecification(contrast=None), label=<VirtualSiteLabels.INTERSITE: 'InterSite'>, length_distribution=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=20.0), truncation_parameters=None, scaling_parameters=None), treadmill_specification=None)[source]

Generator of the inter-site virtual sites

field post_patch: VirtualSiteGenerator | None = None[source]

Generator of the post-patch virtual sites

field reward_site: VirtualSiteGenerator = VirtualSiteGenerator(render_specification=RenderSpecification(contrast=None), label=<VirtualSiteLabels.REWARDSITE: 'RewardSite'>, length_distribution=Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=20.0), truncation_parameters=None, scaling_parameters=None), treadmill_specification=None)[source]

Generator of the reward-site virtual sites

pydantic model aind_behavior_vr_foraging.task_logic.PositionControl[source]

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:
field frequency_filter_cutoff: float = 0.5[source]

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

Constraints:

  • ge = 0

  • le = 100

field gain: Vector3 = Vector3(x=1.0, y=1.0, z=1.0)[source]

Gain of the position control.

field initial_position: Vector3 = Vector3(x=0.0, y=2.56, z=0.0)[source]

Gain of the position control.

field velocity_threshold: float = 1[source]

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

Constraints:

  • ge = 0

pydantic model aind_behavior_vr_foraging.task_logic.RenderSpecification[source]

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:
field contrast: float | None = None[source]

Contrast of the texture

Constraints:

  • ge = 0

  • le = 1

class aind_behavior_vr_foraging.task_logic.RewardFunctionRule(*values)[source]

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_CHOICE = 'OnChoice'[source]
ON_CHOICE_ACCUMULATED = 'OnChoiceAccumulated'[source]
ON_DISTANCE = 'OnDistance'[source]
ON_DISTANCE_ACCUMULATED = 'OnDistanceAccumulated'[source]
ON_REWARD = 'OnReward'[source]
ON_REWARD_ACCUMULATED = 'OnRewardAccumulated'[source]
ON_THIS_PATCH_ENTRY = 'OnThisPatchEntry'[source]
ON_TIME = 'OnTime'[source]
ON_TIME_ACCUMULATED = 'OnTimeAccumulated'[source]
pydantic model aind_behavior_vr_foraging.task_logic.RewardSpecification[source]

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:
field amount: distributions.Distribution = Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=5.0), truncation_parameters=None, scaling_parameters=None)[source]

Initial amount of reward in microliters

field available: distributions.Distribution = Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=5.0), truncation_parameters=None, scaling_parameters=None)[source]

Initial amount of reward available in the patch in microliters

field delay: distributions.Distribution = Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=0.0), truncation_parameters=None, scaling_parameters=None)[source]

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

field operant_logic: OperantLogic | None = None[source]

The optional operant logic of the reward

field probability: distributions.Distribution = Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=1.0), truncation_parameters=None, scaling_parameters=None)[source]

Initial probability of reward delivery

field reward_function: List[RewardFunction] = [][source]

Reward function of the patch

pydantic model aind_behavior_vr_foraging.task_logic.SetValueFunction[source]

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:
field function_type: Literal['SetValueFunction'] = 'SetValueFunction'[source]
field value: distributions.Distribution [Required][source]

Sets the value of the target to this value.

pydantic model aind_behavior_vr_foraging.task_logic.Size[source]

Bases: BaseModel

Represents 2D dimensions with width and height.

Used for defining texture sizes, corridor dimensions, and other 2D measurements in the VR foraging environment.

Fields:
field height: float = 0[source]

Height of the texture

field width: float = 0[source]

Width of the texture

pydantic model aind_behavior_vr_foraging.task_logic.Texture[source]

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:
field name: str = 'default'[source]

Name of the texture

field size: Size = Size(width=40.0, height=40.0)[source]

Size of the texture

pydantic model aind_behavior_vr_foraging.task_logic.TreadmillSpecification[source]

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:
field friction: distributions.Distribution | None = None[source]

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

class aind_behavior_vr_foraging.task_logic.UpdaterTarget(*values)[source]

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.

REWARD_DELAY_OFFSET = 'RewardDelayOffset'[source]
STOP_DURATION_OFFSET = 'StopDurationOffset'[source]
STOP_VELOCITY_THRESHOLD = 'StopVelocityThreshold'[source]
pydantic model aind_behavior_vr_foraging.task_logic.Vector2[source]

Bases: BaseModel

Represents a 2D point or vector with x and y coordinates.

Used for positioning elements in 2D space within the VR environment, such as texture coordinates or 2D movement vectors.

Fields:
field x: float = 0[source]

X coordinate of the point

field y: float = 0[source]

Y coordinate of the point

pydantic model aind_behavior_vr_foraging.task_logic.Vector3[source]

Bases: BaseModel

Represents a 3D point or vector with x, y, and z coordinates.

Used for 3D positioning and movement in the virtual reality environment, including camera positions, object locations, and 3D transformations.

Fields:
field x: float = 0[source]

X coordinate of the point

field y: float = 0[source]

Y coordinate of the point

field z: float = 0[source]

Z coordinate of the point

pydantic model aind_behavior_vr_foraging.task_logic.VirtualSite[source]

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:
field id: int = 0[source]

Id of the virtual site

Constraints:

  • ge = 0

field label: VirtualSiteLabels = VirtualSiteLabels.UNSPECIFIED[source]

Label of the virtual site

field length: float = 20[source]

Length of the virtual site (cm)

field odor_specification: OdorSpecification | None = None[source]

The optional odor specification of the virtual site

field render_specification: RenderSpecification = RenderSpecification(contrast=None)[source]

The optional render specification of the virtual site

field reward_specification: RewardSpecification | None = None[source]

The optional reward specification of the virtual site

field start_position: float = 0[source]

Start position of the virtual site (cm)

Constraints:

  • ge = 0

field treadmill_specification: TreadmillSpecification | None = None[source]

Treadmill specification

pydantic model aind_behavior_vr_foraging.task_logic.VirtualSiteGenerator[source]

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:
field label: VirtualSiteLabels = VirtualSiteLabels.UNSPECIFIED[source]

Label of the virtual site

field length_distribution: distributions.Distribution = Scalar(family=<DistributionFamily.SCALAR: 'Scalar'>, distribution_parameters=ScalarDistributionParameter(family=<DistributionFamily.SCALAR: 'Scalar'>, value=20.0), truncation_parameters=None, scaling_parameters=None)[source]

Distribution of the length of the virtual site

field render_specification: RenderSpecification = RenderSpecification(contrast=None)[source]

Contrast of the environment

field treadmill_specification: TreadmillSpecification | None = None[source]

Treadmill specification

class aind_behavior_vr_foraging.task_logic.VirtualSiteLabels(*values)[source]

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.

INTERPATCH = 'InterPatch'[source]
INTERSITE = 'InterSite'[source]
POSTPATCH = 'PostPatch'[source]
REWARDSITE = 'RewardSite'[source]
UNSPECIFIED = 'Unspecified'[source]
pydantic model aind_behavior_vr_foraging.task_logic.VisualCorridor[source]

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:
field id: int = 0[source]

Id of the visual corridor object

Constraints:

  • ge = 0

field length: float = 120[source]

Length of the corridor site (cm)

Constraints:

  • ge = 0

field size: Size = Size(width=40.0, height=40.0)[source]

Size of the corridor (cm)

field start_position: float = 0[source]

Start position of the corridor (cm)

Constraints:

  • ge = 0

field textures: WallTextures [Required][source]

The textures of the corridor

pydantic model aind_behavior_vr_foraging.task_logic.WallTextures[source]

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:
field ceiling: Texture [Required][source]

The texture of the ceiling

field floor: Texture [Required][source]

The texture of the floor

field left: Texture [Required][source]

The texture of the left

field right: Texture [Required][source]

The texture of the right

aind_behavior_vr_foraging.task_logic.scalar_value(value: float) → Scalar[source]

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

Parameters:

value (float) – The value of the scalar distribution.

Returns:

The scalar distribution type.

Return type:

distributions.Scalar