sl-shared-assets 3.0.0rc7__tar.gz → 3.0.0rc9__tar.gz

{sl_shared_assets-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sl-shared-assets
-Version: 3.0.0rc7
+Version: 3.0.0rc9
 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.0rc7 → sl_shared_assets-3.0.0rc9}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 # Project metdata section. Provides the genral ID information about the project.
 [project]
 name = "sl-shared-assets"
-version = "3.0.0rc7"
+version = "3.0.0rc9"
 description = "Provides data acquisition and processing assets shared between Sun (NeuroAI) lab libraries."
 readme = "README.md"
 license = { file = "LICENSE" }

{sl_shared_assets-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/sl_shared_assets/__init__.py

@@ -26,8 +26,8 @@ from .data_classes import (
     MesoscopePaths,
     ZaberPositions,
     ExperimentState,
+    ExperimentTrial,
     MesoscopeCameras,
-    TrialCueSequence,
     ProcessingTracker,
     MesoscopePositions,
     RunTrainingDescriptor,
@@ -78,7 +78,7 @@ __all__ = [
     "MesoscopeAdditionalFirmware",
     "get_system_configuration_data",
     "set_system_configuration_file",
-    "TrialCueSequence",
+    "ExperimentTrial",
     # Tools package
     "resolve_p53_marker",
     "transfer_directory",

{sl_shared_assets-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/sl_shared_assets/__init__.pyi

@@ -22,8 +22,8 @@ from .data_classes import (
     MesoscopePaths as MesoscopePaths,
     ZaberPositions as ZaberPositions,
     ExperimentState as ExperimentState,
+    ExperimentTrial as ExperimentTrial,
     MesoscopeCameras as MesoscopeCameras,
-    TrialCueSequence as TrialCueSequence,
     ProcessingTracker as ProcessingTracker,
     MesoscopePositions as MesoscopePositions,
     RunTrainingDescriptor as RunTrainingDescriptor,
@@ -68,7 +68,7 @@ __all__ = [
     "MesoscopeAdditionalFirmware",
     "get_system_configuration_data",
     "set_system_configuration_file",
-    "TrialCueSequence",
+    "ExperimentTrial",
     "resolve_p53_marker",
     "transfer_directory",
     "calculate_directory_checksum",

{sl_shared_assets-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/sl_shared_assets/data_classes/__init__.py

@@ -23,8 +23,8 @@ from .surgery_data import (
 from .configuration_data import (
     MesoscopePaths,
     ExperimentState,
+    ExperimentTrial,
     MesoscopeCameras,
-    TrialCueSequence,
     MesoscopeMicroControllers,
     MesoscopeAdditionalFirmware,
     MesoscopeSystemConfiguration,
@@ -59,5 +59,5 @@ __all__ = [
     "MesoscopeMicroControllers",
     "MesoscopeAdditionalFirmware",
     "ProcessingTracker",
-    "TrialCueSequence",
+    "ExperimentTrial",
 ]

{sl_shared_assets-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/sl_shared_assets/data_classes/__init__.pyi

@@ -23,8 +23,8 @@ from .surgery_data import (
 from .configuration_data import (
     MesoscopePaths as MesoscopePaths,
     ExperimentState as ExperimentState,
+    ExperimentTrial as ExperimentTrial,
     MesoscopeCameras as MesoscopeCameras,
-    TrialCueSequence as TrialCueSequence,
     MesoscopeMicroControllers as MesoscopeMicroControllers,
     MesoscopeAdditionalFirmware as MesoscopeAdditionalFirmware,
     MesoscopeSystemConfiguration as MesoscopeSystemConfiguration,
@@ -59,5 +59,5 @@ __all__ = [
     "MesoscopeMicroControllers",
     "MesoscopeAdditionalFirmware",
     "ProcessingTracker",
-    "TrialCueSequence",
+    "ExperimentTrial",
 ]

{sl_shared_assets-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/sl_shared_assets/data_classes/configuration_data.py

@@ -56,14 +56,14 @@ class ExperimentState:
 
 
 @dataclass()
-class TrialCueSequence:
-    """Encapsulates information about the Virtual Reality (VR) wall cue sequence experienced by the animal as part of
-    the given trial.
-
-    All Virtual Reality environments can be broadly conceptualized as repeating motifs (sequences) of wall cues. Since
-    some experimental tasks can use multiple cue sequences as part of the same experiment session, multiple instances of
-    this class can be used to specify supported trial structures. The information stored in this class instance is used
-    during behavior data parsing to assign trial information to data collected from various sources.
+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.
     """
 
     cue_sequence: list[int]
@@ -72,6 +72,15 @@ class TrialCueSequence:
     """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
+    """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
@@ -98,6 +107,14 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     """A dictionary that maps each integer-code associated with a wall cue used in the Virtual Reality experiment 
     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 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."""
     experiment_states: dict[str, ExperimentState] = field(
         default_factory=lambda: {
             "baseline": ExperimentState(
@@ -128,15 +145,22 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     )
     """A dictionary that uses human-readable state-names as keys and ExperimentState instances as values. Each 
     ExperimentState instance represents a phase of the experiment."""
-    trial_structures: dict[str, TrialCueSequence] = field(
+    trial_structures: dict[str, ExperimentTrial] = field(
         default_factory=lambda: {
-            "circular 4 cue": TrialCueSequence(
-                cue_sequence=[0, 1, 0, 2, 0, 3, 0, 4], trial_length_unity_unit=24.0, trial_length_cm=240.0
+            "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,
+                reward_zone_end_cm=222.0,
+                guidance_trigger_location_cm=208.0,
             )
         }
     )
-    """A dictionary that maps human-readable trial structure names as keys and TrialCueSequence instances as values. 
-    Each TrialCueSequence instance represents a specific VR wall cue sequence used by a given trial structure."""
+    """A dictionary that maps 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."""
 
 
 @dataclass()
@@ -231,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)."""
@@ -253,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 
@@ -278,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-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/sl_shared_assets/data_classes/configuration_data.pyi

@@ -28,19 +28,23 @@ class ExperimentState:
     recovery_guided_trials: int
 
 @dataclass()
-class TrialCueSequence:
-    """Encapsulates information about the Virtual Reality (VR) wall cue sequence experienced by the animal as part of
-    the given trial.
-
-    All Virtual Reality environments can be broadly conceptualized as repeating motifs (sequences) of wall cues. Since
-    some experimental tasks can use multiple cue sequences as part of the same experiment session, multiple instances of
-    this class can be used to specify supported trial structures. The information stored in this class instance is used
-    during behavior data parsing to assign trial information to data collected from various sources.
+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.
     """
 
     cue_sequence: list[int]
     trial_length_unity_unit: float
     trial_length_cm: 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):
@@ -62,8 +66,9 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     """
 
     cue_map: dict[int, float] = field(default_factory=Incomplete)
+    cue_offset_cm: float = ...
     experiment_states: dict[str, ExperimentState] = field(default_factory=Incomplete)
-    trial_structures: dict[str, TrialCueSequence] = field(default_factory=Incomplete)
+    trial_structures: dict[str, ExperimentTrial] = field(default_factory=Incomplete)
 
 @dataclass()
 class MesoscopePaths:
@@ -105,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-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/sl_shared_assets/data_classes/session_data.py

@@ -103,6 +103,13 @@ class RawData:
     the long-term storage destinations (NAS and Server) and the integrity of the moved data is verified on at least one 
     destination. During 'purge' sl-experiment runtimes, the library discovers and removes all session data marked with 
     'ubiquitin.bin' files from the machine that runs the code."""
+    nk_path: Path = Path()
+    """Stores the path to the nk.bin file. This file is used during new data acquisition by the sl-experiment library
+    to mark sessions going through initial runtime initialization. Since runtime initialization is a complex process 
+    that may fail at many different time-points, it is important to know whether the runtime initialized before 
+    encountering an error. The presence of an nk.bin marker notifies post-runtime processes that the runtime failed to 
+    initialize, marking that session's data for immediate deletion from all sources, as it does not contain any valid 
+    information."""
     integrity_verification_tracker_path: Path = Path()
     """Stores the path to the integrity_verification.yaml tracker file. This file stores the current state of the data 
     integrity verification pipeline. It prevents more than one instance of the pipeline from working with the data 
@@ -137,6 +144,7 @@ class RawData:
         self.system_configuration_path = self.raw_data_path.joinpath("system_configuration.yaml")
         self.telomere_path = self.raw_data_path.joinpath("telomere.bin")
         self.ubiquitin_path = self.raw_data_path.joinpath("ubiquitin.bin")
+        self.nk_path = self.raw_data_path.joinpath("nk.bin")
         self.integrity_verification_tracker_path = self.raw_data_path.joinpath("integrity_verification_tracker.yaml")
 
     def make_directories(self) -> None:
@@ -406,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
 
@@ -485,6 +498,15 @@ class SessionData(YamlConfig):
         # Returns the initialized SessionData instance to caller
         return instance
 
+    def mark_initialization(self) -> None:
+        """Ensures that the 'nk.bin' marker file is removed from the session's raw_dat folder.
+
+        This marker is generated as part of the SessionData initialization (creation) process to mark sessions that did
+        not fully initialize during runtime. Call this method after fully initializing the data acquisition runtime
+        control class to ensure that the session is not marker for automated deletion upon runtime completion.
+        """
+        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-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/sl_shared_assets/data_classes/session_data.pyi

@@ -37,6 +37,7 @@ class RawData:
     checksum_path: Path = ...
     telomere_path: Path = ...
     ubiquitin_path: Path = ...
+    nk_path: Path = ...
     integrity_verification_tracker_path: Path = ...
     def resolve_paths(self, root_directory_path: Path) -> None:
         """Resolves all paths managed by the class instance based on the input root directory path.
@@ -190,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 mark_initialization(self) -> None:
+        """Ensures that the 'nk.bin' marker file is removed from the session's raw_dat folder.
+
+        This marker is generated as part of the SessionData initialization (creation) process to mark sessions that did
+        not fully initialize during runtime. Call this method after fully initializing the data acquisition runtime
+        control class to ensure that the session is not marker for automated deletion upon runtime completion.
         """
     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-3.0.0rc7 → sl_shared_assets-3.0.0rc9}/src/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.mark_initialization()
+
                 # 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.