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

sl_shared_assets/{data_classes.pyi → data_classes/session_data.pyi}

@@ -4,6 +4,8 @@ from dataclasses import field, dataclass
 from _typeshed import Incomplete
 from ataraxis_data_structures import YamlConfig
 
+from .configuration_data import ExperimentConfiguration as ExperimentConfiguration
+
 def replace_root_path(path: Path) -> None:
     """Replaces the path to the local root directory used to store all Sun lab projects with the provided path.
 
@@ -252,7 +254,8 @@ class ProcessedData:
     mesoscope_data_path: Path = ...
     behavior_data_path: Path = ...
     job_logs_path: Path = ...
-    processing_tracker_path: Path = ...
+    project_configuration_path: Path = ...
+    session_data_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.
 
@@ -497,6 +500,10 @@ class SessionData(YamlConfig):
         Notes:
             To create a new session, use the create() method instead.
 
+            Although session_data.yaml is stored both inside raw_data and processed_data subfolders, this method
+            always searches only inside the raw_data folder. Storing session data in both folders is only used to ensure
+            human experimenters can always trace all data in the lab back to the proper project, animal, and session.
+
         Args:
             session_path: The path to the root directory of an existing session, e.g.: vrpc_root/project/animal/session.
             on_server: Determines whether the method is used to initialize an existing session on the BioHPC server or
@@ -511,289 +518,10 @@ class SessionData(YamlConfig):
             FileNotFoundError: If the 'session_data.yaml' file is not found under the session_path/raw_data/ subfolder.
         """
     def _save(self) -> None:
-        """Saves the instance data to the 'raw_data' directory of the managed session as a 'session_data.yaml' file.
+        """Saves the instance data to the 'raw_data' directory and the 'processed_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 preprocessing or
         data processing. The method is intended to only be used by the SessionData instance itself during its
         create() method runtime.
         """
-
-@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)
-
-@dataclass()
-class HardwareConfiguration(YamlConfig):
-    """This class is used to save the runtime hardware configuration parameters as a .yaml file.
-
-    This information is used to read and decode the data saved to the .npz log files during runtime as part of data
-    processing.
-
-    Notes:
-        All fields in this dataclass initialize to None. During log processing, any log associated with a hardware
-        module that provides the data stored in a field will be processed, unless that field is None. Therefore, setting
-        any field in this dataclass to None also functions as a flag for whether to parse the log associated with the
-        module that provides this field's information.
-
-        This class is automatically configured by MesoscopeExperiment and BehaviorTraining classes from sl-experiment
-        library to facilitate log parsing.
-    """
-
-    cue_map: dict[int, float] | None = ...
-    cm_per_pulse: float | None = ...
-    maximum_break_strength: float | None = ...
-    minimum_break_strength: float | None = ...
-    lick_threshold: int | None = ...
-    valve_scale_coefficient: float | None = ...
-    valve_nonlinearity_exponent: float | None = ...
-    torque_per_adc_unit: float | None = ...
-    screens_initially_on: bool | None = ...
-    recorded_mesoscope_ttl: bool | None = ...
-
-@dataclass()
-class LickTrainingDescriptor(YamlConfig):
-    """This class is used to save the description information specific to lick training sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    trained animal.
-    """
-
-    experimenter: str
-    mouse_weight_g: float
-    dispensed_water_volume_ml: float
-    minimum_reward_delay: int
-    maximum_reward_delay_s: int
-    maximum_water_volume_ml: float
-    maximum_training_time_m: int
-    experimenter_notes: str = ...
-    experimenter_given_water_volume_ml: float = ...
-
-@dataclass()
-class RunTrainingDescriptor(YamlConfig):
-    """This class is used to save the description information specific to run training sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    trained animal.
-    """
-
-    experimenter: str
-    mouse_weight_g: float
-    dispensed_water_volume_ml: float
-    final_run_speed_threshold_cm_s: float
-    final_run_duration_threshold_s: float
-    initial_run_speed_threshold_cm_s: float
-    initial_run_duration_threshold_s: float
-    increase_threshold_ml: float
-    run_speed_increase_step_cm_s: float
-    run_duration_increase_step_s: float
-    maximum_water_volume_ml: float
-    maximum_training_time_m: int
-    experimenter_notes: str = ...
-    experimenter_given_water_volume_ml: float = ...
-
-@dataclass()
-class MesoscopeExperimentDescriptor(YamlConfig):
-    """This class is used to save the description information specific to experiment sessions as a .yaml file.
-
-    The information stored in this class instance is filled in two steps. The main runtime function fills most fields
-    of the class, before it is saved as a .yaml file. After runtime, the experimenter manually fills leftover fields,
-    such as 'experimenter_notes,' before the class instance is transferred to the long-term storage destination.
-
-    The fully filled instance data is also used during preprocessing to write the water restriction log entry for the
-    animal participating in the experiment runtime.
-    """
-
-    experimenter: str
-    mouse_weight_g: float
-    dispensed_water_volume_ml: float
-    experimenter_notes: str = ...
-    experimenter_given_water_volume_ml: float = ...
-
-@dataclass()
-class ZaberPositions(YamlConfig):
-    """This class is used to save Zaber motor positions as a .yaml file to reuse them between sessions.
-
-    The class is specifically designed to store, save, and load the positions of the LickPort and HeadBar motors
-    (axes). It is used to both store Zaber motor positions for each session for future analysis and to restore the same
-    Zaber motor positions across consecutive runtimes for the same project and animal combination.
-
-    Notes:
-        All positions are saved using native motor units. All class fields initialize to default placeholders that are
-        likely NOT safe to apply to the VR system. Do not apply the positions loaded from the file unless you are
-        certain they are safe to use.
-
-        Exercise caution when working with Zaber motors. The motors are powerful enough to damage the surrounding
-        equipment and manipulated objects. Do not modify the data stored inside the .yaml file unless you know what you
-        are doing.
-    """
-
-    headbar_z: int = ...
-    headbar_pitch: int = ...
-    headbar_roll: int = ...
-    lickport_z: int = ...
-    lickport_x: int = ...
-    lickport_y: int = ...
-
-@dataclass()
-class MesoscopePositions(YamlConfig):
-    """This class is used to save the real and virtual Mesoscope objective positions as a .yaml file to reuse it
-    between experiment sessions.
-
-    Primarily, the class is used to help the experimenter to position the Mesoscope at the same position across
-    multiple imaging sessions. It stores both the physical (real) position of the objective along the motorized
-    X, Y, Z, and Roll axes and the virtual (ScanImage software) tip, tilt, and fastZ focus axes.
-
-    Notes:
-        Since the API to read and write these positions automatically is currently not available, this class relies on
-        the experimenter manually entering all positions and setting the mesoscope to these positions when necessary.
-    """
-
-    mesoscope_x_position: float = ...
-    mesoscope_y_position: float = ...
-    mesoscope_roll_position: float = ...
-    mesoscope_z_position: float = ...
-    mesoscope_fast_z_position: float = ...
-    mesoscope_tip_position: float = ...
-    mesoscope_tilt_position: float = ...
-
-@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 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: int
-    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: int
-    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: int
-    ketoprofen_volume_ml: float
-    ketoprofen_code: int
-    buprenorphine_volume_ml: float
-    buprenorphine_code: int
-    dexamethasone_volume_ml: float
-    dexamethasone_code: int
-
-@dataclass
-class SurgeryData(YamlConfig):
-    """Stores the data about a single mouse 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]
-
-@dataclass()
-class ProcessingTracker(YamlConfig):
-    """Tracks the data processing status for a single session.
-
-    This class is used during BioHPC-server data processing runtimes to track which processing steps are enabled and
-    have been successfully applied to a given session. This is used to optimize data processing and avoid unnecessary
-    processing step repetitions where possible.
-
-    Notes:
-        This class uses a similar mechanism for determining whether a particular option is enabled as the
-        HardwareConfiguration class. Specifically, if any field of the class is set to None (null), the processing
-        associated with that field is disabled. Otherwise, if the field is False, that session has not been processed
-        and, if True, the session has been processed.
-    """
-
-    checksum: bool | None = ...
-    log_extractions: bool | None = ...
-    suite2p: bool | None = ...
-    deeplabcut: bool | None = ...

sl_shared_assets/data_classes/surgery_data.py

@@ -0,0 +1,152 @@
+"""This module provides classes to store animal surgery data. This is used to store the data extracted from the Sun lab
+surgery log, so that subject surgery data is always kept together with training and experiment data."""
+
+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
+    """Stores the unique ID (name) of the subject. Assumes all animals are given a numeric ID, rather than a string 
+    name."""
+    ear_punch: str
+    """Stores the ear tag location of the subject."""
+    sex: str
+    """Stores the gender of the subject."""
+    genotype: str
+    """Stores the genotype of the subject."""
+    date_of_birth_us: int
+    """Stores the date of birth of the subject as the number of microseconds elapsed since UTC epoch onset."""
+    weight_g: float
+    """Stores the weight of the subject pre-surgery, in grams."""
+    cage: int
+    """Stores the number of the cage used to house the subject after surgery."""
+    location_housed: str
+    """Stores the location used to house the subject after the surgery."""
+    status: str
+    """Stores the current status of the subject (alive / deceased)."""
+
+
+@dataclass()
+class ProcedureData:
+    """Stores the general information about the surgical intervention."""
+
+    surgery_start_us: int
+    """Stores the date and time when the surgery has started as microseconds elapsed since UTC epoch onset."""
+    surgery_end_us: int
+    """Stores the date and time when the surgery has ended as microseconds elapsed since UTC epoch onset."""
+    surgeon: str
+    """Stores the name or ID of the surgeon. If the intervention was carried out by multiple surgeons, all participating
+    surgeon names and IDs are stored as part of the same string."""
+    protocol: str
+    """Stores the experiment protocol number (ID) used during the surgery."""
+    surgery_notes: str
+    """Stores surgeon's notes taken during the surgery."""
+    post_op_notes: str
+    """Stores surgeon's notes taken during the post-surgery recovery period."""
+    surgery_quality: int = 0
+    """Stores the quality of the surgical intervention as a numeric level. 0 indicates unusable (bad) result, 1 
+    indicates usable result that is not good enough to be included in a publication, 2 indicates publication-grade 
+    result."""
+
+
+@dataclass
+class ImplantData:
+    """Stores the information about a single implantation performed during the surgical intervention.
+
+    Multiple ImplantData instances are used at the same time if the surgery involved multiple implants.
+    """
+
+    implant: str
+    """The descriptive name of the implant."""
+    implant_target: str
+    """The name of the brain region or cranium section targeted by the implant."""
+    implant_code: int
+    """The manufacturer code or internal reference code for the implant. This code is used to identify the implant in 
+    additional datasheets and lab ordering documents."""
+    implant_ap_coordinate_mm: float
+    """Stores implant's antero-posterior stereotactic coordinate, in millimeters, relative to bregma."""
+    implant_ml_coordinate_mm: float
+    """Stores implant's medial-lateral stereotactic coordinate, in millimeters, relative to bregma."""
+    implant_dv_coordinate_mm: float
+    """Stores implant's dorsal-ventral stereotactic coordinate, in millimeters, relative to bregma."""
+
+
+@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
+    """The descriptive name of the injection."""
+    injection_target: str
+    """The name of the brain region targeted by the injection."""
+    injection_volume_nl: float
+    """The volume of substance, in nanoliters, delivered during the injection."""
+    injection_code: int
+    """The manufacturer code or internal reference code for the injected substance. This code is used to identify the 
+    substance in additional datasheets and lab ordering documents."""
+    injection_ap_coordinate_mm: float
+    """Stores injection's antero-posterior stereotactic coordinate, in millimeters, relative to bregma."""
+    injection_ml_coordinate_mm: float
+    """Stores injection's medial-lateral stereotactic coordinate, in millimeters, relative to bregma."""
+    injection_dv_coordinate_mm: float
+    """Stores injection's dorsal-ventral stereotactic coordinate, in millimeters, relative to bregma."""
+
+
+@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
+    """Stores the volume of Lactated Ringer's Solution (LRS) administered during surgery, in ml."""
+    lactated_ringers_solution_code: int
+    """Stores the manufacturer code or internal reference code for Lactated Ringer's Solution (LRS). This code is used 
+    to identify the LRS batch in additional datasheets and lab ordering documents."""
+    ketoprofen_volume_ml: float
+    """Stores the volume of ketoprofen diluted with saline administered during surgery, in ml."""
+    ketoprofen_code: int
+    """Stores the manufacturer code or internal reference code for ketoprofen. This code is used to identify the 
+    ketoprofen batch in additional datasheets and lab ordering documents."""
+    buprenorphine_volume_ml: float
+    """Stores the volume of buprenorphine diluted with saline administered during surgery, in ml."""
+    buprenorphine_code: int
+    """Stores the manufacturer code or internal reference code for buprenorphine. This code is used to identify the 
+    buprenorphine batch in additional datasheets and lab ordering documents."""
+    dexamethasone_volume_ml: float
+    """Stores the volume of dexamethasone diluted with saline administered during surgery, in ml."""
+    dexamethasone_code: int
+    """Stores the manufacturer code or internal reference code for dexamethasone. This code is used to identify the 
+    dexamethasone batch in additional datasheets and lab ordering documents."""
+
+
+@dataclass
+class SurgeryData(YamlConfig):
+    """Stores the data about a single mouse 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
+    """Stores the ID information about the subject (mouse)."""
+    procedure: ProcedureData
+    """Stores general data about the surgical intervention."""
+    drugs: DrugData
+    """Stores the data about the substances subcutaneously injected into the subject before, during and immediately 
+    after the surgical intervention."""
+    implants: list[ImplantData]
+    """Stores the data for all cranial and transcranial implants introduced to the subject during the surgical 
+    intervention."""
+    injections: list[InjectionData]
+    """Stores the data about all substances infused into the brain of the subject during the surgical intervention."""

sl_shared_assets/data_classes/surgery_data.pyi

@@ -0,0 +1,89 @@
+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 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: int
+    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: int
+    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: int
+    ketoprofen_volume_ml: float
+    ketoprofen_code: int
+    buprenorphine_volume_ml: float
+    buprenorphine_code: int
+    dexamethasone_volume_ml: float
+    dexamethasone_code: int
+
+@dataclass
+class SurgeryData(YamlConfig):
+    """Stores the data about a single mouse 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__.py

@@ -0,0 +1,8 @@
+"""This package provides the classes and methods used by all Sun lab libraries to submit remote jobs to the BioHPC
+and other compute servers. This package is also used across all Sun lab members private code to interface with the
+shared server."""
+
+from .job import Job
+from .server import Server, ServerCredentials, generate_server_credentials
+
+__all__ = ["Server", "ServerCredentials", "generate_server_credentials", "Job"]

sl_shared_assets/server/__init__.pyi

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