sl-shared-assets 1.0.0rc19__tar.gz → 1.0.0rc20__tar.gz

{sl_shared_assets-1.0.0rc19 → sl_shared_assets-1.0.0rc20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sl-shared-assets
-Version: 1.0.0rc19
+Version: 1.0.0rc20
 Summary: Stores assets shared between multiple Sun (NeuroAI) lab data pipelines.
 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-1.0.0rc19 → sl_shared_assets-1.0.0rc20}/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 = "1.0.0rc19"
+version = "1.0.0rc20"
 description = "Stores assets shared between multiple Sun (NeuroAI) lab data pipelines."
 readme = "README.md"
 license = { file = "LICENSE" }

sl_shared_assets-1.0.0rc20/src/sl_shared_assets/__init__.pyi

@@ -0,0 +1,71 @@
+from .tools import (
+    transfer_directory as transfer_directory,
+    calculate_directory_checksum as calculate_directory_checksum,
+)
+from .server import (
+    Server as Server,
+    ServerCredentials as ServerCredentials,
+)
+from .suite2p import (
+    MultiDayS2PConfiguration as MultiDayS2PConfiguration,
+    SingleDayS2PConfiguration as SingleDayS2PConfiguration,
+)
+from .data_classes import (
+    RawData as RawData,
+    DrugData as DrugData,
+    ImplantData as ImplantData,
+    SessionData as SessionData,
+    SubjectData as SubjectData,
+    SurgeryData as SurgeryData,
+    InjectionData as InjectionData,
+    MesoscopeData as MesoscopeData,
+    ProcedureData as ProcedureData,
+    ProcessedData as ProcessedData,
+    DeepLabCutData as DeepLabCutData,
+    ZaberPositions as ZaberPositions,
+    ExperimentState as ExperimentState,
+    VRPCDestinations as VRPCDestinations,
+    ConfigurationData as ConfigurationData,
+    MesoscopePositions as MesoscopePositions,
+    VRPCPersistentData as VRPCPersistentData,
+    ProjectConfiguration as ProjectConfiguration,
+    HardwareConfiguration as HardwareConfiguration,
+    RunTrainingDescriptor as RunTrainingDescriptor,
+    LickTrainingDescriptor as LickTrainingDescriptor,
+    ExperimentConfiguration as ExperimentConfiguration,
+    ScanImagePCPersistentData as ScanImagePCPersistentData,
+    MesoscopeExperimentDescriptor as MesoscopeExperimentDescriptor,
+)
+
+__all__ = [
+    "Server",
+    "ServerCredentials",
+    "SingleDayS2PConfiguration",
+    "MultiDayS2PConfiguration",
+    "DrugData",
+    "ImplantData",
+    "SessionData",
+    "RawData",
+    "ProcessedData",
+    "ConfigurationData",
+    "DeepLabCutData",
+    "VRPCPersistentData",
+    "ScanImagePCPersistentData",
+    "MesoscopeData",
+    "VRPCDestinations",
+    "SubjectData",
+    "SurgeryData",
+    "InjectionData",
+    "ProcedureData",
+    "ZaberPositions",
+    "ExperimentState",
+    "MesoscopePositions",
+    "ProjectConfiguration",
+    "HardwareConfiguration",
+    "RunTrainingDescriptor",
+    "LickTrainingDescriptor",
+    "ExperimentConfiguration",
+    "MesoscopeExperimentDescriptor",
+    "transfer_directory",
+    "calculate_directory_checksum",
+]

sl_shared_assets-1.0.0rc20/src/sl_shared_assets/cli.pyi

@@ -0,0 +1,28 @@
+from .tools import ascend_tyche_data as ascend_tyche_data
+from .server import generate_server_credentials as generate_server_credentials
+from .data_classes import replace_root_path as replace_root_path
+
+def replace_local_root_directory(path: str) -> None:
+    """Replaces the root directory used to store all lab projects on the local PC with the specified directory.
+
+    To ensure all projects are saved in the same location, this library resolves and saves the absolute path to the
+    project directory the first time ProjectConfiguration class instance is created on a new PC. All future projects
+    automatically reuse the same 'root' directory path. Since this information is stored in a typically hidden user
+    directory, this CLI can be used to replace the local directory path, if necessary.
+    """
+
+def generate_server_credentials_file(output_directory: str, host: str, username: str, password: str) -> None:
+    """Generates a new server_credentials.yaml file under the specified directory, using input information.
+
+    This CLI is used to set up new PCs to work with the lab BioHPC server. While this is primarily intended for the
+    VRPC, any machined that interacts with BioHPC server can use this CLI to build the access credentials file.
+    """
+
+def ascend_tyche_directory(path: str, output_directory: str, server_directory: str) -> None:
+    """Restructures old Tyche project data to use the modern Sun lab data structure.
+
+    This CLI is used to convert ('ascend') the old Tyche project data to the modern Sun lab structure. After
+    ascension, the data can be processed and analyzed using all modern Sun lab (sl-) tools and libraries. Note, this
+    process expects the input data to be preprocessed using an old Sun lab mesoscope data preprocessing pipeline. It
+    will not work for any other project or data.
+    """

sl_shared_assets-1.0.0rc20/src/sl_shared_assets/data_classes/__init__.pyi

@@ -0,0 +1,61 @@
+from .runtime_data import (
+    ZaberPositions as ZaberPositions,
+    MesoscopePositions as MesoscopePositions,
+    HardwareConfiguration as HardwareConfiguration,
+    RunTrainingDescriptor as RunTrainingDescriptor,
+    LickTrainingDescriptor as LickTrainingDescriptor,
+    MesoscopeExperimentDescriptor as MesoscopeExperimentDescriptor,
+)
+from .session_data import (
+    RawData as RawData,
+    SessionData as SessionData,
+    MesoscopeData as MesoscopeData,
+    ProcessedData as ProcessedData,
+    DeepLabCutData as DeepLabCutData,
+    VRPCDestinations as VRPCDestinations,
+    ConfigurationData as ConfigurationData,
+    VRPCPersistentData as VRPCPersistentData,
+    ProjectConfiguration as ProjectConfiguration,
+    ScanImagePCPersistentData as ScanImagePCPersistentData,
+    replace_root_path as replace_root_path,
+)
+from .surgery_data import (
+    DrugData as DrugData,
+    ImplantData as ImplantData,
+    SubjectData as SubjectData,
+    SurgeryData as SurgeryData,
+    InjectionData as InjectionData,
+    ProcedureData as ProcedureData,
+)
+from .configuration_data import (
+    ExperimentState as ExperimentState,
+    ExperimentConfiguration as ExperimentConfiguration,
+)
+
+__all__ = [
+    "DrugData",
+    "ImplantData",
+    "SessionData",
+    "RawData",
+    "ProcessedData",
+    "ConfigurationData",
+    "DeepLabCutData",
+    "VRPCPersistentData",
+    "ScanImagePCPersistentData",
+    "MesoscopeData",
+    "VRPCDestinations",
+    "SubjectData",
+    "SurgeryData",
+    "InjectionData",
+    "ProcedureData",
+    "ZaberPositions",
+    "ExperimentState",
+    "MesoscopePositions",
+    "ProjectConfiguration",
+    "HardwareConfiguration",
+    "RunTrainingDescriptor",
+    "LickTrainingDescriptor",
+    "ExperimentConfiguration",
+    "MesoscopeExperimentDescriptor",
+    "replace_root_path",
+]

sl_shared_assets-1.0.0rc20/src/sl_shared_assets/data_classes/configuration_data.pyi

@@ -0,0 +1,37 @@
+from pathlib import Path as Path
+from dataclasses import field, dataclass
+
+from _typeshed import Incomplete
+from ataraxis_data_structures import YamlConfig
+
+@dataclass()
+class ExperimentState:
+    """Encapsulates the information used to set and maintain the desired experiment and Mesoscope-VR system state.
+
+    Primarily, experiment runtime logic (task logic) is resolved by the Unity game engine. However, the Mesoscope-VR
+    system configuration may also need to change throughout the experiment to optimize the runtime by disabling or
+    reconfiguring specific hardware modules. For example, some experiment stages may require the running wheel to be
+    locked to prevent the animal from running, and other may require the VR screens to be turned off.
+    """
+
+    experiment_state_code: int
+    vr_state_code: int
+    state_duration_s: float
+
+@dataclass()
+class ExperimentConfiguration(YamlConfig):
+    """Stores the configuration of a single experiment runtime.
+
+    Primarily, this includes the sequence of experiment and Virtual Reality (Mesoscope-VR) states that defines the flow
+    of the experiment runtime. During runtime, the main runtime control function traverses the sequence of states
+    stored in this class instance start-to-end in the exact order specified by the user. Together with custom Unity
+    projects that define the task logic (how the system responds to animal interactions with the VR system) this class
+    allows flexibly implementing a wide range of experiments.
+
+    Each project should define one or more experiment configurations and save them as .yaml files inside the project
+    'configuration' folder. The name for each configuration file is defined by the user and is used to identify and load
+    the experiment configuration when 'sl-run-experiment' CLI command exposed by the sl-experiment library is executed.
+    """
+
+    cue_map: dict[int, float] = field(default_factory=Incomplete)
+    experiment_states: dict[str, ExperimentState] = field(default_factory=Incomplete)

{sl_shared_assets-1.0.0rc19 → sl_shared_assets-1.0.0rc20}/src/sl_shared_assets/data_classes/runtime_data.py

@@ -90,6 +90,10 @@ class LickTrainingDescriptor(YamlConfig):
     """Stores the maximum volume of water the system is allowed to dispense during training."""
     maximum_training_time_m: int
     """Stores the maximum time, in minutes, the system is allowed to run the training for."""
+    maximum_unconsumed_rewards: int = 3
+    """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."""
     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."""
@@ -137,6 +141,14 @@ class RunTrainingDescriptor(YamlConfig):
     """Stores the maximum volume of water the system is allowed to dispense during training."""
     maximum_training_time_m: int
     """Stores the maximum time, in minutes, the system is allowed to run the training for."""
+    maximum_unconsumed_rewards: int = 3
+    """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."""
+    maximum_idle_time_s: float = 0.0
+    """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."""
     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-1.0.0rc20/src/sl_shared_assets/data_classes/runtime_data.pyi

@@ -0,0 +1,148 @@
+from dataclasses import dataclass
+
+from ataraxis_data_structures import YamlConfig
+
+@dataclass()
+class HardwareConfiguration(YamlConfig):
+    """This class is used to save the runtime hardware configuration parameters as a .yaml file.
+
+    This information is used to read and decode the data saved to the .npz log files during runtime as part of data
+    processing.
+
+    Notes:
+        All fields in this dataclass initialize to None. During log processing, any log associated with a hardware
+        module that provides the data stored in a field will be processed, unless that field is None. Therefore, setting
+        any field in this dataclass to None also functions as a flag for whether to parse the log associated with the
+        module that provides this field's information.
+
+        This class is automatically configured by MesoscopeExperiment and BehaviorTraining classes from sl-experiment
+        library to facilitate log parsing.
+    """
+
+    cue_map: dict[int, float] | None = ...
+    cm_per_pulse: float | None = ...
+    maximum_break_strength: float | None = ...
+    minimum_break_strength: float | None = ...
+    lick_threshold: int | None = ...
+    valve_scale_coefficient: float | None = ...
+    valve_nonlinearity_exponent: float | None = ...
+    torque_per_adc_unit: float | None = ...
+    screens_initially_on: bool | None = ...
+    recorded_mesoscope_ttl: bool | None = ...
+
+@dataclass()
+class LickTrainingDescriptor(YamlConfig):
+    """This class is used to save the description information specific to lick training sessions as a .yaml file.
+
+    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
+    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
+    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
+
+    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
+    trained animal.
+    """
+
+    experimenter: str
+    mouse_weight_g: float
+    dispensed_water_volume_ml: float
+    minimum_reward_delay: int
+    maximum_reward_delay_s: int
+    maximum_water_volume_ml: float
+    maximum_training_time_m: int
+    maximum_unconsumed_rewards: int = ...
+    experimenter_notes: str = ...
+    experimenter_given_water_volume_ml: float = ...
+
+@dataclass()
+class RunTrainingDescriptor(YamlConfig):
+    """This class is used to save the description information specific to run training sessions as a .yaml file.
+
+    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
+    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
+    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
+
+    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
+    trained animal.
+    """
+
+    experimenter: str
+    mouse_weight_g: float
+    dispensed_water_volume_ml: float
+    final_run_speed_threshold_cm_s: float
+    final_run_duration_threshold_s: float
+    initial_run_speed_threshold_cm_s: float
+    initial_run_duration_threshold_s: float
+    increase_threshold_ml: float
+    run_speed_increase_step_cm_s: float
+    run_duration_increase_step_s: float
+    maximum_water_volume_ml: float
+    maximum_training_time_m: int
+    maximum_unconsumed_rewards: int = ...
+    maximum_idle_time_s: float = ...
+    experimenter_notes: str = ...
+    experimenter_given_water_volume_ml: float = ...
+
+@dataclass()
+class MesoscopeExperimentDescriptor(YamlConfig):
+    """This class is used to save the description information specific to experiment sessions as a .yaml file.
+
+    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
+    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
+    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
+
+    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
+    animal participating in the experiment runtime.
+    """
+
+    experimenter: str
+    mouse_weight_g: float
+    dispensed_water_volume_ml: float
+    experimenter_notes: str = ...
+    experimenter_given_water_volume_ml: float = ...
+
+@dataclass()
+class ZaberPositions(YamlConfig):
+    """This class is used to save Zaber motor positions as a .yaml file to reuse them between sessions.
+
+    The class is specifically designed to store, save, and load the positions of the LickPort and HeadBar motors
+    (axes). It is used to both store Zaber motor positions for each session for future analysis and to restore the same
+    Zaber motor positions across consecutive runtimes for the same project and animal combination.
+
+    Notes:
+        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.
+
+        Exercise caution when working with Zaber motors. The motors are powerful enough to damage the surrounding
+        equipment and manipulated objects. Do not modify the data stored inside the .yaml file unless you know what you
+        are doing.
+    """
+
+    headbar_z: int = ...
+    headbar_pitch: int = ...
+    headbar_roll: int = ...
+    lickport_z: int = ...
+    lickport_x: int = ...
+    lickport_y: int = ...
+
+@dataclass()
+class MesoscopePositions(YamlConfig):
+    """This class is used to save the real and virtual Mesoscope objective positions as a .yaml file to reuse it
+    between experiment sessions.
+
+    Primarily, the class is used to help the experimenter to position the Mesoscope at the same position 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.
+
+    Notes:
+        Since the API to read and write these positions automatically is currently not available, this class relies on
+        the experimenter manually entering all positions and setting the mesoscope to these positions when necessary.
+    """
+
+    mesoscope_x_position: float = ...
+    mesoscope_y_position: float = ...
+    mesoscope_roll_position: float = ...
+    mesoscope_z_position: float = ...
+    mesoscope_fast_z_position: float = ...
+    mesoscope_tip_position: float = ...
+    mesoscope_tilt_position: float = ...

{sl_shared_assets-1.0.0rc19 → sl_shared_assets-1.0.0rc20}/src/sl_shared_assets/data_classes/session_data.py

@@ -11,11 +11,11 @@ import shutil as sh
 from pathlib import Path
 from dataclasses import field, dataclass
 
+import dacite
 import appdirs
 from ataraxis_base_utilities import LogLevel, console, ensure_directory_exists
 from ataraxis_data_structures import YamlConfig
 from ataraxis_time.time_helpers import get_timestamp
-import dacite
 
 from .configuration_data import ExperimentConfiguration
 
@@ -1313,7 +1313,7 @@ class SessionData(YamlConfig):
         """
 
         # Reads the file content without using the YAML parsing methods.
-        with open(path, 'r') as f:
+        with open(path, "r") as f:
             content = f.read()
 
         # Extracts the necessary fields using regex
@@ -1321,11 +1321,11 @@ class SessionData(YamlConfig):
 
         # Defines the field patterns for each field to extract
         patterns = {
-            "project_name": r'project_name:\s*(.+?)(?=\n\w|\n$)',
-            "animal_id": r'animal_id:\s*(.+?)(?=\n\w|\n$)',
-            "session_name": r'session_name:\s*(.+?)(?=\n\w|\n$)',
-            "session_type": r'session_type:\s*(.+?)(?=\n\w|\n$)',
-            "experiment_name": r'experiment_name:\s*(.+?)(?=\n\w|\n$)'
+            "project_name": r"project_name:\s*(.+?)(?=\n\w|\n$)",
+            "animal_id": r"animal_id:\s*(.+?)(?=\n\w|\n$)",
+            "session_name": r"session_name:\s*(.+?)(?=\n\w|\n$)",
+            "session_type": r"session_type:\s*(.+?)(?=\n\w|\n$)",
+            "experiment_name": r"experiment_name:\s*(.+?)(?=\n\w|\n$)",
         }
 
         # Extracts each field
@@ -1343,5 +1343,5 @@ class SessionData(YamlConfig):
                     fields_to_keep[key] = ""  # Default for other fields
 
         # Returns the data to caller
-        return dacite.from_dict(data_class=cls, data=fields_to_keep)  # type: ignore
-
+        # noinspection PyTypeChecker
+        return dacite.from_dict(data_class=cls, data=fields_to_keep)