sl-shared-assets 4.0.1__py3-none-any.whl → 5.0.1__py3-none-any.whl

sl_shared_assets/data_classes/session_data.pyi

@@ -1,379 +0,0 @@
-from enum import StrEnum
-from pathlib import Path
-from dataclasses import field, dataclass
-
-from _typeshed import Incomplete
-from ataraxis_data_structures import YamlConfig
-
-from .configuration_data import (
-    AcquisitionSystems as AcquisitionSystems,
-    get_system_configuration_data as get_system_configuration_data,
-)
-
-class SessionTypes(StrEnum):
-    """Defines the set of data acquisition session types supported by various data acquisition systems used in the
-    Sun lab.
-
-    A data acquisition session broadly encompasses a recording session carried out to either: acquire experiment data,
-    train the animal for the upcoming experiments, or to assess the quality of surgical or other pre-experiment
-    intervention.
-
-    Notes:
-        This enumeration does not differentiate between different acquisition systems. Different acquisition systems
-        support different session types and may not be suited for acquiring some of the session types listed in this
-        enumeration.
-    """
-
-    LICK_TRAINING = "lick training"
-    RUN_TRAINING = "run training"
-    MESOSCOPE_EXPERIMENT = "mesoscope experiment"
-    WINDOW_CHECKING = "window checking"
-
-class TrackerFileNames(StrEnum):
-    """Defines a set of processing tacker .yaml files supported by various Sun lab data preprocessing, processing, and
-    dataset formation pipelines.
-
-    This enumeration standardizes the names for all processing tracker files used in the lab. It is designed to be used
-    via the get_processing_tracker() function to generate ProcessingTracker instances.
-    """
-
-    BEHAVIOR = "behavior_processing_tracker.yaml"
-    SUITE2P = "suite2p_processing_tracker.yaml"
-    DATASET = "dataset_formation_tracker.yaml"
-    VIDEO = "video_processing_tracker.yaml"
-    INTEGRITY = "integrity_verification_tracker.yaml"
-
-@dataclass()
-class RawData:
-    """Stores the paths to the directories and files that make up the 'raw_data' session-specific directory.
-
-    The raw_data directory stores the data acquired during the session data acquisition runtime, before and after
-    preprocessing. Since preprocessing does not irreversibly alter the data, any data in that folder is considered
-    'raw,' event if preprocessing losslessly re-compresses the data for efficient transfer.
-
-    Notes:
-        Sun lab data management strategy primarily relies on keeping multiple redundant copies of the raw_data for
-        each acquired session. Typically, one copy is stored on the lab's processing server and the other is stored on
-        the NAS.
-    """
-
-    raw_data_path: Path = ...
-    camera_data_path: Path = ...
-    mesoscope_data_path: Path = ...
-    behavior_data_path: Path = ...
-    zaber_positions_path: Path = ...
-    session_descriptor_path: Path = ...
-    hardware_state_path: Path = ...
-    surgery_metadata_path: Path = ...
-    session_data_path: Path = ...
-    experiment_configuration_path: Path = ...
-    mesoscope_positions_path: Path = ...
-    window_screenshot_path: Path = ...
-    system_configuration_path: Path = ...
-    checksum_path: Path = ...
-    telomere_path: Path = ...
-    ubiquitin_path: Path = ...
-    nk_path: Path = ...
-    def resolve_paths(self, root_directory_path: Path) -> None:
-        """Resolves all paths managed by the class instance based on the input root directory path.
-
-        This method is called each time the (wrapper) SessionData class is instantiated to regenerate the managed path
-        hierarchy on any machine that instantiates the class.
-
-        Args:
-            root_directory_path: The path to the top-level directory of the session. Typically, this path is assembled
-                using the following hierarchy: root/project/animal/session_id
-        """
-    def make_directories(self) -> None:
-        """Ensures that all major subdirectories and the root directory exist, creating any missing directories.
-
-        This method is called each time the (wrapper) SessionData class is instantiated and allowed to generate
-        missing data directories.
-        """
-
-@dataclass()
-class ProcessedData:
-    """Stores the paths to the directories and files that make up the 'processed_data' session-specific directory.
-
-    The processed_data directory stores the data generated by various processing pipelines from the raw data (contents
-    of the raw_data directory). Processed data represents an intermediate step between raw data and the dataset used in
-    the data analysis, but is not itself designed to be analyzed.
-    """
-
-    processed_data_path: Path = ...
-    camera_data_path: Path = ...
-    mesoscope_data_path: Path = ...
-    behavior_data_path: Path = ...
-    p53_path: Path = ...
-    def resolve_paths(self, root_directory_path: Path) -> None:
-        """Resolves all paths managed by the class instance based on the input root directory path.
-
-        This method is called each time the (wrapper) SessionData class is instantiated to regenerate the managed path
-        hierarchy on any machine that instantiates the class.
-
-        Args:
-            root_directory_path: The path to the top-level directory of the session. Typically, this path is assembled
-                using the following hierarchy: root/project/animal/session_id
-        """
-    def make_directories(self) -> None:
-        """Ensures that all major subdirectories and the root directory exist, creating any missing directories.
-
-        This method is called each time the (wrapper) SessionData class is instantiated and allowed to generate
-        missing data directories.
-        """
-
-@dataclass
-class SessionData(YamlConfig):
-    """Stores and manages the data layout of a single Sun lab data acquisition session.
-
-    The primary purpose of this class is to maintain the session data structure across all supported destinations and to
-    provide a unified data access interface shared by all Sun lab libraries. The class can be used to either generate a
-    new session or load the layout of an already existing session. When the class is used to create a new session, it
-    generates the new session's name using the current UTC timestamp, accurate to microseconds. This ensures that each
-    session 'name' is unique and preserves the overall session order.
-
-    Notes:
-        This class is specifically designed for working with the data from a single session, performed by a single
-        animal under the specific experiment. The class is used to manage both raw and processed data. It follows the
-        data through acquisition, preprocessing, and processing stages of the Sun lab data workflow. This class serves
-        as an entry point for all interactions with the managed session's data.
-    """
-
-    project_name: str
-    animal_id: str
-    session_name: str
-    session_type: str | SessionTypes
-    acquisition_system: str | AcquisitionSystems = ...
-    experiment_name: str | None = ...
-    python_version: str = ...
-    sl_experiment_version: str = ...
-    raw_data: RawData = field(default_factory=Incomplete)
-    processed_data: ProcessedData = field(default_factory=Incomplete)
-    def __post_init__(self) -> None:
-        """Ensures raw_data and processed_data are always instances of RawData and ProcessedData."""
-    @classmethod
-    def create(
-        cls,
-        project_name: str,
-        animal_id: str,
-        session_type: SessionTypes | str,
-        experiment_name: str | None = None,
-        session_name: str | None = None,
-        python_version: str = "3.11.13",
-        sl_experiment_version: str = "2.0.0",
-    ) -> SessionData:
-        """Creates a new SessionData object and generates the new session's data structure on the local PC.
-
-        This method is intended to be called exclusively by the sl-experiment library to create new training or
-        experiment sessions and generate the session data directory tree.
-
-        Notes:
-            To load an already existing session data structure, use the load() method instead.
-
-            This method automatically dumps the data of the created SessionData instance into the session_data.yaml file
-            inside the root 'raw_data' directory of the created hierarchy. It also finds and dumps other configuration
-            files, such as experiment_configuration.yaml and system_configuration.yaml into the same 'raw_data'
-            directory. If the session's runtime is interrupted unexpectedly, the acquired data can still be processed
-            using these pre-saved class instances.
-
-        Args:
-            project_name: The name of the project for which the session is carried out.
-            animal_id: The ID code of the animal participating in the session.
-            session_type: The type of the session. Has to be one of the supported session types exposed by the
-                SessionTypes enumeration.
-            experiment_name: The name of the experiment executed during the session. This optional argument is only
-                used for experiment sessions. Note! The name passed to this argument has to match the name of the
-                experiment configuration .yaml file.
-            session_name: An optional session name override. Generally, this argument should not be provided for most
-                sessions. When provided, the method uses this name instead of generating a new timestamp-based name.
-                This is only used during the 'ascension' runtime to convert old data structures to the modern
-                lab standards.
-            python_version: The string that specifies the Python version used to collect session data. Has to be
-                specified using the major.minor.patch version format.
-            sl_experiment_version: The string that specifies the version of the sl-experiment library used to collect
-                session data. Has to be specified using the major.minor.patch version format.
-
-        Returns:
-            An initialized SessionData instance that stores the layout of the newly created session's data.
-        """
-    @classmethod
-    def load(
-        cls, session_path: Path, processed_data_root: Path | None = None, make_processed_data_directory: bool = False
-    ) -> SessionData:
-        """Loads the SessionData instance from the target session's session_data.yaml file.
-
-        This method is used to load the data layout information of an already existing session. Primarily, this is used
-        when processing session data. Due to how SessionData is stored and used in the lab, this method always loads the
-        data layout from the session_data.yaml file stored inside the 'raw_data' session subfolder. Currently, all
-        interactions with Sun lab data require access to the 'raw_data' folder of each session.
-
-        Notes:
-            To create a new session, use the create() method instead.
-
-        Args:
-            session_path: The path to the root directory of an existing session, e.g.: root/project/animal/session.
-            processed_data_root: If processed data is kept on a drive different from the one that stores raw data,
-                provide the path to the root project directory (directory that stores all Sun lab projects) on that
-                drive. The method will automatically resolve the project/animal/session/processed_data hierarchy using
-                this root path. If raw and processed data are kept on the same drive, keep this set to None.
-            make_processed_data_directory: Determines whether this method should create the processed_data directory if
-                it does not exist.
-
-        Returns:
-            An initialized SessionData instance for the session whose data is stored at the provided path.
-
-        Raises:
-            FileNotFoundError: If the 'session_data.yaml' file is not found under the session_path/raw_data/ subfolder.
-
-        """
-    def runtime_initialized(self) -> None:
-        """Ensures that the 'nk.bin' marker file is removed from the session's raw_data folder.
-
-        The 'nk.bin' marker is generated as part of the SessionData initialization (creation) process to mark sessions
-        that did not fully initialize during runtime. This service method is designed to be called by the sl-experiment
-        library classes to remove the 'nk.bin' marker when it is safe to do so. It should not be called by end-users.
-        """
-    def save(self) -> None:
-        """Saves the instance data to the 'raw_data' directory of the managed session as a 'session_data.yaml' file.
-
-        This is used to save the data stored in the instance to disk so that it can be reused during further stages of
-        data processing. The method is intended to only be used by the SessionData instance itself during its
-        create() method runtime.
-        """
-
-@dataclass()
-class ProcessingTracker(YamlConfig):
-    """Wraps the .yaml file that tracks the state of a data processing runtime and provides tools for communicating the
-    state between multiple processes in a thread-safe manner.
-
-    Primarily, this tracker class is used by all remote data processing pipelines in the lab to prevent race conditions
-    and make it impossible to run multiple processing runtimes at the same time. It is also used to evaluate the status
-    (success / failure) of jobs running on remote compute servers.
-
-    Note:
-        In library version 4.0.0 the processing trackers have been refactored to work similar to 'lock' files. That is,
-        when a runtime is started, the tracker is switched into the 'running' (locked) state until it is unlocked,
-        aborted, or encounters an error. When the tracker is locked, only the same manager process as the one that
-        locked the tracker is allowed to work with session data. This feature allows executing complex processing
-        pipelines that use multiple concurrent and / or sequential processing jobs on the remote server.
-
-        This instance frequently refers to a 'manager process' in method documentation. A 'manager process' is the
-        highest-level process that manages the runtime. When the runtime is executed on remote compute servers, the
-        manager process is typically the process running on the non-server machine (user PC) that executes the remote
-        processing job on the compute server (via SSH or similar protocol). The worker process(es) that run the
-        processing job(s) on the remote compute servers are NOT considered manager processes.
-    """
-
-    file_path: Path
-    _complete: bool = ...
-    _encountered_error: bool = ...
-    _running: bool = ...
-    _manager_id: int = ...
-    _lock_path: str = field(init=False)
-    def __post_init__(self) -> None: ...
-    def _load_state(self) -> None:
-        """Reads the current processing state from the wrapped .YAML file."""
-    def _save_state(self) -> None:
-        """Saves the current processing state stored inside instance attributes to the specified .YAML file."""
-    def start(self, manager_id: int) -> None:
-        """Configures the tracker file to indicate that a manager process is currently executing the tracked processing
-        runtime.
-
-        Calling this method effectively 'locks' the tracked session and processing runtime combination to only be
-        accessible from the manager process that calls this method. Calling this method for an already running runtime
-        managed by the same process does not have any effect, so it is safe to call this method at the beginning of
-        each processing job that makes up the runtime.
-
-        Args:
-            manager_id: The unique xxHash-64 hash identifier of the manager process which attempts to start the runtime
-                tracked by this tracker file.
-
-        Raises:
-            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
-        """
-    def error(self, manager_id: int) -> None:
-        """Configures the tracker file to indicate that the tracked processing runtime encountered an error and failed
-        to complete.
-
-        This method fulfills two main purposes. First, it 'unlocks' the runtime, allowing other manager processes to
-        interface with the tracked runtime. Second, it updates the tracker file to reflect that the runtime was
-        interrupted due to an error, which is used by the manager processes to detect and handle processing failures.
-
-        Args:
-            manager_id: The unique xxHash-64 hash identifier of the manager process which attempts to report that the
-                runtime tracked by this tracker file has encountered an error.
-
-        Raises:
-            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
-        """
-    def stop(self, manager_id: int) -> None:
-        """Configures the tracker file to indicate that the tracked processing runtime has been completed successfully.
-
-        This method 'unlocks' the runtime, allowing other manager processes to interface with the tracked runtime. It
-        also configures the tracker file to indicate that the runtime has been completed successfully, which is used
-        by the manager processes to detect and handle processing completion.
-
-        Args:
-            manager_id: The unique xxHash-64 hash identifier of the manager process which attempts to report that the
-                runtime tracked by this tracker file has been completed successfully.
-
-        Raises:
-            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
-        """
-    def abort(self) -> None:
-        """Resets the runtime tracker file to the default state.
-
-        This method can be used to reset the runtime tracker file, regardless of the current runtime state. Unlike other
-        instance methods, this method can be called from any manager process, even if the runtime is already locked by
-        another process. This method is only intended to be used in the case of emergency to 'unlock' a deadlocked
-        runtime.
-        """
-    @property
-    def is_complete(self) -> bool:
-        """Returns True if the tracker wrapped by the instance indicates that the processing runtime has been completed
-        successfully and that the runtime is not currently ongoing."""
-    @property
-    def encountered_error(self) -> bool:
-        """Returns True if the tracker wrapped by the instance indicates that the processing runtime has aborted due
-        to encountering an error."""
-    @property
-    def is_running(self) -> bool:
-        """Returns True if the tracker wrapped by the instance indicates that the processing runtime is currently
-        ongoing."""
-
-def get_processing_tracker(root: Path, file_name: TrackerFileNames | str) -> ProcessingTracker:
-    """Initializes and returns the ProcessingTracker instance that manages the data stored inside the target processing
-    tracker file.
-
-    This function uses the input root path and tracker file name to first resolve the absolute path to the .yaml data
-    cache of the target processing tracker file and then wrap the file into a ProcessingTracker instance. All Sun lab
-    libraries that use ProcessingTracker instances use this function to access the necessary trackers.
-
-    Notes:
-        If the target file does not exist, this function will create the file as part of the ProcessingTracker
-        initialization.
-
-        This function also generates the corresponding .lock file to ensure that the data inside the processing tracker
-        is accessed by a single process at a time.
-
-    Args:
-        file_name: The name of the target processing tracker file. Has to be one of the names from the TrackerFileNames
-            enumeration.
-        root: The absolute path to the directory where the target file is stored or should be created.
-
-    Returns:
-        The initialized ProcessingTracker instance that manages the data stored in the target file.
-    """
-
-def generate_manager_id() -> int:
-    """Generates and returns a unique integer identifier that can be used to identify the manager process that calls
-    this function.
-
-    The identifier is generated based on the current timestamp, accurate to microseconds, and a random number between 1
-    and 9999999999999. This ensures that the identifier is unique for each function call. The generated identifier
-    string is converted to a unique integer value using the xxHash-64 algorithm before it is returned to the caller.
-
-    Notes:
-        This function should be used to generate manager process identifiers for working with ProcessingTracker
-        instances from sl-shared-assets version 4.0.0 and above.
-    """

sl_shared_assets/data_classes/surgery_data.pyi

@@ -1,89 +0,0 @@
-from dataclasses import dataclass
-
-from ataraxis_data_structures import YamlConfig
-
-@dataclass()
-class SubjectData:
-    """Stores the ID information of the surgical intervention's subject (animal)."""
-
-    id: int
-    ear_punch: str
-    sex: str
-    genotype: str
-    date_of_birth_us: int
-    weight_g: float
-    cage: int
-    location_housed: str
-    status: str
-
-@dataclass()
-class ProcedureData:
-    """Stores the general information about the surgical intervention."""
-
-    surgery_start_us: int
-    surgery_end_us: int
-    surgeon: str
-    protocol: str
-    surgery_notes: str
-    post_op_notes: str
-    surgery_quality: int = ...
-
-@dataclass
-class ImplantData:
-    """Stores the information about a single implantation procedure performed during the surgical intervention.
-
-    Multiple ImplantData instances are used at the same time if the surgery involved multiple implants.
-    """
-
-    implant: str
-    implant_target: str
-    implant_code: str
-    implant_ap_coordinate_mm: float
-    implant_ml_coordinate_mm: float
-    implant_dv_coordinate_mm: float
-
-@dataclass
-class InjectionData:
-    """Stores the information about a single injection performed during surgical intervention.
-
-    Multiple InjectionData instances are used at the same time if the surgery involved multiple injections.
-    """
-
-    injection: str
-    injection_target: str
-    injection_volume_nl: float
-    injection_code: str
-    injection_ap_coordinate_mm: float
-    injection_ml_coordinate_mm: float
-    injection_dv_coordinate_mm: float
-
-@dataclass
-class DrugData:
-    """Stores the information about all drugs administered to the subject before, during, and immediately after the
-    surgical intervention.
-    """
-
-    lactated_ringers_solution_volume_ml: float
-    lactated_ringers_solution_code: str
-    ketoprofen_volume_ml: float
-    ketoprofen_code: str
-    buprenorphine_volume_ml: float
-    buprenorphine_code: str
-    dexamethasone_volume_ml: float
-    dexamethasone_code: str
-
-@dataclass
-class SurgeryData(YamlConfig):
-    """Stores the data about a single animal surgical intervention.
-
-    This class aggregates other dataclass instances that store specific data about the surgical procedure. Primarily, it
-    is used to save the data as a .yaml file to every session's 'raw_data' directory of each animal used in every lab
-    project. This way, the surgery data is always stored alongside the behavior and brain activity data collected
-    during the session.
-    """
-
-    subject: SubjectData
-    procedure: ProcedureData
-    drugs: DrugData
-    implants: list[ImplantData]
-    injections: list[InjectionData]

sl_shared_assets/server/__init__.pyi

@@ -1,11 +0,0 @@
-from .job import (
-    Job as Job,
-    JupyterJob as JupyterJob,
-)
-from .server import (
-    Server as Server,
-    ServerCredentials as ServerCredentials,
-    generate_server_credentials as generate_server_credentials,
-)
-
-__all__ = ["Server", "ServerCredentials", "generate_server_credentials", "Job", "JupyterJob"]