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

sl_shared_assets/__init__.py

@@ -5,6 +5,8 @@ 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 .server import Server, ServerCredentials
 from .suite2p import (
     Suite2PConfiguration,
@@ -31,6 +33,10 @@ from .data_classes import (
 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",
@@ -54,7 +60,7 @@ __all__ = [
     "LickTrainingDescriptor",
     "ExperimentConfiguration",
     "MesoscopeExperimentDescriptor",
-    "ProcessingTracker"
+    "ProcessingTracker",
     # Transfer tools module
     "transfer_directory",
     # Packaging tools module

sl_shared_assets/__init__.pyi

@@ -0,0 +1,51 @@
+from .server import (
+    Server as Server,
+    ServerCredentials as ServerCredentials,
+)
+from .suite2p import Suite2PConfiguration as Suite2PConfiguration
+from .data_classes 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,
+    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",
+    "SubjectData",
+    "SurgeryData",
+    "InjectionData",
+    "ProcedureData",
+    "ZaberPositions",
+    "ExperimentState",
+    "MesoscopePositions",
+    "ProjectConfiguration",
+    "HardwareConfiguration",
+    "RunTrainingDescriptor",
+    "LickTrainingDescriptor",
+    "ExperimentConfiguration",
+    "MesoscopeExperimentDescriptor",
+    "ProcessingTracker",
+    "transfer_directory",
+    "calculate_directory_checksum",
+]

sl_shared_assets/ascension_tools.py

@@ -14,10 +14,6 @@ from .data_classes import SessionData, ProjectConfiguration
 from .transfer_tools import transfer_directory
 from .packaging_tools import calculate_directory_checksum
 
-# Ensures the console is enabled when this file is imported
-if not console.enabled:
-    console.enable()
-
 
 def _generate_session_name(acquisition_path: Path) -> str:
     """Generates a session name using the last modification time of a zstack.mat or MotionEstimator.me file.

sl_shared_assets/ascension_tools.pyi

@@ -0,0 +1,68 @@
+from pathlib import Path
+
+from .data_classes import (
+    SessionData as SessionData,
+    ProjectConfiguration as ProjectConfiguration,
+)
+from .transfer_tools import transfer_directory as transfer_directory
+from .packaging_tools import calculate_directory_checksum as calculate_directory_checksum
+
+def _generate_session_name(acquisition_path: Path) -> str:
+    """Generates a session name using the last modification time of a zstack.mat or MotionEstimator.me file.
+
+    This worker function uses one of the motion estimation files stored in each Tyche 'acquisition' subfolder to
+    generate a modern Sun lab timestamp-based session name. This is used to translate the original Tyche session naming
+    pattern into the pattern used by all modern Sun lab projects and pipelines.
+
+    Args:
+        acquisition_path: The absolute path to the target acquisition folder. These folders are found under the 'day'
+            folders for each animal, e.g.: Tyche-A7/2022_01_03/1.
+
+    Returns:
+        The modernized session name.
+    """
+
+def _reorganize_data(session_data: SessionData, source_root: Path) -> bool:
+    """Reorganizes and moves the session's data from the source folder in the old Tyche data hierarchy to the raw_data
+    folder in the newly created modern hierarchy.
+
+    This worker function is used to physically rearrange the data from the original Tyche data structure to the
+    new data structure. It both moves the existing files to their new destinations and renames certain files to match
+    the modern naming convention used in the Sun lab.
+
+    Args:
+        session_data: The initialized SessionData instance managing the 'ascended' (modernized) session data hierarchy.
+        source_root: The absolute path to the old Tyche data hierarchy folder that stores session's data.
+
+    Returns:
+        True if the ascension process was successfully completed. False if the process encountered missing data or
+        otherwise did not go as expected. When the method returns False, the runtime function requests user intervention
+        to finalize the process manually.
+    """
+
+def ascend_tyche_data(root_directory: Path, output_root_directory: Path, server_root_directory: Path) -> None:
+    """Reformats the old Tyche data to use the modern Sun lab layout and metadata files.
+
+    This function is used to convert old Tyche data to the modern data management standard. This is used to make the
+    data compatible with the modern Sun lab data workflows.
+
+    Notes:
+        This function is statically written to work with the raw Tyche dataset featured in the OSM manuscript:
+        https://www.nature.com/articles/s41586-024-08548-w. Additionally, it assumes that the dataset has been
+        preprocessed with the early Sun lab mesoscope compression pipeline. The function will not work for any other
+        project or data hierarchy.
+
+        As part of its runtime, the function automatically transfers the ascended session data to the BioHPC server.
+        Since transferring the data over the network is the bottleneck of this pipeline, it runs in a single-threaded
+        mode and is constrained by the communication channel between the local machine and the BioHPC server. Calling
+        this function for a large number of sessions will result in a long processing time due to the network data
+        transfer.
+
+    Args:
+        root_directory: The directory that stores one or more Tyche animal folders. This can be conceptualized as the
+            root directory for the Tyche project.
+        output_root_directory: The path to the local directory where to generate the converted Tyche project hierarchy.
+            Typically, this is the 'root' directory where all other Sun lab projects are stored.
+        server_root_directory: The path to the local filesystem-mounted BioHPC server storage directory. Note, this
+            directory hs to be mapped to the local filesystem via the SMB or equivalent protocol.
+    """

sl_shared_assets/cli.py

@@ -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 .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.
+
+    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.
+    """