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

sl_shared_assets/data_classes/runtime_data.pyi

@@ -12,15 +12,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
@@ -28,11 +28,10 @@ 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 = ...
     cm_per_pulse: float | None = ...
     maximum_break_strength: float | None = ...
     minimum_break_strength: float | None = ...
@@ -97,48 +96,51 @@ class MesoscopeExperimentDescriptor(YamlConfig):
     experimenter_given_water_volume_ml: float = ...
     incomplete: bool = ...
 
+@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
+    experimenter_notes: str = ...
+    surgery_quality: int = ...
+    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.
+    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 = ...
     headbar_pitch: int = ...
     headbar_roll: int = ...
     lickport_z: int = ...
-    lickport_x: int = ...
     lickport_y: int = ...
+    lickport_x: int = ...
     wheel_x: int = ...
 
 @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 = ...
@@ -148,3 +150,4 @@ class MesoscopePositions(YamlConfig):
     mesoscope_fast_z: float = ...
     mesoscope_tip: float = ...
     mesoscope_tilt: float = ...
+    laser_power_mw: float = ...