sl-shared-assets 3.0.0rc9__py3-none-any.whl → 3.0.0rc11__py3-none-any.whl

sl_shared_assets/__init__.py

@@ -20,6 +20,7 @@ from .data_classes import (
     SessionData,
     SubjectData,
     SurgeryData,
+    SessionTypes,
     InjectionData,
     ProcedureData,
     ProcessedData,
@@ -29,6 +30,7 @@ from .data_classes import (
     ExperimentTrial,
     MesoscopeCameras,
     ProcessingTracker,
+    AcquisitionSystems,
     MesoscopePositions,
     RunTrainingDescriptor,
     LickTrainingDescriptor,
@@ -79,6 +81,8 @@ __all__ = [
     "get_system_configuration_data",
     "set_system_configuration_file",
     "ExperimentTrial",
+    "SessionTypes",
+    "AcquisitionSystems",
     # Tools package
     "resolve_p53_marker",
     "transfer_directory",

sl_shared_assets/__init__.pyi

@@ -16,6 +16,7 @@ from .data_classes import (
     SessionData as SessionData,
     SubjectData as SubjectData,
     SurgeryData as SurgeryData,
+    SessionTypes as SessionTypes,
     InjectionData as InjectionData,
     ProcedureData as ProcedureData,
     ProcessedData as ProcessedData,
@@ -25,6 +26,7 @@ from .data_classes import (
     ExperimentTrial as ExperimentTrial,
     MesoscopeCameras as MesoscopeCameras,
     ProcessingTracker as ProcessingTracker,
+    AcquisitionSystems as AcquisitionSystems,
     MesoscopePositions as MesoscopePositions,
     RunTrainingDescriptor as RunTrainingDescriptor,
     LickTrainingDescriptor as LickTrainingDescriptor,
@@ -69,6 +71,8 @@ __all__ = [
     "get_system_configuration_data",
     "set_system_configuration_file",
     "ExperimentTrial",
+    "SessionTypes",
+    "AcquisitionSystems",
     "resolve_p53_marker",
     "transfer_directory",
     "calculate_directory_checksum",

sl_shared_assets/data_classes/__init__.py

@@ -11,7 +11,7 @@ from .runtime_data import (
     MesoscopeHardwareState,
     MesoscopeExperimentDescriptor,
 )
-from .session_data import RawData, SessionData, ProcessedData, ProcessingTracker
+from .session_data import RawData, SessionData, SessionTypes, ProcessedData, ProcessingTracker
 from .surgery_data import (
     DrugData,
     ImplantData,
@@ -25,6 +25,7 @@ from .configuration_data import (
     ExperimentState,
     ExperimentTrial,
     MesoscopeCameras,
+    AcquisitionSystems,
     MesoscopeMicroControllers,
     MesoscopeAdditionalFirmware,
     MesoscopeSystemConfiguration,
@@ -60,4 +61,6 @@ __all__ = [
     "MesoscopeAdditionalFirmware",
     "ProcessingTracker",
     "ExperimentTrial",
+    "AcquisitionSystems",
+    "SessionTypes",
 ]

sl_shared_assets/data_classes/__init__.pyi

@@ -9,6 +9,7 @@ from .runtime_data import (
 from .session_data import (
     RawData as RawData,
     SessionData as SessionData,
+    SessionTypes as SessionTypes,
     ProcessedData as ProcessedData,
     ProcessingTracker as ProcessingTracker,
 )
@@ -25,6 +26,7 @@ from .configuration_data import (
     ExperimentState as ExperimentState,
     ExperimentTrial as ExperimentTrial,
     MesoscopeCameras as MesoscopeCameras,
+    AcquisitionSystems as AcquisitionSystems,
     MesoscopeMicroControllers as MesoscopeMicroControllers,
     MesoscopeAdditionalFirmware as MesoscopeAdditionalFirmware,
     MesoscopeSystemConfiguration as MesoscopeSystemConfiguration,
@@ -60,4 +62,6 @@ __all__ = [
     "MesoscopeAdditionalFirmware",
     "ProcessingTracker",
     "ExperimentTrial",
+    "AcquisitionSystems",
+    "SessionTypes",
 ]

sl_shared_assets/data_classes/configuration_data.py

@@ -3,6 +3,7 @@ projects use classes from this module to configure experiment runtimes and deter
 particular data acquisition and runtime management system (hardware) they run on."""
 
 import copy
+from enum import StrEnum
 from pathlib import Path
 from dataclasses import field, dataclass
 
@@ -11,16 +12,23 @@ from ataraxis_base_utilities import LogLevel, console, ensure_directory_exists
 from ataraxis_data_structures import YamlConfig
 
 
+class AcquisitionSystems(StrEnum):
+    """Defines the set of data acquisition systems used in the Sun lab and supported by all data-related libraries."""
+
+    MESOSCOPE_VR = "mesoscope-vr"
+    """The Mesoscope-VR data acquisition system. It is built around 2-Photon Random Access Mesoscope (2P-RAM) and 
+    relies on Unity-backed virtual reality task-environments to conduct experiments."""
+
+
 @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'.
+    Broadly, each experiment runtime can be conceptualized as a two state-system. The first is the experiment task,
+    which reflects the behavior goal, the rules for achieving the goal, and the reward for achieving the goal. The
+    second is the data acquisition system state, 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
@@ -35,24 +43,25 @@ class ExperimentState:
     while maintaining the same experiment state."""
     system_state_code: int
     """One of the supported system state-codes. Note, the meaning of each system state code depends on the specific 
-    data acquisition and experiment control system used by the project. For example, projects using the 'mesoscope-vr' 
-    system currently support two system state codes: REST (1) and RUN (2)."""
+    data acquisition and experiment control system used by the project. For details on available system-states, see 
+    the sl-experiment library documentation."""
     state_duration_s: float
-    """The time, in seconds, to maintain the current combination of the experiment and system states."""
+    """The time, in seconds, to maintain the experiment and system state combination specified by this instance."""
     initial_guided_trials: int
-    """Specifies the number of trials (laps) at the onset of the experiment state, for which lick guidance will be 
-    automatically enabled. Specifically, if the experiment state supports running linearized Virtual Reality track, the 
-    system will enable lick guidance for this many trials at the beginning of the experiment state and automatically 
-    disable it for the following trials."""
-    failed_trial_threshold: int
-    """Specifies the number of failed (non-rewarded) non-guided trials (laps), after which the system will re-enable 
-    guidance for the 'recovery_guided_trials' number of following trials. For this to take effect, the trials must be 
-    failed this many times in a row."""
+    """The number of trials (laps) at the onset of the experiment state, for which to enable lick guidance. This 
+    determines the number of trials, counting from the onset of the experiment state, for which the animal will receive 
+    water rewards from entering the reward zone. Once the specified number of guided trial passes, the system disables 
+    guidance, requiring the animal to lick in the reward zone to get water rewards."""
+    recovery_failed_trial_threshold: int
+    """Specifies the number of failed (non-rewarded) trials (laps), after which the system will re-enable lick guidance 
+    for the 'recovery_guided_trials' number of following trials. Note, engaging the recovery guided trial system 
+    requires the specified number of failed trials to occur sequentially."""
     recovery_guided_trials: int
-    """Specifies the number of trials (laps) for which the system will re-enable lick guidance, when the animal 
-    repeatedly fails 'failed_trial_threshold' number of trials. This field works similar to the 'initial_guided_trials' 
-    field, but is triggered by repeated performance failures, rather than experiment state onset. After the animal 
-    runs this many guided trials, the system will automatically disable guidance for the following trials."""
+    """Specifies the number of trials (laps) for which the system should re-enable lick guidance, when the animal 
+    sequentially fails 'failed_trial_threshold' number of trials. This field works similar to the 
+    'initial_guided_trials' field, but is triggered by repeated performance failures, rather than experiment state 
+    onset. After the animal runs this many guided trials, the system automatically disables guidance for the following 
+    trials."""
 
 
 @dataclass()
@@ -60,16 +69,15 @@ class ExperimentTrial:
     """Encapsulates information about a single experiment trial.
 
     All Virtual Reality tasks can be broadly conceptualized as repeating motifs (sequences) of wall cues,
-    associated with a specific rewarded goal. These repeated motifs are typically used to define experiment trials
-    during analysis. Since some experiments can use multiple trial types as part of the same experiment session,
-    multiple instances of this class can be used to specify supported trial structures and trial parameters for a
-    given experiment.
+    associated with a specific goal, for which animals receive water rewards. Since some experiments can use multiple
+    trial types as part of the same experiment session, multiple instances of this class can be used to specify
+    supported trial structures and trial parameters for a given experiment.
     """
 
     cue_sequence: list[int]
-    """Specifies the sequence of wall cues experienced by the animal while running this trial."""
-    trial_length_unity_unit: float
-    """The length of the trial cue sequence, in Unity units."""
+    """Specifies the sequence of wall cues experienced by the animal while running this trial. Note, the cues must be 
+    specified as integer-codes, where each code has the same meaning as in the 'cue_map' dictionary of the main 
+    ExperimentConfiguration class for that experiment."""
     trial_length_cm: float
     """The length of the trial cue sequence in centimeters."""
     trial_reward_size_ul: float
@@ -89,10 +97,11 @@ 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.
+    runtime and the configuration of various trials supported by 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
@@ -101,6 +110,8 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     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.
+
+        To create a new experiment configuration, use the 'sl-create-experiment' CLI command.
     """
 
     cue_map: dict[int, float] = field(default_factory=lambda: {0: 30.0, 1: 30.0, 2: 30.0, 3: 30.0, 4: 30.0})
@@ -109,12 +120,12 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     to travel to fully traverse the wall cue region from start to end."""
     cue_offset_cm: float = 10.0
     """Specifies the positive offset distance, in centimeters, by which the animal's running track is shifted 
-    relative to experiment environment onset. Due to how the VR environment is revealed to the animal, most runtimes 
-    need to shift the animal slightly forward relative to the track origin (0), to prevent it from seeing the area 
-    before the first VR wall cue when the task starts and when the animal is teleported to the beginning of the track. 
-    This offset statically shifts the entire track (in centimeters) against the set of VR wall cues used during 
-    runtime. Storing this static offset as part of experiment configuration is crucial for correctly interpreting the 
-    data acquiring during runtime."""
+    relative to VR wall cue sequence. Due to how the VR environment is revealed to the animal, most runtimes 
+    need to shift the animal slightly forward relative to the VR cue sequence origin (0), to prevent it from seeing the 
+    area before the first VR wall cue when the task starts and when the animal is teleported to the beginning of the 
+    track. This offset statically shifts the entire track (in centimeters) against the set of VR wall cues used during 
+    runtime. Storing this static offset as part of experiment configuration is crucial for correctly mapping what the 
+    animal sees during runtime to the real-world distance it travels on the running wheel."""
     experiment_states: dict[str, ExperimentState] = field(
         default_factory=lambda: {
             "baseline": ExperimentState(
@@ -122,7 +133,7 @@ class MesoscopeExperimentConfiguration(YamlConfig):
                 system_state_code=1,
                 state_duration_s=30,
                 initial_guided_trials=0,
-                failed_trial_threshold=0,
+                recovery_failed_trial_threshold=0,
                 recovery_guided_trials=0,
             ),
             "experiment": ExperimentState(
@@ -130,7 +141,7 @@ class MesoscopeExperimentConfiguration(YamlConfig):
                 system_state_code=2,
                 state_duration_s=120,
                 initial_guided_trials=3,
-                failed_trial_threshold=6,
+                recovery_failed_trial_threshold=6,
                 recovery_guided_trials=3,
             ),
             "cooldown": ExperimentState(
@@ -138,7 +149,7 @@ class MesoscopeExperimentConfiguration(YamlConfig):
                 system_state_code=1,
                 state_duration_s=15,
                 initial_guided_trials=1000000,
-                failed_trial_threshold=0,
+                recovery_failed_trial_threshold=0,
                 recovery_guided_trials=0,
             ),
         }
@@ -149,7 +160,6 @@ class MesoscopeExperimentConfiguration(YamlConfig):
         default_factory=lambda: {
             "cyclic_4_cue": ExperimentTrial(
                 cue_sequence=[1, 0, 2, 0, 3, 0, 4, 0],
-                trial_length_unity_unit=24.0,
                 trial_length_cm=240.0,
                 trial_reward_size_ul=5.0,
                 reward_zone_start_cm=208.0,
@@ -158,7 +168,7 @@ class MesoscopeExperimentConfiguration(YamlConfig):
             )
         }
     )
-    """A dictionary that maps human-readable trial structure names as keys and ExperimentTrial instances as values. 
+    """A dictionary that uses human-readable trial structure names as keys and ExperimentTrial instances as values. 
     Each ExperimentTrial instance specifies the Virtual Reality layout and runtime parameters associated with a single 
     type of trials supported by the experiment runtime."""
 

sl_shared_assets/data_classes/configuration_data.pyi

@@ -1,19 +1,24 @@
+from enum import StrEnum
 from pathlib import Path
 from dataclasses import field, dataclass
 
 from _typeshed import Incomplete
 from ataraxis_data_structures import YamlConfig
 
+class AcquisitionSystems(StrEnum):
+    """Defines the set of data acquisition systems used in the Sun lab and supported by all data-related libraries."""
+
+    MESOSCOPE_VR = "mesoscope-vr"
+
 @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'.
+    Broadly, each experiment runtime can be conceptualized as a two state-system. The first is the experiment task,
+    which reflects the behavior goal, the rules for achieving the goal, and the reward for achieving the goal. The
+    second is the data acquisition system state, 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
@@ -24,7 +29,7 @@ class ExperimentState:
     system_state_code: int
     state_duration_s: float
     initial_guided_trials: int
-    failed_trial_threshold: int
+    recovery_failed_trial_threshold: int
     recovery_guided_trials: int
 
 @dataclass()
@@ -32,14 +37,12 @@ class ExperimentTrial:
     """Encapsulates information about a single experiment trial.
 
     All Virtual Reality tasks can be broadly conceptualized as repeating motifs (sequences) of wall cues,
-    associated with a specific rewarded goal. These repeated motifs are typically used to define experiment trials
-    during analysis. Since some experiments can use multiple trial types as part of the same experiment session,
-    multiple instances of this class can be used to specify supported trial structures and trial parameters for a
-    given experiment.
+    associated with a specific goal, for which animals receive water rewards. Since some experiments can use multiple
+    trial types as part of the same experiment session, multiple instances of this class can be used to specify
+    supported trial structures and trial parameters for a given experiment.
     """
 
     cue_sequence: list[int]
-    trial_length_unity_unit: float
     trial_length_cm: float
     trial_reward_size_ul: float
     reward_zone_start_cm: float
@@ -51,10 +54,11 @@ 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.
+    runtime and the configuration of various trials supported by 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
@@ -63,6 +67,8 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     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.
+
+        To create a new experiment configuration, use the 'sl-create-experiment' CLI command.
     """
 
     cue_map: dict[int, float] = field(default_factory=Incomplete)

sl_shared_assets/data_classes/runtime_data.py

@@ -19,15 +19,15 @@ class MesoscopeHardwareState(YamlConfig):
 
     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.
+        session runtime. This is in contrast to MesoscopeExperimentConfiguration class, which reflects the 'dynamic'
+        state of the Mesoscope-VR system during each experiment.
 
         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.
+        not do any rounding or otherwise attempt to be repeatable, which is in contrast to hardware modules that read
+        and apply 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
@@ -35,17 +35,14 @@ class MesoscopeHardwareState(YamlConfig):
         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.
+        This class is automatically configured by _MesoscopeVRSystem class from sl-experiment library to facilitate
+        proper 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."""
+    real-world centimeters. This conversion factor is fixed for each data acquisition system and does not change 
+    between experiments."""
     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."""
@@ -75,10 +72,11 @@ class MesoscopeHardwareState(YamlConfig):
     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."""
+    activity data with the mesoscope. In that case, attempts to parse the Mesoscope frame scanning TTL pulse data to 
+    synchronize Mesoscope data to behavior data."""
     system_state_codes: dict[str, int] | None = None
-    """A MesoscopeVRSystem property. A dictionary that maps integer state-codes used by the Mesoscope-VR system to 
-    communicate its states to human-readable state names."""
+    """A _MesoscopeVRSystem instance property. A dictionary that maps integer state-codes used by the Mesoscope-VR 
+    system to communicate its states (system states) to human-readable state names."""
 
 
 @dataclass()
@@ -196,26 +194,40 @@ class MesoscopeExperimentDescriptor(YamlConfig):
     Sun lab automated processing and analysis."""
 
 
+@dataclass()
+class WindowCheckingDescriptor(YamlConfig):
+    """Stores the outcome information specific to window checking sessions that use the Mesoscope-VR system.
+
+    Notes:
+        Window Checking sessions are different from all other sessions. Unlike other sessions, their purpose is not to
+        generate data, but rather to assess the suitability of the particular animal to be included in training and
+        experiment cohorts. These sessions are automatically excluded from any automated data processing and analysis.
+    """
+
+    experimenter: str
+    """The ID of the experimenter running the session."""
+    experimenter_notes: str = "Replace this with your notes."
+    """The notes on the quality of the cranial window and animal's suitability for the target project."""
+    surgery_quality: int = 0
+    """The quality of the cranial window and surgical intervention on a scale from 0 (non-usable) to 
+    3 (high-tier publication grade) inclusive."""
+    incomplete: bool = True
+    """Window checking sessions are always considered 'incomplete', as they do not contain the full range of 
+    information collected as part of a 'standard' behavior training or experiment session."""
+
+
 @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.
+    The class is specifically designed to store, save, and load the positions of the LickPort, HeadBar, and Wheel motors
+    (axes). It is used to both store Zaber motor positions for each session for future analysis and to restore the
+    Zaber motors to the same 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.
+        By default, the class initializes all fields to 0, which is the position of the home sensor for each motor. The
+        class assumes that the motor groups are assembled and arranged in a way that ensures all motors can safely move
+        to the home sensor positions from any runtime configuration.
     """
 
     headbar_z: int = 0
@@ -226,40 +238,37 @@ class ZaberPositions(YamlConfig):
     """The absolute position, in native motor units, of the HeadBar roll-axis motor."""
     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."""
+    lickport_x: int = 0
+    """The absolute position, in native motor units, of the LickPort x-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."""
+    """The absolute position, in native motor units, of the running wheel platform x-axis motor."""
 
 
 @dataclass()
 class MesoscopePositions(YamlConfig):
-    """Stores real and virtual Mesoscope objective positions reused between experiment sessions that use the
+    """Stores the positions of real and virtual Mesoscope objective axes 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.
+    This class is designed to help the experimenter move the Mesoscope to the same imaging plane across 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 (virtual zoom) axes.
     """
 
     mesoscope_x: float = 0.0
-    """The X-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    """The Mesoscope objective X-axis position, in centimeters."""
     mesoscope_y: float = 0.0
-    """The Y-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    """The Mesoscope objective Y-axis position, in centimeters."""
     mesoscope_roll: float = 0.0
-    """The Roll-axis position, in degrees, of the Mesoscope objective used during session runtime."""
+    """The Mesoscope objective Roll-axis position, in degrees."""
     mesoscope_z: float = 0.0
-    """The Z-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    """The Mesoscope objective Z-axis position, in centimeters."""
     mesoscope_fast_z: float = 0.0
-    """The Fast-Z-axis position, in micrometers, of the Mesoscope objective used during session runtime."""
+    """The ScanImage FastZ (virtual Z-axis) position, in micrometers."""
     mesoscope_tip: float = 0.0
-    """The Tilt-axis position, in degrees, of the Mesoscope objective used during session runtime."""
+    """The ScanImage Tilt position, in degrees.."""
     mesoscope_tilt: float = 0.0
-    """The Tip-axis position, in degrees, of the Mesoscope objective used during session runtime."""
+    """The ScanImage Tip position, in degrees."""
+    laser_power_mw: float = 0.0
+    """The laser excitation power at the sample, in milliwatts."""