sl-shared-assets 1.0.0rc13__py3-none-any.whl → 1.0.0rc15__py3-none-any.whl

sl_shared_assets/__init__.py

@@ -5,42 +5,61 @@ API documentation: https://sl-shared-assets-api-docs.netlify.app/
 Authors: Ivan Kondratyev (Inkaros), Kushaan Gupta, Yuantao Deng
 """
 
+from ataraxis_base_utilities import console
+
+from .tools import transfer_directory, calculate_directory_checksum
 from .server import Server, ServerCredentials
-from .suite2p import (
-    Suite2PConfiguration,
-)
+from .suite2p import MultiDayS2PConfiguration, SingleDayS2PConfiguration
 from .data_classes import (
+    RawData,
     DrugData,
     ImplantData,
     SessionData,
     SubjectData,
     SurgeryData,
     InjectionData,
+    MesoscopeData,
     ProcedureData,
+    ProcessedData,
+    DeepLabCutData,
     ZaberPositions,
     ExperimentState,
-    ProcessingTracker,
+    VRPCDestinations,
+    ConfigurationData,
     MesoscopePositions,
+    VRPCPersistentData,
     ProjectConfiguration,
     HardwareConfiguration,
     RunTrainingDescriptor,
     LickTrainingDescriptor,
     ExperimentConfiguration,
+    ScanImagePCPersistentData,
     MesoscopeExperimentDescriptor,
 )
-from .transfer_tools import transfer_directory
-from .packaging_tools import calculate_directory_checksum
+
+# Ensures console is enabled when this library is imported
+if not console.enabled:
+    console.enable()
 
 __all__ = [
     # Server module
     "Server",
     "ServerCredentials",
-    # Suite2p module
-    "Suite2PConfiguration",
+    # Suite2p package
+    "SingleDayS2PConfiguration",
+    "MultiDayS2PConfiguration",
     # Data classes module
     "DrugData",
     "ImplantData",
     "SessionData",
+    "RawData",
+    "ProcessedData",
+    "ConfigurationData",
+    "DeepLabCutData",
+    "VRPCPersistentData",
+    "ScanImagePCPersistentData",
+    "MesoscopeData",
+    "VRPCDestinations",
     "SubjectData",
     "SurgeryData",
     "InjectionData",
@@ -54,7 +73,6 @@ __all__ = [
     "LickTrainingDescriptor",
     "ExperimentConfiguration",
     "MesoscopeExperimentDescriptor",
-    "ProcessingTracker"
     # Transfer tools module
     "transfer_directory",
     # Packaging tools module

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/cli.py

@@ -4,9 +4,9 @@ from pathlib import Path
 
 import click
 
+from .tools import ascend_tyche_data
 from .server import generate_server_credentials
 from .data_classes import replace_root_path
-from .ascension_tools import ascend_tyche_data
 
 
 @click.command()
@@ -22,9 +22,9 @@ 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 when it is used for the first time. All future projects reuse the same 'root' 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.
+    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.
     """
     replace_root_path(path=Path(path))
 
@@ -35,8 +35,7 @@ def replace_local_root_directory(path: str) -> None:
     "--output_directory",
     type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
     required=True,
-    prompt="Enter the path to the directory where to create the credentials file: ",
-    help="The path to the directory where to create the credentials file.",
+    help="The absolute path to the directory where to create the credentials file.",
 )
 @click.option(
     "-h",
@@ -64,7 +63,8 @@ def replace_local_root_directory(path: str) -> None:
 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 during the initial PC setup (typically, VRPC) to allow it to access the lab BioHPC server.
+    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.
     """
     generate_server_credentials(
         output_directory=Path(output_directory), username=username, password=password, host=host
@@ -77,7 +77,6 @@ def generate_server_credentials_file(output_directory: str, host: str, username:
     "--path",
     type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
     required=True,
-    prompt="Enter the absolute path to the directory that stores original Tyche animal folders: ",
     help="The absolute path to the directory that stores original Tyche animal folders.",
 )
 @click.option(
@@ -85,7 +84,6 @@ def generate_server_credentials_file(output_directory: str, host: str, username:
     "--output_directory",
     type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
     required=True,
-    prompt="Enter the absolute path to the local directory where to create the ascended Tyche project hierarchy: ",
     help="The absolute path to the local directory where to create the ascended Tyche project hierarchy.",
 )
 @click.option(
@@ -93,17 +91,18 @@ def generate_server_credentials_file(output_directory: str, host: str, username:
     "--server_directory",
     type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
     required=True,
-    prompt=(
-        "Enter the path to the SMB-mounted BioHPC server directory where to create the ascended Tyche project "
-        "hierarchy: "
+    help=(
+        "The path to the SMB-mounted BioHPC server directory where to transfer the ascended Tyche project "
+        "hierarchy after it is created."
     ),
-    help="The path to the SMB-mounted BioHPC server directory where to create the ascended Tyche project hierarchy.",
 )
 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.
+    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.
     """
     ascend_tyche_data(
         root_directory=Path(path),

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/data_classes/__init__.py

@@ -0,0 +1,63 @@
+"""This package provides the classes used to store data acquired at various stages of the data workflow and to
+configure various pipelines used in the Sun lab. These classes are used across all stages of data acquisition,
+preprocessing, and processing in the lab, across multiple machines (PCs). Many classes in this package are designed to
+be saved to disk as .yaml files and restored from the .yaml files as needed."""
+
+from .runtime_data import (
+    ZaberPositions,
+    MesoscopePositions,
+    HardwareConfiguration,
+    RunTrainingDescriptor,
+    LickTrainingDescriptor,
+    MesoscopeExperimentDescriptor,
+)
+from .session_data import (
+    RawData,
+    SessionData,
+    MesoscopeData,
+    ProcessedData,
+    DeepLabCutData,
+    VRPCDestinations,
+    ConfigurationData,
+    VRPCPersistentData,
+    ProjectConfiguration,
+    ScanImagePCPersistentData,
+    replace_root_path,
+)
+from .surgery_data import (
+    DrugData,
+    ImplantData,
+    SubjectData,
+    SurgeryData,
+    InjectionData,
+    ProcedureData,
+)
+from .configuration_data import ExperimentState, 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/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/data_classes/configuration_data.py

@@ -0,0 +1,64 @@
+"""This module provides classes used to configure data acquisition and processing runtimes in the Sun lab.
+Classes from this library are saved as .yaml files to be edited by the user when a new project and / or session
+is created by the sl-experiment library. The runtime settings are then loaded from user-edited .yaml files by various
+lab pipelines."""
+
+import copy
+from pathlib import Path
+from dataclasses import field, dataclass
+
+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
+    """The integer code of the experiment state. Experiment states do not have a predefined meaning, Instead, each 
+    project is expected to define and follow its own experiment state code mapping. Typically, the experiment state 
+    code is used to denote major experiment stages, such as 'baseline', 'task', 'cooldown', etc. Note, the same 
+    experiment state code can be used by multiple sequential ExperimentState instances to change the VR system states 
+    while maintaining the same experiment state."""
+    vr_state_code: int
+    """One of the supported VR system state-codes. Currently, the Mesoscope-VR system supports two state codes. State 
+    code '1' denotes 'REST' state and code '2' denotes 'RUN' state. Note, multiple consecutive ExperimentState 
+    instances with different experiment state codes can reuse the same VR state code."""
+    state_duration_s: float
+    """The time, in seconds, to maintain the current combination of the experiment and VR states."""
+
+
+@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=lambda: {0: 30.0, 1: 30.0, 2: 30.0, 3: 30.0, 4: 30.0})
+    """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."""
+    experiment_states: dict[str, ExperimentState] = field(
+        default_factory=lambda: {
+            "baseline": ExperimentState(experiment_state_code=1, vr_state_code=1, state_duration_s=30),
+            "experiment": ExperimentState(experiment_state_code=2, vr_state_code=2, state_duration_s=120),
+            "cooldown": ExperimentState(experiment_state_code=3, vr_state_code=1, state_duration_s=15),
+        }
+    )
+    """A dictionary that uses human-readable state-names as keys and ExperimentState instances as values. Each 
+    ExperimentState instance represents a phase of the experiment."""

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)