sl-shared-assets 3.0.0rc6__tar.gz → 3.0.0rc8__tar.gz

{sl_shared_assets-3.0.0rc6 → sl_shared_assets-3.0.0rc8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sl-shared-assets
-Version: 3.0.0rc6
+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.0rc6 → sl_shared_assets-3.0.0rc8}/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.0rc6"
+version = "3.0.0rc8"
 description = "Provides data acquisition and processing assets shared between Sun (NeuroAI) lab libraries."
 readme = "README.md"
 license = { file = "LICENSE" }

{sl_shared_assets-3.0.0rc6 → sl_shared_assets-3.0.0rc8}/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.0rc6 → sl_shared_assets-3.0.0rc8}/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.0rc6 → sl_shared_assets-3.0.0rc8}/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.0rc6 → sl_shared_assets-3.0.0rc8}/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.0rc6 → sl_shared_assets-3.0.0rc8}/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,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-3.0.0rc6 → sl_shared_assets-3.0.0rc8}/src/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-3.0.0rc6 → sl_shared_assets-3.0.0rc8}/src/sl_shared_assets/data_classes/session_data.py

@@ -68,9 +68,6 @@ class RawData:
     surgery_metadata_path: Path = Path()
     """Stores the path to the surgery_metadata.yaml file. This file contains the most actual information about the 
     surgical intervention(s) performed on the animal prior to the session."""
-    project_configuration_path: Path = Path()
-    """Stores the path to the project_configuration.yaml file. This file contains the snapshot of the configuration 
-    parameters for the session's project."""
     session_data_path: Path = Path()
     """Stores the path to the session_data.yaml file. This path is used by the SessionData instance to save itself to 
     disk as a .yaml file. The file contains the paths to all raw and processed data directories used during data 
@@ -106,13 +103,17 @@ 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 
     at a given time and communicates the outcome (success or failure) of the most recent pipeline runtime."""
-    version_data_path: Path = Path()
-    """Stores the path to the version_data.yaml file. This file contains the snapshot of Python and sl-experiment 
-    library versions that were used when the data was acquired."""
 
     def resolve_paths(self, root_directory_path: Path) -> None:
         """Resolves all paths managed by the class instance based on the input root directory path.
@@ -135,7 +136,6 @@ class RawData:
         self.session_descriptor_path = self.raw_data_path.joinpath("session_descriptor.yaml")
         self.hardware_state_path = self.raw_data_path.joinpath("hardware_state.yaml")
         self.surgery_metadata_path = self.raw_data_path.joinpath("surgery_metadata.yaml")
-        self.project_configuration_path = self.raw_data_path.joinpath("project_configuration.yaml")
         self.session_data_path = self.raw_data_path.joinpath("session_data.yaml")
         self.experiment_configuration_path = self.raw_data_path.joinpath("experiment_configuration.yaml")
         self.mesoscope_positions_path = self.raw_data_path.joinpath("mesoscope_positions.yaml")
@@ -144,8 +144,8 @@ 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")
-        self.version_data_path = self.raw_data_path.joinpath("version_data.yaml")
 
     def make_directories(self) -> None:
         """Ensures that all major subdirectories and the root directory exist, creating any missing directories."""
@@ -302,9 +302,9 @@ class SessionData(YamlConfig):
 
             This method automatically dumps the data of the created SessionData instance into the session_data.yaml file
             inside the root raw_data directory of the created hierarchy. It also finds and dumps other configuration
-            files, such as project_configuration.yaml, experiment_configuration.yaml, and system_configuration.yaml into
-            the same raw_data directory. This ensures that if the session's runtime is interrupted unexpectedly, the
-            acquired data can still be processed.
+            files, such as experiment_configuration.yaml and system_configuration.yaml into the same raw_data directory.
+            This ensures that if the session's runtime is interrupted unexpectedly, the acquired data can still be
+            processed.
 
         Args:
             project_name: The name of the project for which the data is acquired.
@@ -401,14 +401,8 @@ class SessionData(YamlConfig):
         # preprocessing.
         instance._save()
 
-        # Also saves the ProjectConfiguration, SystemConfiguration, and ExperimentConfiguration instances to the same
-        # folder using the paths resolved for the RawData instance above.
-
-        # Copies the project_configuration.yaml file to session's folder
-        project_configuration_path = acquisition_system.paths.root_directory.joinpath(
-            project_name, "configuration", "project_configuration.yaml"
-        )
-        sh.copy2(project_configuration_path, instance.raw_data.project_configuration_path)
+        # Also saves the SystemConfiguration and ExperimentConfiguration instances to the same folder using the paths
+        # resolved for the RawData instance above.
 
         # Dumps the acquisition system's configuration data to session's folder
         acquisition_system.save(path=instance.raw_data.system_configuration_path)

{sl_shared_assets-3.0.0rc6 → sl_shared_assets-3.0.0rc8}/src/sl_shared_assets/data_classes/session_data.pyi

@@ -29,7 +29,6 @@ class RawData:
     session_descriptor_path: Path = ...
     hardware_state_path: Path = ...
     surgery_metadata_path: Path = ...
-    project_configuration_path: Path = ...
     session_data_path: Path = ...
     experiment_configuration_path: Path = ...
     mesoscope_positions_path: Path = ...
@@ -38,8 +37,8 @@ class RawData:
     checksum_path: Path = ...
     telomere_path: Path = ...
     ubiquitin_path: Path = ...
+    nk_path: Path = ...
     integrity_verification_tracker_path: Path = ...
-    version_data_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.
 
@@ -140,9 +139,9 @@ class SessionData(YamlConfig):
 
             This method automatically dumps the data of the created SessionData instance into the session_data.yaml file
             inside the root raw_data directory of the created hierarchy. It also finds and dumps other configuration
-            files, such as project_configuration.yaml, experiment_configuration.yaml, and system_configuration.yaml into
-            the same raw_data directory. This ensures that if the session's runtime is interrupted unexpectedly, the
-            acquired data can still be processed.
+            files, such as experiment_configuration.yaml and system_configuration.yaml into the same raw_data directory.
+            This ensures that if the session's runtime is interrupted unexpectedly, the acquired data can still be
+            processed.
 
         Args:
             project_name: The name of the project for which the data is acquired.