sl-shared-assets 1.0.0rc14__tar.gz → 1.0.0rc15__tar.gz

{sl_shared_assets-1.0.0rc14 → sl_shared_assets-1.0.0rc15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sl-shared-assets
-Version: 1.0.0rc14
+Version: 1.0.0rc15
 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.0rc14 → sl_shared_assets-1.0.0rc15}/docs/source/api.rst

@@ -21,29 +21,22 @@ Command Line Interfaces
    :prog: sl-ascend
    :nested: full
 
-Packaging Tools
-===============
-.. automodule:: sl_shared_assets.packaging_tools
+Tools
+=====
+.. automodule:: sl_shared_assets.tools
    :members:
    :undoc-members:
    :show-inheritance:
 
-Transfer Tools
-==============
-.. automodule:: sl_shared_assets.transfer_tools
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Suite2P Configuration Classes
-=============================
+Suite2P Configuration
+=====================
 .. automodule:: sl_shared_assets.suite2p
    :members:
    :undoc-members:
    :show-inheritance:
 
-General Configuration and Data Storage Classes
-==============================================
+General Data and Configuration Classes
+======================================
 .. automodule:: sl_shared_assets.data_classes
    :members:
    :undoc-members:
@@ -55,10 +48,3 @@ Compute Server Tools
    :members:
    :undoc-members:
    :show-inheritance:
-
-Ascension Tools
-===============
-.. automodule:: sl_shared_assets.ascension_tools
-   :members:
-   :undoc-members:
-   :show-inheritance:

{sl_shared_assets-1.0.0rc14 → sl_shared_assets-1.0.0rc15}/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.0rc14"
+version = "1.0.0rc15"
 description = "Stores assets shared between multiple Sun (NeuroAI) lab data pipelines."
 readme = "README.md"
 license = { file = "LICENSE" }

{sl_shared_assets-1.0.0rc14 → sl_shared_assets-1.0.0rc15}/src/sl_shared_assets/__init__.py

@@ -7,31 +7,35 @@ 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:
@@ -41,12 +45,21 @@ __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",
@@ -60,7 +73,6 @@ __all__ = [
     "LickTrainingDescriptor",
     "ExperimentConfiguration",
     "MesoscopeExperimentDescriptor",
-    "ProcessingTracker",
     # Transfer tools module
     "transfer_directory",
     # Packaging tools module

sl_shared_assets-1.0.0rc15/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.0rc14 → sl_shared_assets-1.0.0rc15}/src/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()

{sl_shared_assets-1.0.0rc14 → sl_shared_assets-1.0.0rc15}/src/sl_shared_assets/cli.pyi

@@ -1,6 +1,6 @@
+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
-from .ascension_tools import ascend_tyche_data as ascend_tyche_data
 
 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.

sl_shared_assets-1.0.0rc15/src/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-1.0.0rc14/src/sl_shared_assets → sl_shared_assets-1.0.0rc15/src/sl_shared_assets/data_classes}/__init__.pyi

@@ -1,37 +1,49 @@
-from .server import (
-    Server as Server,
-    ServerCredentials as ServerCredentials,
+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 .suite2p import Suite2PConfiguration as Suite2PConfiguration
-from .data_classes import (
+from .surgery_data import (
     DrugData as DrugData,
     ImplantData as ImplantData,
-    SessionData as SessionData,
     SubjectData as SubjectData,
     SurgeryData as SurgeryData,
     InjectionData as InjectionData,
     ProcedureData as ProcedureData,
-    ZaberPositions as ZaberPositions,
+)
+from .configuration_data import (
     ExperimentState as ExperimentState,
-    ProcessingTracker as ProcessingTracker,
-    MesoscopePositions as MesoscopePositions,
-    ProjectConfiguration as ProjectConfiguration,
-    HardwareConfiguration as HardwareConfiguration,
-    RunTrainingDescriptor as RunTrainingDescriptor,
-    LickTrainingDescriptor as LickTrainingDescriptor,
     ExperimentConfiguration as ExperimentConfiguration,
-    MesoscopeExperimentDescriptor as MesoscopeExperimentDescriptor,
 )
-from .transfer_tools import transfer_directory as transfer_directory
-from .packaging_tools import calculate_directory_checksum as calculate_directory_checksum
 
 __all__ = [
-    "Server",
-    "ServerCredentials",
-    "Suite2PConfiguration",
     "DrugData",
     "ImplantData",
     "SessionData",
+    "RawData",
+    "ProcessedData",
+    "ConfigurationData",
+    "DeepLabCutData",
+    "VRPCPersistentData",
+    "ScanImagePCPersistentData",
+    "MesoscopeData",
+    "VRPCDestinations",
     "SubjectData",
     "SurgeryData",
     "InjectionData",
@@ -45,7 +57,5 @@ __all__ = [
     "LickTrainingDescriptor",
     "ExperimentConfiguration",
     "MesoscopeExperimentDescriptor",
-    "ProcessingTracker",
-    "transfer_directory",
-    "calculate_directory_checksum",
+    "replace_root_path",
 ]

sl_shared_assets-1.0.0rc15/src/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-1.0.0rc15/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)