sl-shared-assets 1.0.0rc20__py3-none-any.whl → 1.0.0rc22__py3-none-any.whl

sl_shared_assets/__init__.py

@@ -2,14 +2,13 @@
 
 See https://github.com/Sun-Lab-NBB/sl-shared-assets for more details.
 API documentation: https://sl-shared-assets-api-docs.netlify.app/
-Authors: Ivan Kondratyev (Inkaros), Kushaan Gupta, Yuantao Deng
+Authors: Ivan Kondratyev (Inkaros), Kushaan Gupta, Yuantao Deng, Natalie Yeung
 """
 
 from ataraxis_base_utilities import console
 
-from .tools import transfer_directory, calculate_directory_checksum
-from .server import Server, ServerCredentials
-from .suite2p import MultiDayS2PConfiguration, SingleDayS2PConfiguration
+from .tools import transfer_directory, verify_session_checksum, generate_project_manifest, calculate_directory_checksum
+from .server import Job, Server, ServerCredentials
 from .data_classes import (
     RawData,
     DrugData,
@@ -18,23 +17,24 @@ from .data_classes import (
     SubjectData,
     SurgeryData,
     InjectionData,
-    MesoscopeData,
     ProcedureData,
     ProcessedData,
-    DeepLabCutData,
+    MesoscopePaths,
     ZaberPositions,
     ExperimentState,
-    VRPCDestinations,
-    ConfigurationData,
+    MesoscopeCameras,
     MesoscopePositions,
-    VRPCPersistentData,
     ProjectConfiguration,
-    HardwareConfiguration,
     RunTrainingDescriptor,
     LickTrainingDescriptor,
-    ExperimentConfiguration,
-    ScanImagePCPersistentData,
+    MesoscopeHardwareState,
+    MesoscopeMicroControllers,
+    MesoscopeAdditionalFirmware,
+    MesoscopeSystemConfiguration,
     MesoscopeExperimentDescriptor,
+    MesoscopeExperimentConfiguration,
+    get_system_configuration_data,
+    set_system_configuration_file,
 )
 
 # Ensures console is enabled when this library is imported
@@ -42,24 +42,16 @@ if not console.enabled:
     console.enable()
 
 __all__ = [
-    # Server module
+    # Server package
     "Server",
     "ServerCredentials",
-    # Suite2p package
-    "SingleDayS2PConfiguration",
-    "MultiDayS2PConfiguration",
-    # Data classes module
+    "Job",
+    # Data classes package
     "DrugData",
     "ImplantData",
     "SessionData",
     "RawData",
     "ProcessedData",
-    "ConfigurationData",
-    "DeepLabCutData",
-    "VRPCPersistentData",
-    "ScanImagePCPersistentData",
-    "MesoscopeData",
-    "VRPCDestinations",
     "SubjectData",
     "SurgeryData",
     "InjectionData",
@@ -68,13 +60,21 @@ __all__ = [
     "ExperimentState",
     "MesoscopePositions",
     "ProjectConfiguration",
-    "HardwareConfiguration",
+    "MesoscopeHardwareState",
     "RunTrainingDescriptor",
     "LickTrainingDescriptor",
-    "ExperimentConfiguration",
+    "MesoscopeExperimentConfiguration",
     "MesoscopeExperimentDescriptor",
-    # Transfer tools module
+    "MesoscopeSystemConfiguration",
+    "MesoscopePaths",
+    "MesoscopeCameras",
+    "MesoscopeMicroControllers",
+    "MesoscopeAdditionalFirmware",
+    "get_system_configuration_data",
+    "set_system_configuration_file",
+    # Tools package
     "transfer_directory",
-    # Packaging tools module
+    "generate_project_manifest",
+    "verify_session_checksum",
     "calculate_directory_checksum",
 ]

sl_shared_assets/__init__.pyi

@@ -1,15 +1,14 @@
 from .tools import (
     transfer_directory as transfer_directory,
+    verify_session_checksum as verify_session_checksum,
+    generate_project_manifest as generate_project_manifest,
     calculate_directory_checksum as calculate_directory_checksum,
 )
 from .server import (
+    Job as Job,
     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,
@@ -18,41 +17,35 @@ from .data_classes import (
     SubjectData as SubjectData,
     SurgeryData as SurgeryData,
     InjectionData as InjectionData,
-    MesoscopeData as MesoscopeData,
     ProcedureData as ProcedureData,
     ProcessedData as ProcessedData,
-    DeepLabCutData as DeepLabCutData,
+    MesoscopePaths as MesoscopePaths,
     ZaberPositions as ZaberPositions,
     ExperimentState as ExperimentState,
-    VRPCDestinations as VRPCDestinations,
-    ConfigurationData as ConfigurationData,
+    MesoscopeCameras as MesoscopeCameras,
     MesoscopePositions as MesoscopePositions,
-    VRPCPersistentData as VRPCPersistentData,
     ProjectConfiguration as ProjectConfiguration,
-    HardwareConfiguration as HardwareConfiguration,
     RunTrainingDescriptor as RunTrainingDescriptor,
     LickTrainingDescriptor as LickTrainingDescriptor,
-    ExperimentConfiguration as ExperimentConfiguration,
-    ScanImagePCPersistentData as ScanImagePCPersistentData,
+    MesoscopeHardwareState as MesoscopeHardwareState,
+    MesoscopeMicroControllers as MesoscopeMicroControllers,
+    MesoscopeAdditionalFirmware as MesoscopeAdditionalFirmware,
+    MesoscopeSystemConfiguration as MesoscopeSystemConfiguration,
     MesoscopeExperimentDescriptor as MesoscopeExperimentDescriptor,
+    MesoscopeExperimentConfiguration as MesoscopeExperimentConfiguration,
+    get_system_configuration_data as get_system_configuration_data,
+    set_system_configuration_file as set_system_configuration_file,
 )
 
 __all__ = [
     "Server",
     "ServerCredentials",
-    "SingleDayS2PConfiguration",
-    "MultiDayS2PConfiguration",
+    "Job",
     "DrugData",
     "ImplantData",
     "SessionData",
     "RawData",
     "ProcessedData",
-    "ConfigurationData",
-    "DeepLabCutData",
-    "VRPCPersistentData",
-    "ScanImagePCPersistentData",
-    "MesoscopeData",
-    "VRPCDestinations",
     "SubjectData",
     "SurgeryData",
     "InjectionData",
@@ -61,11 +54,20 @@ __all__ = [
     "ExperimentState",
     "MesoscopePositions",
     "ProjectConfiguration",
-    "HardwareConfiguration",
+    "MesoscopeHardwareState",
     "RunTrainingDescriptor",
     "LickTrainingDescriptor",
-    "ExperimentConfiguration",
+    "MesoscopeExperimentConfiguration",
     "MesoscopeExperimentDescriptor",
+    "MesoscopeSystemConfiguration",
+    "MesoscopePaths",
+    "MesoscopeCameras",
+    "MesoscopeMicroControllers",
+    "MesoscopeAdditionalFirmware",
+    "get_system_configuration_data",
+    "set_system_configuration_file",
     "transfer_directory",
+    "generate_project_manifest",
+    "verify_session_checksum",
     "calculate_directory_checksum",
 ]

sl_shared_assets/cli.py

@@ -3,46 +3,168 @@
 from pathlib import Path
 
 import click
+from ataraxis_base_utilities import LogLevel, console, ensure_directory_exists
 
-from .tools import ascend_tyche_data
+from .tools import ascend_tyche_data, verify_session_checksum, generate_project_manifest
 from .server import generate_server_credentials
-from .data_classes import replace_root_path
+from .data_classes import (
+    ExperimentState,
+    ProjectConfiguration,
+    MesoscopeSystemConfiguration,
+    MesoscopeExperimentConfiguration,
+    get_system_configuration_data,
+    set_system_configuration_file,
+)
 
 
 @click.command()
 @click.option(
-    "-p",
-    "--path",
+    "-sp",
+    "--session_path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    required=True,
+    help="The absolute path to the session whose raw data needs to be verified for potential corruption.",
+)
+def verify_session_integrity(session_path: str) -> None:
+    """Checks the integrity of the target session's raw data (contents of the raw_data directory).
+
+    This command assumes that the data has been checksummed during acquisition and contains an ax_checksum.txt file
+    that stores the data checksum generated before transferring the data to long-term storage destination. This function
+    always verified the integrity of the 'raw_data' directory. It does not work with 'processed_data' or any other
+    directories. If the session data was corrupted, the command removes the 'telomere.bin' file, marking the session as
+    'incomplete' and automatically excluding it from all further automated processing runtimes.
+    """
+    session = Path(session_path)
+    if verify_session_checksum(session):
+        console.echo(message=f"Session {session.stem} raw data integrity: verified.", level=LogLevel.SUCCESS)
+    else:
+        console.echo(message=f"Session {session.stem} raw data integrity: compromised!", level=LogLevel.ERROR)
+
+
+@click.command()
+@click.option(
+    "-pp",
+    "--project_path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    required=True,
+    help="The absolute path to the project directory where raw session data is stored.",
+)
+@click.option(
+    "-od",
+    "--output_directory",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    required=True,
+    help="The absolute path to the directory where to store the generated project manifest file.",
+)
+@click.option(
+    "-ppp",
+    "--project_processed_path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    required=False,
+    help=(
+        "The absolute path to the project directory where processed session data is stored, if different from the "
+        "directory used to store raw session data. Typically, this extra argument is only used when processing data "
+        "stored on remote compute server(s)."
+    ),
+)
+def generate_project_manifest_file(
+    project_path: str, output_directory: str, project_processed_path: str | None
+) -> None:
+    """Generates the manifest .feather file that provides information about the data-processing state of all available
+    project sessions.
+
+    The manifest file is typically used when batch-processing session data on the remote compute server. It contains the
+    comprehensive snapshot of the available project's data in a table-compatible format that can also be transferred
+    between machines (as it is cached in a file).
+    """
+    generate_project_manifest(
+        raw_project_directory=Path(project_path),
+        output_directory=Path(output_directory),
+        processed_project_directory=Path(project_processed_path) if project_processed_path else None,
+    )
+    console.echo(message=f"Project {Path(project_path).stem} data manifest file: generated.", level=LogLevel.SUCCESS)
+
+
+@click.command()
+@click.option(
+    "-od",
+    "--output_directory",
     type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
     required=True,
-    prompt="Enter the path to the new local directory where to store all project subdirectories: ",
-    help="The path to the new local directory where to store all project subdirectories.",
+    help="The absolute path to the directory where to store the generated system configuration file.",
 )
-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.
+@click.option(
+    "-as",
+    "--acquisition_system",
+    type=str,
+    show_default=True,
+    required=True,
+    default="mesoscope-vr",
+    help=(
+        "The type (name) of the data acquisition system for which to generate the configuration file. Note, currently, "
+        "only the following types are supported: mesoscope-vr."
+    ),
+)
+def generate_system_configuration_file(output_directory: str, acquisition_system: str) -> None:
+    """Generates a precursor system configuration file for the target acquisition system and configures all local
+    Sun lab libraries to use that file to load the acquisition system configuration data.
 
-    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.
+    This command is typically used when setting up a new data acquisition system in the lab. The system configuration
+    only needs to be specified on the machine (PC) that runs the sl-experiment library and manages the acquisition
+    runtime if the system uses multiple machines (PCs). Once the system configuration .yaml file is created via this
+    command, editing the configuration parameters in the file will automatically take effect during all following
+    runtimes.
     """
-    replace_root_path(path=Path(path))
+
+    # Verifies that the input path is a valid directory path and, if necessary, creates the directory specified by the
+    # path.
+    path = Path(output_directory)
+    if not path.is_dir():
+        message = (
+            f"Unable to generate the system configuration file for the system '{acquisition_system}'. The path to "
+            f"the output directory ({path}) is not a valid directory path."
+        )
+        console.error(message=message, error=ValueError)
+    else:
+        ensure_directory_exists(path)
+
+    # Mesoscope
+    if acquisition_system.lower() == "mesoscope-vr":
+        file_name = "mesoscope_system_configuration.yaml"
+        file_path = path.joinpath(file_name)
+        system_configuration = MesoscopeSystemConfiguration()
+        system_configuration.save(file_path)
+        set_system_configuration_file(file_path)
+        message = (
+            f"Mesoscope-VR system configuration file: generated. Edit the configuration parameters stored inside the "
+            f"{file_name} file to match the state of the acquisition system and use context."
+        )
+        console.echo(message=message, level=LogLevel.SUCCESS)
+
+    # For unsupported system types, raises an error message
+    else:
+        message = (
+            f"Unable to generate the system configuration file for the system '{acquisition_system}'. The input "
+            f"acquisition system is not supported (not recognized). Currently, only the following acquisition "
+            f"systems are supported: mesoscope-vr."
+        )
+        console.error(message=message, error=ValueError)
 
 
 @click.command()
 @click.option(
-    "-o",
+    "-od",
     "--output_directory",
     type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
     required=True,
-    help="The absolute path to the directory where to create the credentials file.",
+    help="The absolute path to the directory where to store the generated server credentials file.",
 )
 @click.option(
     "-h",
     "--host",
     type=str,
-    show_default=True,
     required=True,
+    show_default=True,
     default="cbsuwsun.biohpc.cornell.edu",
     help="The host name or IP address of the server to connect to.",
 )
@@ -63,49 +185,153 @@ 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 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.
+    This command is used to set up access to compute servers and clusters on new machines (PCs). The data stored inside
+    the server_credentials.yaml file generated by this command is used by the Server and Job classes used in many Sun
+    lab data processing libraries.
     """
     generate_server_credentials(
         output_directory=Path(output_directory), username=username, password=password, host=host
     )
+    message = (
+        f"Server access credentials file: generated. If necessary, remember to edit the data acquisition system "
+        f"configuration file to include the path to the credentials file generated via this CLI."
+    )
+    console.echo(message=message, level=LogLevel.SUCCESS)
 
 
 @click.command()
 @click.option(
     "-p",
-    "--path",
-    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    "--project",
+    type=str,
     required=True,
-    help="The absolute path to the directory that stores original Tyche animal folders.",
+    help="The name of the project to be created.",
 )
 @click.option(
-    "-o",
-    "--output_directory",
-    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    "-sli",
+    "--surgery_log_id",
+    type=str,
     required=True,
-    help="The absolute path to the local directory where to create the ascended Tyche project hierarchy.",
+    help="The 44-symbol alpha-numeric ID code used by the project's surgery log Google sheet.",
 )
 @click.option(
-    "-s",
-    "--server_directory",
+    "-wli",
+    "--water_restriction_log_id",
+    type=str,
+    required=True,
+    help="The 44-symbol alpha-numeric ID code used by the project's water restriction log Google sheet.",
+)
+def generate_project_configuration_file(project: str, surgery_log_id: str, water_restriction_log_id: str) -> None:
+    """Generates a new project directory hierarchy and writes its configuration as a project_configuration.yaml file.
+
+    This command creates new Sun lab projects. Until a project is created in this fashion, all data-acquisition and
+    data-processing commands from sl-experiment and sl-forgery libraries targeting the project will not work. This
+    command is intended to be called on the main computer of the data-acquisition system(s) used by the project. Note,
+    this command assumes that the local machine (PC) is the main PC of the data acquisition system and has a valid
+    acquisition system configuration .yaml file.
+    """
+
+    # Queries the data acquisition configuration data. Specifically, this is used to get the path to the root
+    # directory where all projects are stored on the local machine.
+    system_configuration = get_system_configuration_data()
+    file_path = system_configuration.paths.root_directory.joinpath(
+        project, "configuration", "project_configuration.yaml"
+    )
+
+    # Generates the initial project directory hierarchy
+    ensure_directory_exists(file_path)
+
+    # Saves project configuration data as a .yaml file to the 'configuration' directory of the created project
+    configuration = ProjectConfiguration(
+        project_name=project, surgery_sheet_id=surgery_log_id, water_log_sheet_id=water_restriction_log_id
+    )
+    configuration.save(path=file_path.joinpath())
+    console.echo(message=f"Project {project} data structure and configuration file: generated.", level=LogLevel.SUCCESS)
+
+
+@click.command()
+@click.option(
+    "-p",
+    "--project",
+    type=str,
+    required=True,
+    help="The name of the project for which to generate the new experiment configuration file.",
+)
+@click.option(
+    "-e",
+    "--experiment",
+    type=str,
+    required=True,
+    help="The name of the experiment. Note, the generated experiment configuration file will also use this name.",
+)
+@click.option(
+    "-sc",
+    "--state_count",
+    type=int,
+    required=True,
+    help="The total number of experiment and acquisition system state combinations in the experiment.",
+)
+def generate_experiment_configuration_file(project: str, experiment: str, state_count: int) -> None:
+    """Generates a precursor experiment configuration .yaml file for the target experiment inside the project's
+    configuration folder.
+
+    This command assists users in creating new experiment configurations, by statically resolving the structure (layout)
+    of the appropriate experiment configuration file for the acquisition system of the local machine (PC). Specifically,
+    the generated precursor will contain the correct number of experiment state entries initialized to nonsensical
+    default value. The user needs to manually edit the configuration file to properly specify their experiment runtime
+    parameters and state transitions before running the experiment. In a sense, this command acts as an 'experiment
+    template' generator.
+    """
+
+    # Resolves the acquisition system configuration. Uses the path to the local project directory and the project name
+    # to determine where to save the experiment configuration file
+    acquisition_system = get_system_configuration_data()
+    file_path = acquisition_system.paths.root_directory.joinpath(project, "configuration", f"{experiment}.yaml")
+
+    # Loops over the number of requested states and, for each, generates a precursor experiment state field inside the
+    # 'states' dictionary.
+    states = {}
+    for state in range(state_count):
+        states[f"state_{state + 1}"] = ExperimentState(
+            experiment_state_code=state + 1,  # Assumes experiment state sequences are 1-based
+            system_state_code=0,
+            state_duration_s=60,
+        )
+
+    # Depending on the acquisition system, packs state data into the appropriate experiment configuration class and
+    # saves it to the project's configuration folder as a .yaml file.
+    if acquisition_system.name == "mesoscope-vr":
+        experiment_configuration = MesoscopeExperimentConfiguration(experiment_states=states)
+
+    else:
+        message = (
+            f"Unable to generate the experiment {experiment} configuration file for the project {project}. "
+            f"The data acquisition system of the local machine (PC) is not supported (not recognized). Currently, only "
+            f"the following acquisition systems are supported: mesoscope-vr."
+        )
+        console.error(message=message, error=ValueError)
+        raise ValueError(message)  # Fall-back to appease mypy, should not be reachable
+
+    experiment_configuration.to_yaml(file_path=file_path)
+    console.echo(message=f"Experiment {experiment} configuration file: generated.", level=LogLevel.SUCCESS)
+
+
+@click.command()
+@click.option(
+    "-id",
+    "--input_directory",
     type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
     required=True,
-    help=(
-        "The path to the SMB-mounted BioHPC server directory where to transfer the ascended Tyche project "
-        "hierarchy after it is created."
-    ),
+    help="The absolute path to the directory that stores original Tyche animal folders.",
 )
-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.
+def ascend_tyche_directory(input_directory: str) -> None:
+    """Restructures old Tyche project data to use the modern Sun lab data structure and uploads them to the processing
+    server.
 
-    This CLI is used to convert ('ascend') the old Tyche project data to the modern Sun lab structure. After
+    This command 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.
+    will not work for any other project or data. Also, this command will only work on a machine (PC) that belongs to a
+    valid Sun lab data acquisition system, such as VRPC of the Mesoscope-VR system.
     """
-    ascend_tyche_data(
-        root_directory=Path(path),
-        output_root_directory=Path(output_directory),
-        server_root_directory=Path(server_directory),
-    )
+    ascend_tyche_data(root_directory=Path(input_directory))