sl-shared-assets 1.0.0__py3-none-any.whl

sl_shared_assets/data_classes/configuration_data.pyi

@@ -0,0 +1,199 @@
+from pathlib import Path
+from dataclasses import field, dataclass
+
+from _typeshed import Incomplete
+from ataraxis_data_structures import YamlConfig
+
+@dataclass()
+class ExperimentState:
+    """Encapsulates the information used to set and maintain the desired experiment and system state.
+
+    Broadly, each experiment runtime can be conceptualized as a two state-system. The first state is that of the
+    experimental task, which reflects the behavior goal, the rules for achieving the goal, and the reward for
+    achieving the goal. The second state is that of the data acquisition and experiment control system, which is a
+    snapshot of all hardware module states that make up the system that acquires the data and controls the task
+    environment. Overall, experiment state is about 'what the animal is doing', while the system state is about
+    'what the hardware is doing'.
+
+    Note:
+        This class is acquisition-system-agnostic. It can be used to define the ExperimentConfiguration class for any
+        valid data acquisition system.
+    """
+
+    experiment_state_code: int
+    system_state_code: int
+    state_duration_s: float
+
+@dataclass()
+class MesoscopeExperimentConfiguration(YamlConfig):
+    """Stores the configuration of a single experiment runtime that uses the Mesoscope_VR data acquisition system.
+
+    Primarily, this includes the sequence of experiment and system states that defines the flow of the experiment
+    runtime. During runtime, the main runtime control function traverses the sequence of states stored in this class
+    instance start-to-end in the exact order specified by the user. Together with custom Unity projects that define
+    the task logic (how the system responds to animal interactions with the VR system) this class allows flexibly
+    implementing a wide range of experiments using the Mesoscope-VR system.
+
+    Each project should define one or more experiment configurations and save them as .yaml files inside the project
+    'configuration' folder. The name for each configuration file is defined by the user and is used to identify and load
+    the experiment configuration when 'sl-experiment' CLI command exposed by the sl-experiment library is executed.
+
+    Notes:
+        This class is designed exclusively for the Mesoscope-VR system. Any other system needs to define a separate
+        ExperimentConfiguration class to specify its experiment runtimes and additional data.
+    """
+
+    cue_map: dict[int, float] = field(default_factory=Incomplete)
+    experiment_states: dict[str, ExperimentState] = field(default_factory=Incomplete)
+
+@dataclass()
+class MesoscopePaths:
+    """Stores the filesystem configuration parameters for the Mesoscope-VR data acquisition system."""
+
+    server_credentials_path: Path = ...
+    google_credentials_path: Path = ...
+    root_directory: Path = ...
+    server_storage_directory: Path = ...
+    server_working_directory: Path = ...
+    nas_directory: Path = ...
+    mesoscope_directory: Path = ...
+    harvesters_cti_path: Path = ...
+    server_processed_data_root: Path = ...
+    server_raw_data_root: Path = ...
+
+@dataclass()
+class MesoscopeCameras:
+    """Stores the configuration parameters for the cameras used by the Mesoscope-VR system to record behavior videos."""
+
+    face_camera_index: int = ...
+    left_camera_index: int = ...
+    right_camera_index: int = ...
+    face_camera_quantization_parameter: int = ...
+    body_camera_quantization_parameter: int = ...
+    display_face_camera_frames: bool = ...
+    display_body_camera_frames: bool = ...
+
+@dataclass()
+class MesoscopeMicroControllers:
+    """Stores the configuration parameters for the microcontrollers used by the Mesoscope-VR system."""
+
+    actor_port: str = ...
+    sensor_port: str = ...
+    encoder_port: str = ...
+    debug: bool = ...
+    mesoscope_ttl_pulse_duration_ms: int = ...
+    minimum_break_strength_g_cm: float = ...
+    maximum_break_strength_g_cm: float = ...
+    wheel_diameter_cm: float = ...
+    lick_threshold_adc: int = ...
+    lick_signal_threshold_adc: int = ...
+    lick_delta_threshold_adc: int = ...
+    lick_averaging_pool_size: int = ...
+    torque_baseline_voltage_adc: int = ...
+    torque_maximum_voltage_adc: int = ...
+    torque_sensor_capacity_g_cm: float = ...
+    torque_report_cw: bool = ...
+    torque_report_ccw: bool = ...
+    torque_signal_threshold_adc: int = ...
+    torque_delta_threshold_adc: int = ...
+    torque_averaging_pool_size: int = ...
+    wheel_encoder_ppr = ...
+    wheel_encoder_report_cw: bool = ...
+    wheel_encoder_report_ccw: bool = ...
+    wheel_encoder_delta_threshold_pulse: int = ...
+    wheel_encoder_polling_delay_us = ...
+    cm_per_unity_unit = ...
+    screen_trigger_pulse_duration_ms: int = ...
+    auditory_tone_duration_ms: int = ...
+    valve_calibration_pulse_count: int = ...
+    sensor_polling_delay_ms: int = ...
+    valve_calibration_data: dict[int | float, int | float] | tuple[tuple[int | float, int | float], ...] = ...
+
+@dataclass()
+class MesoscopeAdditionalFirmware:
+    """Stores the configuration parameters for all firmware and hardware components not assembled in the Sun lab."""
+
+    headbar_port: str = ...
+    lickport_port: str = ...
+    wheel_port: str = ...
+    unity_ip: str = ...
+    unity_port: int = ...
+
+@dataclass()
+class MesoscopeSystemConfiguration(YamlConfig):
+    """Stores the hardware and filesystem configuration parameters for the Mesoscope-VR data acquisition system used in
+    the Sun lab.
+
+    This class is specifically designed to encapsulate the configuration parameters for the Mesoscope-VR system. It
+    expects the system to be configured according to the specifications available from the sl_experiment repository
+    (https://github.com/Sun-Lab-NBB/sl-experiment) and should be used exclusively by the VRPC machine
+    (main Mesoscope-VR PC).
+
+    Notes:
+        Each SystemConfiguration class is uniquely tied to a specific hardware configuration used in the lab. This
+        class will only work with the Mesoscope-VR system. Any other data acquisition and runtime management system in
+        the lab should define its own SystemConfiguration class to specify its own hardware and filesystem configuration
+        parameters.
+    """
+
+    name: str = ...
+    paths: MesoscopePaths = field(default_factory=MesoscopePaths)
+    cameras: MesoscopeCameras = field(default_factory=MesoscopeCameras)
+    microcontrollers: MesoscopeMicroControllers = field(default_factory=MesoscopeMicroControllers)
+    additional_firmware: MesoscopeAdditionalFirmware = field(default_factory=MesoscopeAdditionalFirmware)
+    def __post_init__(self) -> None:
+        """Ensures that variables converted to different types for storage purposes are always set to expected types
+        upon class instantiation."""
+    def save(self, path: Path) -> None:
+        """Saves class instance data to disk as a 'mesoscope_system_configuration.yaml' file.
+
+        This method converts certain class variables to yaml-safe types (for example, Path objects -> strings) and
+        saves class data to disk as a .yaml file. The method is intended to be used solely by the
+        set_system_configuration_file() function and should not be called from any other context.
+
+        Args:
+            path: The path to the .yaml file to save the data to.
+        """
+
+_supported_configuration_files: Incomplete
+
+def set_system_configuration_file(path: Path) -> None:
+    """Sets the system configuration .yaml file specified by the input path as the default system configuration file for
+    the managed machine (PC).
+
+    This function is used to initially configure or override the existing configuration of any data acquisition system
+    used in the lab. The path to the configuration file is stored inside the user's data directory, so that all
+    Sun lab libraries can automatically access that information during every runtime. Since the storage directory is
+    typically hidden and varies between OSes and machines, this function provides a convenient way for setting that
+    path without manually editing the storage cache.
+
+    Notes:
+        If the input path does not point to an existing file, but the file name and extension are correct, the function
+        will automatically generate a default SystemConfiguration class instance and save it under the specified path.
+
+        A data acquisition system can include multiple machines (PCs). However, the configuration file is typically
+        only present on the 'main' machine that manages all runtimes.
+
+    Args:
+        path: The path to the new system configuration file to be used by the local data acquisition system (PC).
+
+    Raises:
+        ValueError: If the input path is not a valid system configuration file or does not use a supported data
+            acquisition system name.
+    """
+
+def get_system_configuration_data() -> MesoscopeSystemConfiguration:
+    """Resolves the path to the local system configuration file and loads the system configuration data.
+
+    This service function is used by all Sun lab data acquisition runtimes to load the system configuration data from
+    the shared configuration file. It supports resolving and returning the data for all data acquisition systems used
+    in the lab.
+
+    Returns:
+        The initialized SystemConfiguration class instance for the local acquisition system that stores the loaded
+        configuration parameters.
+
+    Raises:
+        FileNotFoundError: If the local machine does not have the Sun lab data directory, or the system configuration
+            file does not exist.
+    """

sl_shared_assets/data_classes/runtime_data.py

@@ -0,0 +1,251 @@
+"""This module provides classes used to store the training and experiment data acquired by the sl-experiment library.
+Some classes from this library store raw data later processed by Sun lab data processing pipelines. Others are used to
+restore the data acquisition and runtime management system to the same state across training or experiment sessions for
+the same animal.
+"""
+
+from dataclasses import dataclass
+
+from ataraxis_data_structures import YamlConfig
+
+
+@dataclass()
+class MesoscopeHardwareState(YamlConfig):
+    """Stores configuration parameters (states) of the Mesoscope-VR system hardware modules used during training or
+    experiment runtime.
+
+    This information is used to read and decode the data saved to the .npz log files during runtime as part of data
+    processing.
+
+    Notes:
+        This class stores 'static' Mesoscope-VR system configuration that does not change during experiment or training
+        session runtime. This is in contrast to MesoscopeExperimentState class, which reflects the 'dynamic' state of
+        the Mesoscope-VR system.
+
+        This class partially overlaps with the MesoscopeSystemConfiguration class, which is also stored in the
+        raw_data folder of each session. The primary reason to keep both classes is to ensure that the math (rounding)
+        used during runtime matches the math (rounding) used during data processing. MesoscopeSystemConfiguration does
+        not do any rounding or otherwise attempt to be repeatable, which is in contrast to hardware module that read
+        those parameters. Reading values from this class guarantees the read value exactly matches the value used
+        during runtime.
+
+    Notes:
+        All fields in this dataclass initialize to None. During log processing, any log associated with a hardware
+        module that provides the data stored in a field will be processed, unless that field is None. Therefore, setting
+        any field in this dataclass to None also functions as a flag for whether to parse the log associated with the
+        module that provides this field's information.
+
+        This class is automatically configured by _MesoscopeExperiment and _BehaviorTraining classes from sl-experiment
+        library to facilitate log parsing.
+    """
+
+    cue_map: dict[int, float] | None = None
+    """MesoscopeExperiment instance property. Stores the dictionary that maps the integer id-codes associated with each 
+    wall cue in the Virtual Reality task environment with distances in real-world centimeters animals should run on the 
+    wheel to fully traverse the cue region on a linearized track."""
+    cm_per_pulse: float | None = None
+    """EncoderInterface instance property. Stores the conversion factor used to translate encoder pulses into 
+    real-world centimeters."""
+    maximum_break_strength: float | None = None
+    """BreakInterface instance property. Stores the breaking torque, in Newton centimeters, applied by the break to 
+    the edge of the running wheel when it is engaged at 100% strength."""
+    minimum_break_strength: float | None = None
+    """BreakInterface instance property. Stores the breaking torque, in Newton centimeters, applied by the break to 
+    the edge of the running wheel when it is engaged at 0% strength (completely disengaged)."""
+    lick_threshold: int | None = None
+    """LickInterface instance property. Determines the threshold, in 12-bit Analog to Digital Converter (ADC) units, 
+    above which an interaction value reported by the lick sensor is considered a lick (compared to noise or non-lick 
+    touch)."""
+    valve_scale_coefficient: float | None = None
+    """ValveInterface instance property. To dispense precise water volumes during runtime, ValveInterface uses power 
+    law equation applied to valve calibration data to determine how long to keep the valve open. This stores the 
+    scale_coefficient of the power law equation that describes the relationship between valve open time and dispensed 
+    water volume, derived from calibration data."""
+    valve_nonlinearity_exponent: float | None = None
+    """ValveInterface instance property. To dispense precise water volumes during runtime, ValveInterface uses power 
+    law equation applied to valve calibration data to determine how long to keep the valve open. This stores the 
+    nonlinearity_exponent of the power law equation that describes the relationship between valve open time and 
+    dispensed water volume, derived from calibration data."""
+    torque_per_adc_unit: float | None = None
+    """TorqueInterface instance property. Stores the conversion factor used to translate torque values reported by the 
+    sensor as 12-bit Analog to Digital Converter (ADC) units, into real-world Newton centimeters (N·cm) of torque that 
+    had to be applied to the edge of the running wheel to produce the observed ADC value."""
+    screens_initially_on: bool | None = None
+    """ScreenInterface instance property. Stores the initial state of the Virtual Reality screens at the beginning of 
+    the session runtime."""
+    recorded_mesoscope_ttl: bool | None = None
+    """TTLInterface instance property. A boolean flag that determines whether the processed session recorded brain 
+    activity data with the mesoscope."""
+
+
+@dataclass()
+class LickTrainingDescriptor(YamlConfig):
+    """Stores the task and outcome information specific to lick training sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    """The ID of the experimenter running the session."""
+    mouse_weight_g: float
+    """The weight of the animal, in grams, at the beginning of the session."""
+    dispensed_water_volume_ml: float
+    """Stores the total water volume, in milliliters, dispensed during runtime."""
+    minimum_reward_delay: int
+    """Stores the minimum delay, in seconds, that can separate the delivery of two consecutive water rewards."""
+    maximum_reward_delay_s: int
+    """Stores the maximum delay, in seconds, that can separate the delivery of two consecutive water rewards."""
+    maximum_water_volume_ml: float
+    """Stores the maximum volume of water the system is allowed to dispense during training."""
+    maximum_training_time_m: int
+    """Stores the maximum time, in minutes, the system is allowed to run the training for."""
+    maximum_unconsumed_rewards: int = 1
+    """Stores the maximum number of consecutive rewards that can be delivered without the animal consuming them. If 
+    the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal 
+    consumes the rewards."""
+    experimenter_notes: str = "Replace this with your notes."
+    """This field is not set during runtime. It is expected that each experimenter replaces this field with their 
+    notes made during runtime."""
+    experimenter_given_water_volume_ml: float = 0.0
+    """The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.
+    """
+    incomplete: bool = False
+    """If this field is set to True, the session is marked as 'incomplete' and automatically excluded from all further 
+    Sun lab automated processing and analysis."""
+
+
+@dataclass()
+class RunTrainingDescriptor(YamlConfig):
+    """Stores the task and outcome information specific to run training sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    """The ID of the experimenter running the session."""
+    mouse_weight_g: float
+    """The weight of the animal, in grams, at the beginning of the session."""
+    dispensed_water_volume_ml: float
+    """Stores the total water volume, in milliliters, dispensed during runtime."""
+    final_run_speed_threshold_cm_s: float
+    """Stores the final running speed threshold, in centimeters per second, that was active at the end of training."""
+    final_run_duration_threshold_s: float
+    """Stores the final running duration threshold, in seconds, that was active at the end of training."""
+    initial_run_speed_threshold_cm_s: float
+    """Stores the initial running speed threshold, in centimeters per second, used during training."""
+    initial_run_duration_threshold_s: float
+    """Stores the initial running duration threshold, in seconds, used during training."""
+    increase_threshold_ml: float
+    """Stores the volume of water delivered to the animal, in milliliters, that triggers the increase in the running 
+    speed and duration thresholds."""
+    run_speed_increase_step_cm_s: float
+    """Stores the value, in centimeters per second, used by the system to increment the running speed threshold each 
+    time the animal receives 'increase_threshold' volume of water."""
+    run_duration_increase_step_s: float
+    """Stores the value, in seconds, used by the system to increment the duration threshold each time the animal 
+    receives 'increase_threshold' volume of water."""
+    maximum_water_volume_ml: float
+    """Stores the maximum volume of water the system is allowed to dispense during training."""
+    maximum_training_time_m: int
+    """Stores the maximum time, in minutes, the system is allowed to run the training for."""
+    maximum_unconsumed_rewards: int = 1
+    """Stores the maximum number of consecutive rewards that can be delivered without the animal consuming them. If 
+    the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal 
+    consumes the rewards."""
+    maximum_idle_time_s: float = 0.0
+    """Stores the maximum time, in seconds, the animal can dip below the running speed threshold to still receive the 
+    reward. This allows animals that 'run' by taking a series of large steps, briefly dipping below speed threshold at 
+    the end of each step, to still get water rewards."""
+    experimenter_notes: str = "Replace this with your notes."
+    """This field is not set during runtime. It is expected that each experimenter will replace this field with their 
+    notes made during runtime."""
+    experimenter_given_water_volume_ml: float = 0.0
+    """The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.
+    """
+    incomplete: bool = False
+    """If this field is set to True, the session is marked as 'incomplete' and automatically excluded from all further 
+    Sun lab automated processing and analysis."""
+
+
+@dataclass()
+class MesoscopeExperimentDescriptor(YamlConfig):
+    """Stores the task and outcome information specific to experiment sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    """The ID of the experimenter running the session."""
+    mouse_weight_g: float
+    """The weight of the animal, in grams, at the beginning of the session."""
+    dispensed_water_volume_ml: float
+    """Stores the total water volume, in milliliters, dispensed during runtime."""
+    experimenter_notes: str = "Replace this with your notes."
+    """This field is not set during runtime. It is expected that each experimenter will replace this field with their 
+    notes made during runtime."""
+    experimenter_given_water_volume_ml: float = 0.0
+    """The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.
+    """
+    incomplete: bool = False
+    """If this field is set to True, the session is marked as 'incomplete' and automatically excluded from all further 
+    Sun lab automated processing and analysis."""
+
+
+@dataclass()
+class ZaberPositions(YamlConfig):
+    """Stores Zaber motor positions reused between experiment sessions that use the Mesoscope-VR system.
+
+    The class is specifically designed to store, save, and load the positions of the LickPort and HeadBar motors
+    (axes). It is used to both store Zaber motor positions for each session for future analysis and to restore the same
+    Zaber motor positions across consecutive runtimes for the same project and animal combination.
+
+    Notes:
+        The HeadBar axis (connection) also manages the motor that moves the running wheel along the x-axis. While the
+        motor itself is not part of the HeadBar assembly, it is related to positioning the mouse in the VR system. This
+        is in contrast to the LickPort group, which is related to positioning the lick tube relative to the mouse.
+
+        All positions are saved using native motor units. All class fields initialize to default placeholders that are
+        likely NOT safe to apply to the VR system. Do not apply the positions loaded from the file unless you are
+        certain they are safe to use.
+
+        Exercise caution when working with Zaber motors. The motors are powerful enough to damage the surrounding
+        equipment and manipulated objects. Do not modify the data stored inside the .yaml file unless you know what you
+        are doing.
+    """
+
+    headbar_z: int = 0
+    """The absolute position, in native motor units, of the HeadBar z-axis motor."""
+    headbar_pitch: int = 0
+    """The absolute position, in native motor units, of the HeadBar pitch-axis motor."""
+    headbar_roll: int = 0
+    """The absolute position, in native motor units, of the HeadBar roll-axis motor."""
+    wheel_x: int = 0
+    """The absolute position, in native motor units, of the running wheel platform x-axis motor. Although this motor is
+    not itself part of the HeadBar assembly, it is controlled through the HeadBar controller port."""
+    lickport_z: int = 0
+    """The absolute position, in native motor units, of the LickPort z-axis motor."""
+    lickport_x: int = 0
+    """The absolute position, in native motor units, of the LickPort x-axis motor."""
+    lickport_y: int = 0
+    """The absolute position, in native motor units, of the LickPort y-axis motor."""
+
+
+@dataclass()
+class MesoscopePositions(YamlConfig):
+    """Stores real and virtual Mesoscope objective positions reused between experiment sessions that use the
+    Mesoscope-VR system.
+
+    Primarily, the class is used to help the experimenter to position the Mesoscope at the same position across
+    multiple imaging sessions. It stores both the physical (real) position of the objective along the motorized
+    X, Y, Z, and Roll axes and the virtual (ScanImage software) tip, tilt, and fastZ focus axes.
+
+    Notes:
+        Since the API to read and write these positions automatically is currently not available, this class relies on
+        the experimenter manually entering all positions and setting the mesoscope to these positions when necessary.
+    """
+
+    mesoscope_x: float = 0.0
+    """The X-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    mesoscope_y: float = 0.0
+    """The Y-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    mesoscope_roll: float = 0.0
+    """The Roll-axis position, in degrees, of the Mesoscope objective used during session runtime."""
+    mesoscope_z: float = 0.0
+    """The Z-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    mesoscope_fast_z: float = 0.0
+    """The Fast-Z-axis position, in micrometers, of the Mesoscope objective used during session runtime."""
+    mesoscope_tip: float = 0.0
+    """The Tilt-axis position, in degrees, of the Mesoscope objective used during session runtime."""
+    mesoscope_tilt: float = 0.0
+    """The Tip-axis position, in degrees, of the Mesoscope objective used during session runtime."""

sl_shared_assets/data_classes/runtime_data.pyi

@@ -0,0 +1,145 @@
+from dataclasses import dataclass
+
+from ataraxis_data_structures import YamlConfig
+
+@dataclass()
+class MesoscopeHardwareState(YamlConfig):
+    """Stores configuration parameters (states) of the Mesoscope-VR system hardware modules used during training or
+    experiment runtime.
+
+    This information is used to read and decode the data saved to the .npz log files during runtime as part of data
+    processing.
+
+    Notes:
+        This class stores 'static' Mesoscope-VR system configuration that does not change during experiment or training
+        session runtime. This is in contrast to MesoscopeExperimentState class, which reflects the 'dynamic' state of
+        the Mesoscope-VR system.
+
+        This class partially overlaps with the MesoscopeSystemConfiguration class, which is also stored in the
+        raw_data folder of each session. The primary reason to keep both classes is to ensure that the math (rounding)
+        used during runtime matches the math (rounding) used during data processing. MesoscopeSystemConfiguration does
+        not do any rounding or otherwise attempt to be repeatable, which is in contrast to hardware module that read
+        those parameters. Reading values from this class guarantees the read value exactly matches the value used
+        during runtime.
+
+    Notes:
+        All fields in this dataclass initialize to None. During log processing, any log associated with a hardware
+        module that provides the data stored in a field will be processed, unless that field is None. Therefore, setting
+        any field in this dataclass to None also functions as a flag for whether to parse the log associated with the
+        module that provides this field's information.
+
+        This class is automatically configured by _MesoscopeExperiment and _BehaviorTraining classes from sl-experiment
+        library to facilitate log parsing.
+    """
+
+    cue_map: dict[int, float] | None = ...
+    cm_per_pulse: float | None = ...
+    maximum_break_strength: float | None = ...
+    minimum_break_strength: float | None = ...
+    lick_threshold: int | None = ...
+    valve_scale_coefficient: float | None = ...
+    valve_nonlinearity_exponent: float | None = ...
+    torque_per_adc_unit: float | None = ...
+    screens_initially_on: bool | None = ...
+    recorded_mesoscope_ttl: bool | None = ...
+
+@dataclass()
+class LickTrainingDescriptor(YamlConfig):
+    """Stores the task and outcome information specific to lick training sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    mouse_weight_g: float
+    dispensed_water_volume_ml: float
+    minimum_reward_delay: int
+    maximum_reward_delay_s: int
+    maximum_water_volume_ml: float
+    maximum_training_time_m: int
+    maximum_unconsumed_rewards: int = ...
+    experimenter_notes: str = ...
+    experimenter_given_water_volume_ml: float = ...
+    incomplete: bool = ...
+
+@dataclass()
+class RunTrainingDescriptor(YamlConfig):
+    """Stores the task and outcome information specific to run training sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    mouse_weight_g: float
+    dispensed_water_volume_ml: float
+    final_run_speed_threshold_cm_s: float
+    final_run_duration_threshold_s: float
+    initial_run_speed_threshold_cm_s: float
+    initial_run_duration_threshold_s: float
+    increase_threshold_ml: float
+    run_speed_increase_step_cm_s: float
+    run_duration_increase_step_s: float
+    maximum_water_volume_ml: float
+    maximum_training_time_m: int
+    maximum_unconsumed_rewards: int = ...
+    maximum_idle_time_s: float = ...
+    experimenter_notes: str = ...
+    experimenter_given_water_volume_ml: float = ...
+    incomplete: bool = ...
+
+@dataclass()
+class MesoscopeExperimentDescriptor(YamlConfig):
+    """Stores the task and outcome information specific to experiment sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    mouse_weight_g: float
+    dispensed_water_volume_ml: float
+    experimenter_notes: str = ...
+    experimenter_given_water_volume_ml: float = ...
+    incomplete: bool = ...
+
+@dataclass()
+class ZaberPositions(YamlConfig):
+    """Stores Zaber motor positions reused between experiment sessions that use the Mesoscope-VR system.
+
+    The class is specifically designed to store, save, and load the positions of the LickPort and HeadBar motors
+    (axes). It is used to both store Zaber motor positions for each session for future analysis and to restore the same
+    Zaber motor positions across consecutive runtimes for the same project and animal combination.
+
+    Notes:
+        The HeadBar axis (connection) also manages the motor that moves the running wheel along the x-axis. While the
+        motor itself is not part of the HeadBar assembly, it is related to positioning the mouse in the VR system. This
+        is in contrast to the LickPort group, which is related to positioning the lick tube relative to the mouse.
+
+        All positions are saved using native motor units. All class fields initialize to default placeholders that are
+        likely NOT safe to apply to the VR system. Do not apply the positions loaded from the file unless you are
+        certain they are safe to use.
+
+        Exercise caution when working with Zaber motors. The motors are powerful enough to damage the surrounding
+        equipment and manipulated objects. Do not modify the data stored inside the .yaml file unless you know what you
+        are doing.
+    """
+
+    headbar_z: int = ...
+    headbar_pitch: int = ...
+    headbar_roll: int = ...
+    wheel_x: int = ...
+    lickport_z: int = ...
+    lickport_x: int = ...
+    lickport_y: int = ...
+
+@dataclass()
+class MesoscopePositions(YamlConfig):
+    """Stores real and virtual Mesoscope objective positions reused between experiment sessions that use the
+    Mesoscope-VR system.
+
+    Primarily, the class is used to help the experimenter to position the Mesoscope at the same position across
+    multiple imaging sessions. It stores both the physical (real) position of the objective along the motorized
+    X, Y, Z, and Roll axes and the virtual (ScanImage software) tip, tilt, and fastZ focus axes.
+
+    Notes:
+        Since the API to read and write these positions automatically is currently not available, this class relies on
+        the experimenter manually entering all positions and setting the mesoscope to these positions when necessary.
+    """
+
+    mesoscope_x: float = ...
+    mesoscope_y: float = ...
+    mesoscope_roll: float = ...
+    mesoscope_z: float = ...
+    mesoscope_fast_z: float = ...
+    mesoscope_tip: float = ...
+    mesoscope_tilt: float = ...