sl-shared-assets 1.0.0rc20__py3-none-any.whl → 1.0.0rc22__py3-none-any.whl

sl_shared_assets/data_classes/configuration_data.pyi

@@ -1,4 +1,4 @@
-from pathlib import Path as Path
+from pathlib import Path
 from dataclasses import field, dataclass
 
 from _typeshed import Incomplete
@@ -6,32 +6,190 @@ from ataraxis_data_structures import YamlConfig
 
 @dataclass()
 class ExperimentState:
-    """Encapsulates the information used to set and maintain the desired experiment and Mesoscope-VR system state.
+    """Encapsulates the information used to set and maintain the desired experiment and system state.
 
-    Primarily, experiment runtime logic (task logic) is resolved by the Unity game engine. However, the Mesoscope-VR
-    system configuration may also need to change throughout the experiment to optimize the runtime by disabling or
-    reconfiguring specific hardware modules. For example, some experiment stages may require the running wheel to be
-    locked to prevent the animal from running, and other may require the VR screens to be turned off.
+    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
-    vr_state_code: int
+    system_state_code: int
     state_duration_s: float
 
 @dataclass()
-class ExperimentConfiguration(YamlConfig):
-    """Stores the configuration of a single experiment runtime.
+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 Virtual Reality (Mesoscope-VR) 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.
+    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-run-experiment' CLI command exposed by the sl-experiment library is executed.
+    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 = ...
+
+@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 = ...
+    quantization_parameter: int = ...
+
+@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 = ...
+    mesoscope_start_ttl_module_id: int = ...
+    mesoscope_stop_ttl_module_id: int = ...
+    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

@@ -1,6 +1,7 @@
 """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 Mesoscope-VR system to the same state across training or experiment sessions of the same animal.
+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
@@ -9,19 +10,32 @@ from ataraxis_data_structures import YamlConfig
 
 
 @dataclass()
-class HardwareConfiguration(YamlConfig):
-    """This class is used to save the runtime hardware configuration parameters as a .yaml file.
+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
+        This class is automatically configured by _MesoscopeExperiment and _BehaviorTraining classes from sl-experiment
         library to facilitate log parsing.
     """
 
@@ -66,15 +80,7 @@ class HardwareConfiguration(YamlConfig):
 
 @dataclass()
 class LickTrainingDescriptor(YamlConfig):
-    """This class is used to save the description information specific to lick training sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    trained animal.
-    """
+    """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."""
@@ -90,7 +96,7 @@ class LickTrainingDescriptor(YamlConfig):
     """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 = 3
+    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."""
@@ -100,19 +106,14 @@ class LickTrainingDescriptor(YamlConfig):
     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):
-    """This class is used to save the description information specific to run training sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    trained animal.
-    """
+    """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."""
@@ -141,7 +142,7 @@ class RunTrainingDescriptor(YamlConfig):
     """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 = 3
+    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."""
@@ -155,19 +156,14 @@ class RunTrainingDescriptor(YamlConfig):
     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):
-    """This class is used to save the description information specific to experiment sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    animal participating in the experiment runtime.
-    """
+    """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."""
@@ -181,17 +177,24 @@ class MesoscopeExperimentDescriptor(YamlConfig):
     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):
-    """This class is used to save Zaber motor positions as a .yaml file to reuse them between sessions.
+    """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.
@@ -207,6 +210,9 @@ class ZaberPositions(YamlConfig):
     """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
@@ -217,8 +223,8 @@ class ZaberPositions(YamlConfig):
 
 @dataclass()
 class MesoscopePositions(YamlConfig):
-    """This class is used to save the real and virtual Mesoscope objective positions as a .yaml file to reuse it
-    between experiment sessions.
+    """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
@@ -229,17 +235,17 @@ class MesoscopePositions(YamlConfig):
         the experimenter manually entering all positions and setting the mesoscope to these positions when necessary.
     """
 
-    mesoscope_x_position: float = 0.0
+    mesoscope_x: float = 0.0
     """The X-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
-    mesoscope_y_position: float = 0.0
+    mesoscope_y: float = 0.0
     """The Y-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
-    mesoscope_roll_position: float = 0.0
+    mesoscope_roll: float = 0.0
     """The Roll-axis position, in degrees, of the Mesoscope objective used during session runtime."""
-    mesoscope_z_position: float = 0.0
+    mesoscope_z: float = 0.0
     """The Z-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
-    mesoscope_fast_z_position: float = 0.0
+    mesoscope_fast_z: float = 0.0
     """The Fast-Z-axis position, in micrometers, of the Mesoscope objective used during session runtime."""
-    mesoscope_tip_position: float = 0.0
+    mesoscope_tip: float = 0.0
     """The Tilt-axis position, in degrees, of the Mesoscope objective used during session runtime."""
-    mesoscope_tilt_position: float = 0.0
+    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

@@ -3,19 +3,32 @@ from dataclasses import dataclass
 from ataraxis_data_structures import YamlConfig
 
 @dataclass()
-class HardwareConfiguration(YamlConfig):
-    """This class is used to save the runtime hardware configuration parameters as a .yaml file.
+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
+        This class is automatically configured by _MesoscopeExperiment and _BehaviorTraining classes from sl-experiment
         library to facilitate log parsing.
     """
 
@@ -32,15 +45,7 @@ class HardwareConfiguration(YamlConfig):
 
 @dataclass()
 class LickTrainingDescriptor(YamlConfig):
-    """This class is used to save the description information specific to lick training sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    trained animal.
-    """
+    """Stores the task and outcome information specific to lick training sessions that use the Mesoscope-VR system."""
 
     experimenter: str
     mouse_weight_g: float
@@ -52,18 +57,11 @@ class LickTrainingDescriptor(YamlConfig):
     maximum_unconsumed_rewards: int = ...
     experimenter_notes: str = ...
     experimenter_given_water_volume_ml: float = ...
+    incomplete: bool = ...
 
 @dataclass()
 class RunTrainingDescriptor(YamlConfig):
-    """This class is used to save the description information specific to run training sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    trained animal.
-    """
+    """Stores the task and outcome information specific to run training sessions that use the Mesoscope-VR system."""
 
     experimenter: str
     mouse_weight_g: float
@@ -81,34 +79,32 @@ class RunTrainingDescriptor(YamlConfig):
     maximum_idle_time_s: float = ...
     experimenter_notes: str = ...
     experimenter_given_water_volume_ml: float = ...
+    incomplete: bool = ...
 
 @dataclass()
 class MesoscopeExperimentDescriptor(YamlConfig):
-    """This class is used to save the description information specific to experiment sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    animal participating in the experiment runtime.
-    """
+    """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):
-    """This class is used to save Zaber motor positions as a .yaml file to reuse them between sessions.
+    """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.
@@ -121,14 +117,15 @@ class ZaberPositions(YamlConfig):
     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):
-    """This class is used to save the real and virtual Mesoscope objective positions as a .yaml file to reuse it
-    between experiment sessions.
+    """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
@@ -139,10 +136,10 @@ class MesoscopePositions(YamlConfig):
         the experimenter manually entering all positions and setting the mesoscope to these positions when necessary.
     """
 
-    mesoscope_x_position: float = ...
-    mesoscope_y_position: float = ...
-    mesoscope_roll_position: float = ...
-    mesoscope_z_position: float = ...
-    mesoscope_fast_z_position: float = ...
-    mesoscope_tip_position: float = ...
-    mesoscope_tilt_position: float = ...
+    mesoscope_x: float = ...
+    mesoscope_y: float = ...
+    mesoscope_roll: float = ...
+    mesoscope_z: float = ...
+    mesoscope_fast_z: float = ...
+    mesoscope_tip: float = ...
+    mesoscope_tilt: float = ...