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

sl_shared_assets/data_classes/runtime_data.pyi

@@ -0,0 +1,145 @@
+from dataclasses import dataclass
+
+from ataraxis_data_structures import YamlConfig
+
+@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 = ...