sl-shared-assets 3.0.0rc8__py3-none-any.whl → 3.0.0rc10__py3-none-any.whl

sl_shared_assets/data_classes/configuration_data.py

@@ -44,7 +44,7 @@ class ExperimentState:
     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
+    recovery_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."""
@@ -72,8 +72,15 @@ class ExperimentTrial:
     """The length of the trial cue sequence, in Unity units."""
     trial_length_cm: float
     """The length of the trial cue sequence in centimeters."""
-    trial_reward_size_ul: float = 5.0
+    trial_reward_size_ul: float
     """The volume of water, in microliters, to be dispensed when the animal successfully completes the trial task."""
+    reward_zone_start_cm: float
+    """Specifies the starting boundary of the trial reward zone, in centimeters."""
+    reward_zone_end_cm: float
+    """Specifies the ending boundary of the trial reward zone, in centimeters."""
+    guidance_trigger_location_cm: float
+    """Specifies the location of the invisible boundary (wall) with which the animal must collide to elicit automated 
+    water reward during guided trials."""
 
 
 # noinspection PyArgumentList
@@ -101,7 +108,7 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     environment to its length in real-world centimeters. It is used to map each VR cue to the distance the animal needs
     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 starting position is shifted 
+    """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. 
@@ -115,7 +122,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(
@@ -123,7 +130,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(
@@ -131,7 +138,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,
             ),
         }
@@ -141,10 +148,13 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     trial_structures: dict[str, ExperimentTrial] = field(
         default_factory=lambda: {
             "cyclic_4_cue": ExperimentTrial(
-                cue_sequence=[0, 1, 0, 2, 0, 3, 0, 4],
+                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,
+                reward_zone_end_cm=222.0,
+                guidance_trigger_location_cm=208.0,
             )
         }
     )
@@ -245,9 +255,6 @@ class MesoscopeMicroControllers:
     """Determines whether to run the managed acquisition system in the 'debug mode'. This mode should be disabled 
     during most runtimes. It is used during initial system calibration and testing and prints a lot of generally 
     redundant information into the terminal."""
-    mesoscope_ttl_pulse_duration_ms: int = 10
-    """The duration of the HIGH phase of all outgoing TTL pulses that target the Mesoscope (enable or disable mesoscope
-    frame acquisition), in milliseconds."""
     minimum_break_strength_g_cm: float = 43.2047
     """The minimum torque applied by the running wheel break in gram centimeter. This is the torque the break delivers 
     at minimum voltage (break is disabled)."""
@@ -267,8 +274,10 @@ class MesoscopeMicroControllers:
     """The minimum absolute difference in raw analog units recorded by a 12-bit Analog-to-Digital-Converter (ADC) for 
     the change to be reported to the PC. This is used to prevent reporting repeated non-lick or lick readouts to the 
     PC, conserving communication bandwidth."""
-    lick_averaging_pool_size: int = 10
-    """The number of lick sensor readouts to average together to produce the final lick sensor readout value."""
+    lick_averaging_pool_size: int = 1
+    """The number of lick sensor readouts to average together to produce the final lick sensor readout value. Note, 
+    when using a Teensy controller, this number is multiplied by the built-in analog readout averaging (default is 4).
+    """
     torque_baseline_voltage_adc: int = 2046
     """The voltage level, in raw analog units measured by 3.3v Analog-to-Digital-Converter (ADC) at 12-bit resolution 
     after the AD620 amplifier, that corresponds to no (0) torque readout. Usually, for a 3.3v ADC, this would be 
@@ -292,8 +301,10 @@ class MesoscopeMicroControllers:
     """The minimum absolute difference in raw analog units recorded by a 12-bit Analog-to-Digital-Converter (ADC) for 
     the change to be reported to the PC. This is used to prevent reporting repeated static torque readouts to the 
     PC, conserving communication bandwidth."""
-    torque_averaging_pool_size: int = 10
-    """The number of torque sensor readouts to average together to produce the final torque sensor readout value."""
+    torque_averaging_pool_size: int = 1
+    """The number of torque sensor readouts to average together to produce the final torque sensor readout value. Note, 
+    when using a Teensy controller, this number is multiplied by the built-in analog readout averaging (default is 4).
+    """
     wheel_encoder_ppr: int = 8192
     """The resolution of the managed quadrature encoder, in Pulses Per Revolution (PPR). This is the number of 
     quadrature pulses the encoder emits per full 360-degree rotation."""

sl_shared_assets/data_classes/configuration_data.pyi

@@ -24,7 +24,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()
@@ -41,7 +41,10 @@ class ExperimentTrial:
     cue_sequence: list[int]
     trial_length_unity_unit: float
     trial_length_cm: float
-    trial_reward_size_ul: float = ...
+    trial_reward_size_ul: float
+    reward_zone_start_cm: float
+    reward_zone_end_cm: float
+    guidance_trigger_location_cm: float
 
 @dataclass()
 class MesoscopeExperimentConfiguration(YamlConfig):
@@ -107,7 +110,6 @@ class MesoscopeMicroControllers:
     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 = ...

sl_shared_assets/data_classes/runtime_data.py

@@ -205,10 +205,6 @@ class ZaberPositions(YamlConfig):
     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.
@@ -226,13 +222,12 @@ 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()
@@ -240,9 +235,9 @@ 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
+    Primarily, the class is used to help the experimenter to position the Mesoscope on the same imaging plane 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.
+    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
@@ -250,16 +245,18 @@ class MesoscopePositions(YamlConfig):
     """
 
     mesoscope_x: float = 0.0
-    """The X-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    """The X-axis position, in centimeters, of the Mesoscope objective."""
     mesoscope_y: float = 0.0
-    """The Y-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    """The Y-axis position, in centimeters, of the Mesoscope objective."""
     mesoscope_roll: float = 0.0
-    """The Roll-axis position, in degrees, of the Mesoscope objective used during session runtime."""
+    """The Roll-axis position, in degrees, of the Mesoscope objective."""
     mesoscope_z: float = 0.0
-    """The Z-axis position, in centimeters, of the Mesoscope objective used during session runtime."""
+    """The Z-axis position, in centimeters, of the Mesoscope objective."""
     mesoscope_fast_z: float = 0.0
-    """The Fast-Z-axis position, in micrometers, of the Mesoscope objective used during session runtime."""
+    """The Fast-Z-axis (virtual Z) position, in micrometers."""
     mesoscope_tip: float = 0.0
-    """The Tilt-axis position, in degrees, of the Mesoscope objective used during session runtime."""
+    """The Tilt-axis (software) position, in degrees.."""
     mesoscope_tilt: float = 0.0
-    """The Tip-axis position, in degrees, of the Mesoscope objective used during session runtime."""
+    """The Tip-axis (software) position, in degrees."""
+    laser_power_mw: float = 0.0
+    """The excitation laser power delivered to the sample, in milliwatts."""

sl_shared_assets/data_classes/runtime_data.pyi

@@ -106,10 +106,6 @@ class ZaberPositions(YamlConfig):
     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.
@@ -123,8 +119,8 @@ class ZaberPositions(YamlConfig):
     headbar_pitch: int = ...
     headbar_roll: int = ...
     lickport_z: int = ...
-    lickport_x: int = ...
     lickport_y: int = ...
+    lickport_x: int = ...
     wheel_x: int = ...
 
 @dataclass()
@@ -132,9 +128,9 @@ 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
+    Primarily, the class is used to help the experimenter to position the Mesoscope on the same imaging plane 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.
+    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
@@ -148,3 +144,4 @@ class MesoscopePositions(YamlConfig):
     mesoscope_fast_z: float = ...
     mesoscope_tip: float = ...
     mesoscope_tilt: float = ...
+    laser_power_mw: float = ...

sl_shared_assets/data_classes/session_data.py

@@ -414,6 +414,11 @@ class SessionData(YamlConfig):
             )
             sh.copy2(experiment_configuration_path, instance.raw_data.experiment_configuration_path)
 
+        # All newly created sessions are marked with the 'nk.bin' file. If the marker is not removed during runtime,
+        # the session becomes a valid target for deletion (purging) runtimes operating from the main acquisition
+        # machine of any data acquisition system.
+        instance.raw_data.nk_path.touch()
+
         # Returns the initialized SessionData instance to caller
         return instance
 
@@ -493,6 +498,15 @@ class SessionData(YamlConfig):
         # Returns the initialized SessionData instance to caller
         return instance
 
+    def runtime_initialized(self) -> None:
+        """Ensures that the 'nk.bin' marker file is removed from the session's raw_data folder.
+
+        This marker is generated as part of the SessionData initialization (creation) process to mark sessions that did
+        not fully initialize during runtime. This service method is designed to be called by the inner runtime control
+        functions and classes of the sl-experiment library and generally should not be called by end-users.
+        """
+        self.raw_data.nk_path.unlink(missing_ok=True)
+
     def _save(self) -> None:
         """Saves the instance data to the 'raw_data' directory of the managed session as a 'session_data.yaml' file.
 

sl_shared_assets/data_classes/session_data.pyi

@@ -191,6 +191,13 @@ class SessionData(YamlConfig):
         Raises:
             FileNotFoundError: If the 'session_data.yaml' file is not found under the session_path/raw_data/ subfolder.
 
+        """
+    def runtime_initialized(self) -> None:
+        """Ensures that the 'nk.bin' marker file is removed from the session's raw_data folder.
+
+        This marker is generated as part of the SessionData initialization (creation) process to mark sessions that did
+        not fully initialize during runtime. This service method is designed to be called by the inner runtime control
+        functions and classes of the sl-experiment library and generally should not be called by end-users.
         """
     def _save(self) -> None:
         """Saves the instance data to the 'raw_data' directory of the managed session as a 'session_data.yaml' file.

sl_shared_assets/tools/ascension_tools.py

@@ -226,6 +226,9 @@ def ascend_tyche_data(root_directory: Path) -> None:
                     experiment_name=None,
                 )
 
+                # Since this runtime reprocesses already acquired data, marks the session as fully initialized.
+                session_data.runtime_initialized()
+
                 # Moves the data from the old hierarchy to the new hierarchy. If the process runs as expected, and
                 # fully empties the source acquisition folder, destroys the folder. Otherwise, notifies the user that
                 # the runtime did not fully process the session data and requests intervention.

{sl_shared_assets-3.0.0rc8.dist-info → sl_shared_assets-3.0.0rc10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sl-shared-assets
-Version: 3.0.0rc8
+Version: 3.0.0rc10
 Summary: Provides data acquisition and processing assets shared between Sun (NeuroAI) lab libraries.
 Project-URL: Homepage, https://github.com/Sun-Lab-NBB/sl-shared-assets
 Project-URL: Documentation, https://sl-shared-assets-api-docs.netlify.app/

{sl_shared_assets-3.0.0rc8.dist-info → sl_shared_assets-3.0.0rc10.dist-info}/RECORD

@@ -5,12 +5,12 @@ sl_shared_assets/cli.pyi,sha256=8ZJK56_jh2QlF3XCN6c7fI6Z022XtehB0eCrQDJbAsU,5515
 sl_shared_assets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sl_shared_assets/data_classes/__init__.py,sha256=SUDN7gFngUPEa7Da_G0PjXwnF9Q0S4EgvjpKe3KSr5g,1852
 sl_shared_assets/data_classes/__init__.pyi,sha256=J-tUXAtGEasacVU1qGFFksvfB1tFdEO-GKs90vSTAcg,2022
-sl_shared_assets/data_classes/configuration_data.py,sha256=0uKfFrUO-9xI3MvWNf2xxGZ_RuxJ7MW3yjHXAqPNPeA,34782
-sl_shared_assets/data_classes/configuration_data.pyi,sha256=DNsz6HCs0cPBP7Sn7G_-Y9z_fTFd0ub2s-97wlrPcb4,10723
-sl_shared_assets/data_classes/runtime_data.py,sha256=O98BZg7i7cEUlpIE16JswKOwQNRsS5RxVdBzXYvAw00,16543
-sl_shared_assets/data_classes/runtime_data.pyi,sha256=i8CuZd9p0Nu43xhpE62pB07AiovZIgtMZYN5wQjz-r0,6861
-sl_shared_assets/data_classes/session_data.py,sha256=3MwnDSUJt4PLMcFfQMg7gt5ogoxP2kuc6n98qYFldOc,44699
-sl_shared_assets/data_classes/session_data.pyi,sha256=rgab48TLjWMtSIg2qIuXRG1rQhs_2WfItjEl-MaRW8U,13654
+sl_shared_assets/data_classes/configuration_data.py,sha256=bTkfJqQfNdw-vnsZfzLBE_rLFR_YoiYM3BZQt08Syp4,35425
+sl_shared_assets/data_classes/configuration_data.pyi,sha256=9X06Zsuj2p3XTOdb651rBnZ2RYdRzlv1F7KiMOtNF_8,10781
+sl_shared_assets/data_classes/runtime_data.py,sha256=MwNe_Ilg-DwfgboYafizRj--05z85WsIHQimxDUqI0w,15937
+sl_shared_assets/data_classes/runtime_data.pyi,sha256=BX4sPgr47pitg24N2fvCIFxjG_s9DkqCimF8hiO7Jmo,6545
+sl_shared_assets/data_classes/session_data.py,sha256=yUcHYajAv0SKir2HOHYSMkXkusFL5XP_KfkzzvkmnX0,45576
+sl_shared_assets/data_classes/session_data.pyi,sha256=hNNElZHOe5hlQAStkNqkYYl1UbfGh88LchYjBIqdreY,14153
 sl_shared_assets/data_classes/surgery_data.py,sha256=qsMj3NkjhylAT9b_wHBY-1XwTu2xsZcZatdECmkA7Bs,7437
 sl_shared_assets/data_classes/surgery_data.pyi,sha256=rf59lJ3tGSYKHQlEGXg75MnjajBwl0DYhL4TClAO4SM,2605
 sl_shared_assets/server/__init__.py,sha256=w7y73RXXjBrWQsjU5g1QNCv_gsXDYnHos3NpOoR2AHA,452
@@ -21,7 +21,7 @@ sl_shared_assets/server/server.py,sha256=MGk1v49aEFeIChMDsiR7CXjVkWwDpD9kA1TK0fw
 sl_shared_assets/server/server.pyi,sha256=5Yxq4txhjtd9w-6U9fPehzMeIZL5GcprVCHd9mPP6FI,15113
 sl_shared_assets/tools/__init__.py,sha256=NktXk62E_HHOrO_93z_MVmSd6-Oir3mE4xE9Yr8Qa7U,682
 sl_shared_assets/tools/__init__.pyi,sha256=0UXorfCXXmHQOP5z7hODpsqEX0DAkOta5VZqN6FSS-w,623
-sl_shared_assets/tools/ascension_tools.py,sha256=o5R-M0VCJg1RwH6-2fYjMK-9yBgzJ22YVLQee17Mmw0,14431
+sl_shared_assets/tools/ascension_tools.py,sha256=1cDs6Nx3woL9UPESQBpMbP7mC5URxCdPmjpU_GN87c4,14595
 sl_shared_assets/tools/ascension_tools.pyi,sha256=c-SI9TYJ1vmJXMV2pSW9Nri4mlySF8MtXqrvRvz5C8s,3705
 sl_shared_assets/tools/packaging_tools.py,sha256=QikjeaE_A8FyVJi3cnWLeW-hUXy1-FF1N23muA5VfT4,7526
 sl_shared_assets/tools/packaging_tools.pyi,sha256=vgGbAQCExwg-0A5F72MzEhzHxu97Nqg1yuz-5P89ycU,3118
@@ -29,8 +29,8 @@ sl_shared_assets/tools/project_management_tools.py,sha256=Z_U0R26w9Le1O-u66gyF5C
 sl_shared_assets/tools/project_management_tools.pyi,sha256=4kok98nOZ4KnT-Sg-ZCZYg-WIM5qZqiyK8g1XiiDjHM,10375
 sl_shared_assets/tools/transfer_tools.py,sha256=J26kwOp_NpPSY0-xu5FTw9udte-rm_mW1FJyaTNoqQI,6606
 sl_shared_assets/tools/transfer_tools.pyi,sha256=FoH7eYZe7guGHfPr0MK5ggO62uXKwD2aJ7h1Bu7PaEE,3294
-sl_shared_assets-3.0.0rc8.dist-info/METADATA,sha256=pvUOjPIynm4Ue5yT2eV4eg4-cNw8_fGT_HPot8lbRcE,49309
-sl_shared_assets-3.0.0rc8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sl_shared_assets-3.0.0rc8.dist-info/entry_points.txt,sha256=UmO1rl7ly9N7HWPwWyP9E0b5KBUStpBo4TRoqNtizDY,430
-sl_shared_assets-3.0.0rc8.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-sl_shared_assets-3.0.0rc8.dist-info/RECORD,,
+sl_shared_assets-3.0.0rc10.dist-info/METADATA,sha256=OpcKZWppCyDoGafIiWowtf9p9HZcdbV2lEuQPADmAqY,49310
+sl_shared_assets-3.0.0rc10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sl_shared_assets-3.0.0rc10.dist-info/entry_points.txt,sha256=UmO1rl7ly9N7HWPwWyP9E0b5KBUStpBo4TRoqNtizDY,430
+sl_shared_assets-3.0.0rc10.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+sl_shared_assets-3.0.0rc10.dist-info/RECORD,,