sl-shared-assets 3.0.0rc1__tar.gz → 3.0.0rc3__tar.gz

{sl_shared_assets-3.0.0rc1 → sl_shared_assets-3.0.0rc3}/PKG-INFO

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

{sl_shared_assets-3.0.0rc1 → sl_shared_assets-3.0.0rc3}/src/sl_shared_assets/data_classes/configuration_data.py

@@ -39,6 +39,20 @@ class ExperimentState:
     system currently support two system state codes: REST (1) and RUN (2)."""
     state_duration_s: float
     """The time, in seconds, to maintain the current combination of the experiment and system states."""
+    initial_guided_trials: int = 3
+    """Specifies the number of trials (laps) at the onset of the experiment state, for which lick guidance will be 
+    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 = 6
+    """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."""
+    recovery_guided_trials: int = 3
+    """Specifies the number of trials (laps) for which the system will re-enable lick guidance, when the animal 
+    repeatedly fails 'failed_trial_threshold' number of trials. This field works similar to the 'initial_guided_trials' 
+    field, but is triggered by repeated performance failures, rather than experiment state onset. After the animal 
+    runs this many guided trials, the system will automatically disable guidance for the following trials."""
 
 
 @dataclass()
@@ -54,6 +68,10 @@ class TrialCueSequence:
 
     cue_sequence: tuple[int, ...]
     """Specifies the sequence of wall cues experienced by the animal while running this trial."""
+    trial_length_unity_unit: float = 24.0
+    """The length of the trial cue sequence, in Unity units."""
+    trial_length_cm: float = 240.0
+    """The length of the trial cue sequence in centimeters."""
 
 
 # noinspection PyArgumentList
@@ -90,7 +108,7 @@ 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(
-        default_factory=lambda: {"circular_4cue": TrialCueSequence(cue_sequence=(0, 1, 0, 2, 0, 3, 0, 4))}
+        default_factory=lambda: {"circular 4 cue": TrialCueSequence(cue_sequence=(0, 1, 0, 2, 0, 3, 0, 4))}
     )
     """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."""

{sl_shared_assets-3.0.0rc1 → sl_shared_assets-3.0.0rc3}/src/sl_shared_assets/data_classes/configuration_data.pyi

@@ -23,6 +23,9 @@ class ExperimentState:
     experiment_state_code: int
     system_state_code: int
     state_duration_s: float
+    initial_guided_trials: int = ...
+    failed_trial_threshold: int = ...
+    recovery_guided_trials: int = ...
 
 @dataclass()
 class TrialCueSequence:
@@ -36,6 +39,8 @@ class TrialCueSequence:
     """
 
     cue_sequence: tuple[int, ...]
+    trial_length_unity_unit: float = ...
+    trial_length_cm: float = ...
 
 @dataclass()
 class MesoscopeExperimentConfiguration(YamlConfig):

{sl_shared_assets-3.0.0rc1 → sl_shared_assets-3.0.0rc3}/src/sl_shared_assets/data_classes/runtime_data.py

@@ -4,7 +4,7 @@ restore the data acquisition and runtime management system to the same state acr
 the same animal.
 """
 
-from dataclasses import dataclass
+from dataclasses import field, dataclass
 
 from ataraxis_data_structures import YamlConfig
 
@@ -88,7 +88,7 @@ class LickTrainingDescriptor(YamlConfig):
     """The weight of the animal, in grams, at the beginning of the session."""
     dispensed_water_volume_ml: float
     """Stores the total water volume, in milliliters, dispensed during runtime."""
-    minimum_reward_delay: int
+    minimum_reward_delay_s: int
     """Stores the minimum delay, in seconds, that can separate the delivery of two consecutive water rewards."""
     maximum_reward_delay_s: int
     """Stores the maximum delay, in seconds, that can separate the delivery of two consecutive water rewards."""
@@ -100,6 +100,11 @@ class LickTrainingDescriptor(YamlConfig):
     """Stores the maximum number of consecutive rewards that can be delivered without the animal consuming them. If 
     the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal 
     consumes the rewards."""
+    system_state_codes: dict[str, int] = field(
+        default_factory=lambda: {"idle": 0, "rest": 1, "run": 2, "lick training": 3, "run training": 4}
+    )
+    """Maps integer state-codes used by the acquisition system to communicate its states to human-readable state 
+    names."""
     experimenter_notes: str = "Replace this with your notes."
     """This field is not set during runtime. It is expected that each experimenter replaces this field with their 
     notes made during runtime."""
@@ -150,6 +155,11 @@ class RunTrainingDescriptor(YamlConfig):
     """Stores the maximum time, in seconds, the animal can dip below the running speed threshold to still receive the 
     reward. This allows animals that 'run' by taking a series of large steps, briefly dipping below speed threshold at 
     the end of each step, to still get water rewards."""
+    system_state_codes: dict[str, int] = field(
+        default_factory=lambda: {"idle": 0, "rest": 1, "run": 2, "lick training": 3, "run training": 4}
+    )
+    """Maps integer state-codes used by the acquisition system to communicate its states to human-readable state 
+    names."""
     experimenter_notes: str = "Replace this with your notes."
     """This field is not set during runtime. It is expected that each experimenter will replace this field with their 
     notes made during runtime."""
@@ -175,6 +185,11 @@ class MesoscopeExperimentDescriptor(YamlConfig):
     """Stores the maximum number of consecutive rewards that can be delivered without the animal consuming them. If 
     the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal 
     consumes the rewards."""
+    system_state_codes: dict[str, int] = field(
+        default_factory=lambda: {"idle": 0, "rest": 1, "run": 2, "lick training": 3, "run training": 4}
+    )
+    """Maps integer state-codes used by the acquisition system to communicate its states to human-readable state 
+    names."""
     experimenter_notes: str = "Replace this with your notes."
     """This field is not set during runtime. It is expected that each experimenter will replace this field with their 
     notes made during runtime."""

{sl_shared_assets-3.0.0rc1 → sl_shared_assets-3.0.0rc3}/src/sl_shared_assets/data_classes/runtime_data.pyi

@@ -1,5 +1,6 @@
-from dataclasses import dataclass
+from dataclasses import field, dataclass
 
+from _typeshed import Incomplete
 from ataraxis_data_structures import YamlConfig
 
 @dataclass()
@@ -50,11 +51,12 @@ class LickTrainingDescriptor(YamlConfig):
     experimenter: str
     mouse_weight_g: float
     dispensed_water_volume_ml: float
-    minimum_reward_delay: int
+    minimum_reward_delay_s: int
     maximum_reward_delay_s: int
     maximum_water_volume_ml: float
     maximum_training_time_m: int
     maximum_unconsumed_rewards: int = ...
+    system_state_codes: dict[str, int] = field(default_factory=Incomplete)
     experimenter_notes: str = ...
     experimenter_given_water_volume_ml: float = ...
     incomplete: bool = ...
@@ -77,6 +79,7 @@ class RunTrainingDescriptor(YamlConfig):
     maximum_training_time_m: int
     maximum_unconsumed_rewards: int = ...
     maximum_idle_time_s: float = ...
+    system_state_codes: dict[str, int] = field(default_factory=Incomplete)
     experimenter_notes: str = ...
     experimenter_given_water_volume_ml: float = ...
     incomplete: bool = ...
@@ -89,6 +92,7 @@ class MesoscopeExperimentDescriptor(YamlConfig):
     mouse_weight_g: float
     dispensed_water_volume_ml: float
     maximum_unconsumed_rewards: int = ...
+    system_state_codes: dict[str, int] = field(default_factory=Incomplete)
     experimenter_notes: str = ...
     experimenter_given_water_volume_ml: float = ...
     incomplete: bool = ...

{sl_shared_assets-3.0.0rc1 → sl_shared_assets-3.0.0rc3}/src/sl_shared_assets/server/server.py

@@ -4,6 +4,7 @@ the running job status. All lab processing and analysis pipelines use this inter
 resources.
 """
 
+import stat
 from random import randint
 from pathlib import Path
 import tempfile
@@ -486,6 +487,71 @@ class Server:
         finally:
             sftp.close()
 
+    def pull_directory(self, local_directory_path: Path, remote_directory_path: Path) -> None:
+        """Recursively downloads the entire target directory from the remote server to the local machine.
+
+        Args:
+            local_directory_path: The path to the local directory where the remote directory will be copied.
+            remote_directory_path: The path to the directory on the remote server to be downloaded.
+        """
+        sftp = self._client.open_sftp()
+
+        try:
+            # Creates the local directory if it doesn't exist
+            local_directory_path.mkdir(parents=True, exist_ok=True)
+
+            # Gets the list of items in the remote directory
+            remote_items = sftp.listdir_attr(str(remote_directory_path))
+
+            for item in remote_items:
+                remote_item_path = remote_directory_path.joinpath(item.filename)
+                local_item_path = local_directory_path.joinpath(item.filename)
+
+                # Checks if item is a directory
+                if stat.S_ISDIR(item.st_mode):  # type: ignore
+                    # Recursively pulls the subdirectory
+                    self.pull_directory(local_item_path, remote_item_path)
+                else:
+                    # Pulls the individual file using existing method
+                    sftp.get(localpath=str(local_item_path), remotepath=str(remote_item_path))
+
+        finally:
+            sftp.close()
+
+    def push_directory(self, local_directory_path: Path, remote_directory_path: Path) -> None:
+        """Recursively uploads the entire target directory from the local machine to the remote server.
+
+        Args:
+            local_directory_path: The path to the local directory to be uploaded.
+            remote_directory_path: The path on the remote server where the directory will be copied.
+        """
+        if not local_directory_path.exists() or not local_directory_path.is_dir():
+            message = (
+                f"Unable to upload the target local directory {local_directory_path} to the server, as it does not "
+                f"exist."
+            )
+            console.error(message=message, error=FileNotFoundError)
+
+        sftp = self._client.open_sftp()
+
+        try:
+            # Creates the remote directory using existing method
+            self.create_directory(remote_directory_path, parents=True)
+
+            # Iterates through all items in the local directory
+            for local_item_path in local_directory_path.iterdir():
+                remote_item_path = remote_directory_path.joinpath(local_item_path.name)
+
+                if local_item_path.is_dir():
+                    # Recursively pushes subdirectory
+                    self.push_directory(local_item_path, remote_item_path)
+                else:
+                    # Pushes the individual file using existing method
+                    sftp.put(localpath=str(local_item_path), remotepath=str(remote_item_path))
+
+        finally:
+            sftp.close()
+
     def remove(self, remote_path: Path, is_dir: bool) -> None:
         """Removes the specified file or directory from the remote server.
 

{sl_shared_assets-3.0.0rc1 → sl_shared_assets-3.0.0rc3}/src/sl_shared_assets/server/server.pyi

@@ -216,6 +216,20 @@ class Server:
             local_file_path: The path to the file that needs to be copied to the remote server.
             remote_file_path: The path to the file on the remote server (where to copy the file).
         """
+    def pull_directory(self, local_directory_path: Path, remote_directory_path: Path) -> None:
+        """Recursively downloads the entire target directory from the remote server to the local machine.
+
+        Args:
+            local_directory_path: The path to the local directory where the remote directory will be copied.
+            remote_directory_path: The path to the directory on the remote server to be downloaded.
+        """
+    def push_directory(self, local_directory_path: Path, remote_directory_path: Path) -> None:
+        """Recursively uploads the entire target directory from the local machine to the remote server.
+
+        Args:
+            local_directory_path: The path to the local directory to be uploaded.
+            remote_directory_path: The path on the remote server where the directory will be copied.
+        """
     def remove(self, remote_path: Path, is_dir: bool) -> None:
         """Removes the specified file or directory from the remote server.