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

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/__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/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/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/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,8 @@ 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 = 5.0
+    """The volume of water, in microliters, to be dispensed when the animal successfully completes the trial task."""
 
 
 # noinspection PyArgumentList
@@ -98,6 +100,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 starting position 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 +138,19 @@ 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=[0, 1, 0, 2, 0, 3, 0, 4],
+                trial_length_unity_unit=24.0,
+                trial_length_cm=240.0,
+                trial_reward_size_ul=5.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()

sl_shared_assets/data_classes/configuration_data.pyi

@@ -28,19 +28,20 @@ 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 = ...
 
 @dataclass()
 class MesoscopeExperimentConfiguration(YamlConfig):
@@ -62,8 +63,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:

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:

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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sl-shared-assets
-Version: 3.0.0rc7
+Version: 3.0.0rc8
 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.dist-info → sl_shared_assets-3.0.0rc8.dist-info}/RECORD

@@ -1,16 +1,16 @@
-sl_shared_assets/__init__.py,sha256=tNLUHtKWe-yn7LfvDv4kOqr2NLRf5BFD1MCyuVwdU6M,2199
-sl_shared_assets/__init__.pyi,sha256=WhQ5s5_vvTbMEtZ9F_8jYC0dJar2XAUzYnDqKsm6zNk,2402
+sl_shared_assets/__init__.py,sha256=RzYuJclcE8EpbAC1wRb6eFIycPpsEmNvGkndrIxtmis,2197
+sl_shared_assets/__init__.pyi,sha256=58fHlHTVMfrX4wDnYC2U_mkNMefw7odPn29nN1UnxFU,2399
 sl_shared_assets/cli.py,sha256=R_h_Dlla48mG1LpFDDE9flZ_NyDC9UguRUAYZL6gA9s,18383
 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=B-kR3bGEUwuAk1q3DmwiYi1w-OeiBl9uI0K3PW4Z3RQ,1854
-sl_shared_assets/data_classes/__init__.pyi,sha256=YKK9Dx5RtylJLfVjgw5grLLH0FNr5FcnKrEZIMfTk0Q,2025
-sl_shared_assets/data_classes/configuration_data.py,sha256=CHoKs4wgg_qMNbvZHxfJJHLkeNbnUCevNG1PfiKu9kk,33786
-sl_shared_assets/data_classes/configuration_data.pyi,sha256=SpVnTcAVmR7uDSECbmR4wDmNdTEtavRn8gjI9Lhi5dI,10721
+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=_PFRXxLKednN-UmFjc8N-TISDxZZ2WIxbpOF2FT1RHU,44003
-sl_shared_assets/data_classes/session_data.pyi,sha256=LzjYYYbETtPoN7MwKzs5PfRLLkKJCLm7fHKyox7LNco,13630
+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/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
@@ -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.0rc7.dist-info/METADATA,sha256=kIqXKzZ1oXiPrqaJdfC8qauJlGo7w8akXCeENhur5aE,49309
-sl_shared_assets-3.0.0rc7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sl_shared_assets-3.0.0rc7.dist-info/entry_points.txt,sha256=UmO1rl7ly9N7HWPwWyP9E0b5KBUStpBo4TRoqNtizDY,430
-sl_shared_assets-3.0.0rc7.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-sl_shared_assets-3.0.0rc7.dist-info/RECORD,,
+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,,