sl-shared-assets 6.1.1__py3-none-any.whl

sl_shared_assets/data_classes/processing_data.py

@@ -0,0 +1,385 @@
+"""This module provides the assets for running data processing pipelines."""
+
+import os
+import copy
+from enum import IntEnum, StrEnum
+from pathlib import Path  # noqa: TC003
+from dataclasses import field, dataclass
+
+import xxhash
+from filelock import FileLock
+from ataraxis_base_utilities import console
+from ataraxis_data_structures import YamlConfig
+
+
+class ProcessingPipelines(StrEnum):
+    """Defines the data processing pipelines currently supported by the Sun lab data workflow."""
+
+    MANIFEST = "manifest"
+    """The project manifest generation pipeline. This pipeline generates a .feather file that stores the snapshot of the
+    target project's data processing state. The created manifest file is then used as the entry-point for all other
+    data processing pipelines other than the ADOPTION pipeline."""
+    ADOPTION = "adoption"
+    """The session data adoption pipeline. This pipeline copies session's data stored in the shared Sun lab
+    data directory on the remote compute server to the user's working directory. This is the entry-point for all
+    further interactions with the data, as it gives the calling user the permission to modify the copied data."""
+    CHECKSUM = "checksum"
+    """The session's raw data integrity checksum verification pipeline. This pipeline verifies or regenerates
+    the session's data integrity checksum."""
+    BEHAVIOR = "behavior"
+    """The behavior data processing pipeline. This pipeline parses the non-video behavior data from the .npz log
+    archives generated by the sl-experiment library during the session's data acquisition."""
+    VIDEO = "video"
+    """The video data processing pipeline. This pipeline identifies and extracts the animal's pose and movement data
+    from the frames recorded by behavior video cameras during the session's data acquisition."""
+    SUITE2P = "suite2p"
+    """The suite2p calcium imaging data processing pipeline. This pipeline motion-corrects, identifies, and extracts
+    the calcium fluorescence traces from cells recorded with 2-Photon Random Access Mesoscope (2P-RAM)
+    during the session's data acquisition."""
+    MULTIDAY = "multiday"
+    """The suite2p multi-day cell tracking pipeline. This pipeline uses the output of the 'suite2p' pipeline for each
+    of the processed sessions to identify and track the activity of stably present cells across days."""
+    FORGING = "forging"
+    """The dataset assembly (forging) pipeline. This pipeline integrates the single-day and multi-day data from all
+    available sources for each processed session into a unified analysis Dataset structure. The assembled
+    dataset then serves as an entry-point for all further data analysis tasks."""
+
+
+class ManagingTrackers(StrEnum):
+    """Defines the tracker files used by the data managing pipelines currently supported by the Sun lab data
+    workflow.
+    """
+
+    CHECKSUM = "checksum.yaml"
+    """The tracker file used by the checksum resolution pipeline."""
+    MANIFEST = "manifest.yaml"
+    """The tracker file used by the project manifest generation pipeline."""
+
+
+class ProcessingTrackers(StrEnum):
+    """Defines the tracker files used by data processing pipelines currently supported by the Sun lab data
+    workflow.
+    """
+
+    SUITE2P = "suite2p.yaml"
+    """The tracker file used by the suite2p processing pipeline."""
+    BEHAVIOR = "behavior.yaml"
+    """The tracker file used by the behavior extraction pipeline."""
+    VIDEO = "video.yaml"
+    """The tracker file used by the video (DeepLabCut) processing pipeline."""
+
+
+class DatasetTrackers(StrEnum):
+    """Defines the tracker files used by dataset forging pipelines currently supported by the Sun lab data
+    workflow.
+    """
+
+    FORGING = "forging.yaml"
+    """The tracker file used by the dataset forging pipeline."""
+    MULTIDAY = "multiday.yaml"
+    """The tracker file used by the multi-day suite2p registration pipeline."""
+
+
+class ProcessingStatus(IntEnum):
+    """Defines the status codes used by the ProcessingTracker instances to communicate the runtime state of each
+    job making up the managed data processing pipeline.
+    """
+
+    SCHEDULED = 0
+    """The job is scheduled for execution."""
+    RUNNING = 1
+    """The job is currently being executed."""
+    SUCCEEDED = 2
+    """The job has been completed."""
+    FAILED = 3
+    """The job encountered a runtime error and was not completed."""
+
+
+@dataclass
+class JobState:
+    """Stores the metadata and the current runtime status of a single job in the processing pipeline."""
+
+    status: ProcessingStatus = ProcessingStatus.SCHEDULED
+    """The current status of the job."""
+    slurm_job_id: int | None = None
+    """The SLURM-assigned job ID, if running on a SLURM cluster."""
+
+
+@dataclass()
+class ProcessingTracker(YamlConfig):
+    """Tracks the state of a data processing pipeline and provides tools for communicating this state between multiple
+    processes and host-machines.
+
+    Note:
+        All modifications to the tracker file require the acquisition of the .lock file, which ensures exclusive
+        access to the tracker's data, allowing multiple independent processes (jobs) to safely work with the same
+        tracker file.
+    """
+
+    file_path: Path
+    """The path to the .YAML file used to cache the tracker's data on disk."""
+    jobs: dict[str, JobState] = field(default_factory=dict)
+    """Maps the unique identifiers of the jobs that make up the processing pipeline to their current state and 
+    metadata."""
+    lock_path: str = field(init=False)
+    """The path to the .LOCK file used to ensure thread-safe access to the tracker's data."""
+
+    def __post_init__(self) -> None:
+        """Resolves the .LOCK file for the managed tracker .YAML file."""
+        # Generates the .lock file path for the target tracker .yaml file.
+        if self.file_path is not None:
+            self.lock_path = str(self.file_path.with_suffix(self.file_path.suffix + ".lock"))
+        else:
+            self.lock_path = ""
+
+        # Converts integer status values back to ProcessingStatus enumeration instances. The conversion to integers is
+        # necessary for .YAML saving compatibility.
+        for job_state in self.jobs.values():
+            if isinstance(job_state.status, int):
+                job_state.status = ProcessingStatus(job_state.status)
+
+    @staticmethod
+    def generate_job_id(session_path: Path, job_name: str) -> str:
+        """Generates a unique hexadecimal job identifier based on the session's data path and the job's name using the
+        xxHash64 checksum generator.
+
+        Args:
+            session_path: The path to the processed session's data directory.
+            job_name: The unique name for the processing job.
+
+        Returns:
+            The unique hexadecimal identifier for the target job.
+        """
+        # Combines session path and job name into a single string for hashing
+        combined = f"{session_path.resolve()}:{job_name}"
+        # Generates and returns the xxHash64 hash
+        return xxhash.xxh64(combined.encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def _get_slurm_job_id() -> int | None:
+        """Retrieves the SLURM-assigned job's ID from the environment, if available.
+
+        Returns:
+            The SLURM-assigned job's ID if running in a SLURM environment, None otherwise.
+        """
+        slurm_id = os.environ.get("SLURM_JOB_ID") or os.environ.get("SLURM_JOBID")
+        return int(slurm_id) if slurm_id else None
+
+    def _load_state(self) -> None:
+        """Reads the processing pipeline's runtime state from the cached .YAML file."""
+        if self.file_path.exists():
+            # Loads the data for the state values but does not replace the file path or lock attributes.
+            instance: ProcessingTracker = self.from_yaml(self.file_path)
+            self.jobs = copy.deepcopy(instance.jobs)
+        else:
+            # Otherwise, if the tracker file does not exist, generates a new .yaml file using default instance values
+            # and saves it to disk using the specified tracker file path.
+            self._save_state()
+
+    def _save_state(self) -> None:
+        """Caches the current processing state stored inside the instance's attributes as a.YAML file."""
+        # Resets the lock_path and file_path to None and jobs to a dictionary of integers before dumping the data to
+        # .YAML to avoid issues with loading it back.
+        temp_file_path, temp_lock_path, temp_jobs = self.file_path, self.lock_path, self.jobs
+
+        # Converts enums to int for YAML serialization
+        converted_jobs = {}
+        for job_id, job_state in self.jobs.items():
+            converted_jobs[job_id] = JobState(
+                status=int(job_state.status),  # type: ignore[arg-type]
+                slurm_job_id=job_state.slurm_job_id,
+            )
+
+        try:
+            self.file_path = None  # type: ignore[assignment]
+            self.lock_path = None  # type: ignore[assignment]
+            self.jobs = converted_jobs
+            self.to_yaml(file_path=temp_file_path)
+        finally:
+            self.file_path, self.lock_path, self.jobs = temp_file_path, temp_lock_path, temp_jobs
+
+    def initialize_jobs(self, job_ids: list[str]) -> None:
+        """Configures the tracker with the list of jobs to be executed during the pipeline's runtime.
+
+        Args:
+            job_ids: The list of unique identifiers for all jobs that make up the tracked pipeline.
+
+        Raises:
+            TimeoutError: If the .LOCK file for the tracker .YAML file cannot be acquired within the timeout period.
+        """
+        lock = FileLock(self.lock_path)
+        with lock.acquire(timeout=10.0):
+            # Loads tracker's state from the .yaml file
+            self._load_state()
+
+            # Initialize all jobs as SCHEDULED if they don't already exist
+            for job_id in job_ids:
+                if job_id not in self.jobs:
+                    self.jobs[job_id] = JobState(status=ProcessingStatus.SCHEDULED)
+
+            self._save_state()
+
+    def start_job(self, job_id: str) -> None:
+        """Marks the target job as running and captures the SLURM-assigned job's ID from the environment, if called
+        under the SLURM job manager.
+
+        Args:
+            job_id: The unique identifier of the job mark as started.
+
+        Raises:
+            TimeoutError: If the .LOCK file for the tracker .YAML file cannot be acquired within the timeout period.
+            ValueError: If the specified job ID is not found in the managed tracker file.
+        """
+        lock = FileLock(self.lock_path)
+        with lock.acquire(timeout=10.0):
+            # Loads tracker state from the .yaml file
+            self._load_state()
+
+            # Verifies that the tracker is configured to track the specified job
+            if job_id not in self.jobs:
+                message = (
+                    f"The ProcessingTracker instance is not configured to track the state of the job with ID "
+                    f"'{job_id}'. The instance is currently configured to track jobs with IDs: "
+                    f"{', '.join(self.jobs.keys())}."
+                )
+                console.error(message=message, error=ValueError)
+                # Fallback to appease mypy, should not be reachable
+                raise ValueError(message)  # pragma: no cover
+
+            # Updates job status and captures the SLURM-assigned job ID
+            job_info = self.jobs[job_id]
+            job_info.status = ProcessingStatus.RUNNING
+            job_info.slurm_job_id = self._get_slurm_job_id()
+
+            self._save_state()
+
+    def complete_job(self, job_id: str) -> None:
+        """Marks a target job as successfully completed.
+
+        Args:
+            job_id: The unique identifier of the job to mark as complete.
+
+        Raises:
+            TimeoutError: If the .LOCK file for the tracker .YAML file cannot be acquired within the timeout period.
+            ValueError: If the specified job ID is not found in the managed tracker file.
+        """
+        lock = FileLock(self.lock_path)
+        with lock.acquire(timeout=10.0):
+            # Loads tracker state from the .yaml file
+            self._load_state()
+
+            # Verifies that the tracker is configured to track the specified job
+            if job_id not in self.jobs:
+                message = (
+                    f"The ProcessingTracker instance is not configured to track the state of the job with ID "
+                    f"'{job_id}'. The instance is currently configured to track jobs with IDs: "
+                    f"{', '.join(self.jobs.keys())}."
+                )
+                console.error(message=message, error=ValueError)
+                # Fallback to appease mypy, should not be reachable
+                raise ValueError(message)  # pragma: no cover
+
+            # Updates the job's status.
+            job_info = self.jobs[job_id]
+            job_info.status = ProcessingStatus.SUCCEEDED
+
+            self._save_state()
+
+    def fail_job(self, job_id: str) -> None:
+        """Marks the target job as failed.
+
+        Args:
+            job_id: The unique identifier of the job to mark as failed.
+
+        Raises:
+            TimeoutError: If the .LOCK file for the tracker .YAML file cannot be acquired within the timeout period.
+            ValueError: If the specified job ID is not found in the managed tracker file.
+        """
+        lock = FileLock(self.lock_path)
+        with lock.acquire(timeout=10.0):
+            # Loads tracker state from the .yaml file
+            self._load_state()
+
+            # Verifies that the tracker is configured to track the specified job
+            if job_id not in self.jobs:
+                message = (
+                    f"The ProcessingTracker instance is not configured to track the state of the job with ID "
+                    f"'{job_id}'. The instance is currently configured to track jobs with IDs: "
+                    f"{', '.join(self.jobs.keys())}."
+                )
+                console.error(message=message, error=ValueError)
+                # Fallback to appease mypy, should not be reachable
+                raise ValueError(message)  # pragma: no cover
+
+            # Updates the job's status.
+            job_info = self.jobs[job_id]
+            job_info.status = ProcessingStatus.FAILED
+
+            self._save_state()
+
+    def get_job_status(self, job_id: str) -> ProcessingStatus:
+        """Queries the current runtime status of the target job.
+
+        Args:
+            job_id: The unique identifier of the job for which to query the runtime status.
+
+        Returns:
+            The current runtime status of the job.
+
+        Raises:
+            TimeoutError: If the .LOCK file for the tracker .YAML file cannot be acquired within the timeout period.
+            ValueError: If the specified job ID is not found in the managed tracker file.
+        """
+        lock = FileLock(self.lock_path)
+        with lock.acquire(timeout=10.0):
+            self._load_state()
+
+            # Verifies that the tracker is configured to track the specified job
+            if job_id not in self.jobs:
+                message = (
+                    f"The ProcessingTracker instance is not configured to track the state of the job with ID "
+                    f"'{job_id}'. The instance is currently configured to track jobs with IDs: "
+                    f"{', '.join(self.jobs.keys())}."
+                )
+                console.error(message=message, error=ValueError)
+                # Fallback to appease mypy, should not be reachable
+                raise ValueError(message)  # pragma: no cover
+
+            return self.jobs[job_id].status
+
+    def reset(self) -> None:
+        """Resets the tracker file to the default state."""
+        lock = FileLock(self.lock_path)
+        with lock.acquire(timeout=10.0):
+            # Loads tracker state from the .yaml file.
+            self._load_state()
+
+            # Resets the tracker file to the default state.
+            self.jobs.clear()
+            self._save_state()
+
+    @property
+    def complete(self) -> bool:
+        """Returns True if the tracked processing pipeline has been completed successfully.
+
+        Notes:
+            The pipeline is considered complete if all jobs have been marked as succeeded.
+        """
+        lock = FileLock(self.lock_path)
+        with lock.acquire(timeout=10.0):
+            self._load_state()
+            if not self.jobs:
+                return False
+            return all(job.status == ProcessingStatus.SUCCEEDED for job in self.jobs.values())
+
+    @property
+    def encountered_error(self) -> bool:
+        """Returns True if the tracked processing pipeline has been terminated due to a runtime error.
+
+        Note:
+            The pipeline is considered to have encountered an error if any job has been marked as failed.
+        """
+        lock = FileLock(self.lock_path)
+        with lock.acquire(timeout=10.0):
+            self._load_state()
+            return any(job.status == ProcessingStatus.FAILED for job in self.jobs.values())

sl_shared_assets/data_classes/runtime_data.py

@@ -0,0 +1,237 @@
+"""This module provides the assets used by data acquisition systems to store a subset of the acquired data."""
+
+from dataclasses import dataclass  # pragma: no cover
+
+from ataraxis_data_structures import YamlConfig  # pragma: no cover
+
+
+@dataclass()
+class MesoscopeHardwareState(YamlConfig):  # pragma: no cover
+    """Stores configuration parameters (states) of the Mesoscope-VR system hardware modules used during training or
+    experiment runtimes.
+
+    Notes:
+        All hardware parameters are stored using the appropriate datatypes and rounding methods that ensure
+        their complete equivalence to the values used by the data acquisition system during runtime.
+    """
+
+    cm_per_pulse: float | None = None
+    """The conversion factor used to translate encoder pulses into centimeters."""
+    maximum_brake_strength: float | None = None
+    """The braking torque, in Newton centimeters, applied by the brake to the edge of the running wheel when it is 
+    maximally engaged."""
+    minimum_brake_strength: float | None = None
+    """The braking torque, in Newton centimeters, applied by the brake to the edge of the running wheel when it is 
+    completely disengaged."""
+    lick_threshold: int | None = None
+    """Determines the threshold, in 12-bit Analog to Digital Converter (ADC) units reported by the lick sensor, for 
+    considering the reported signal a lick."""
+    valve_scale_coefficient: float | None = None
+    """The scale coefficient of the power law equation that describes the relationship between the time the valve is 
+    kept open and the dispensed water volume."""
+    valve_nonlinearity_exponent: float | None = None
+    """The nonlinearity exponent of the power law equation that describes the relationship between the time the valve 
+    is kept open and the dispensed water volume."""
+    torque_per_adc_unit: float | None = None
+    """The conversion factor used to translate torque values reported by the sensor as 12-bit Analog to Digital 
+    Converter (ADC) units into Newton centimeters (N·cm)."""
+    screens_initially_on: bool | None = None
+    """Stores the initial state of the Virtual Reality screens at the beginning of the session's runtime."""
+    recorded_mesoscope_ttl: bool | None = None
+    """Tracks whether the session recorded brain activity data with the mesoscope."""
+    delivered_gas_puffs: bool | None = None
+    """Tracks whether the session delivered any gas puffs to the animal."""
+    system_state_codes: dict[str, int] | None = None
+    """Maps integer state-codes used by the Mesoscope-VR system to communicate its states (system states) to
+    human-readable state names."""
+
+
+@dataclass()
+class LickTrainingDescriptor(YamlConfig):  # pragma: no cover
+    """Stores the task and outcome information specific to lick training sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    """The ID of the experimenter running the session."""
+    mouse_weight_g: float
+    """The weight of the animal, in grams, at the beginning of the session."""
+    minimum_reward_delay_s: int = 6
+    """The minimum delay, in seconds, that can separate the delivery of two consecutive water rewards."""
+    maximum_reward_delay_s: int = 18
+    """The maximum delay, in seconds, that can separate the delivery of two consecutive water rewards."""
+    maximum_water_volume_ml: float = 1.0
+    """The maximum volume of water the system is allowed to dispense during training."""
+    maximum_training_time_min: int = 20
+    """The maximum time, in minutes, the system is allowed to run the training."""
+    maximum_unconsumed_rewards: int = 1
+    """The maximum number of consecutive rewards that can be delivered without the animal consuming them. If 
+    the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal 
+    consumes the delivered rewards."""
+    water_reward_size_ul: float = 5.0
+    """The volume of water, in microliters, dispensed to the animal when it achieves the required running speed and 
+    duration thresholds."""
+    reward_tone_duration_ms: int = 300
+    """The duration, in milliseconds, of the auditory tone played to the animal when it receives water rewards."""
+    dispensed_water_volume_ml: float = 0.0
+    """The total water volume, in milliliters, dispensed during runtime. This excludes the water volume 
+    dispensed during the paused (idle) state."""
+    pause_dispensed_water_volume_ml: float = 0.0
+    """The total water volume, in milliliters, dispensed during the paused (idle) state."""
+    experimenter_given_water_volume_ml: float = 0.0
+    """The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.
+    """
+    preferred_session_water_volume_ml: float = 0.0
+    """The volume of water, in milliliters, the animal should be receiving during the session runtime if its 
+    performance matches experimenter-specified threshold."""
+    incomplete: bool = True
+    """Tracks whether the session's data is complete and eligible for unsupervised data processing."""
+    experimenter_notes: str = "Replace this with your notes."
+    """Stores the experimenter's notes made during runtime."""
+
+
+@dataclass()
+class RunTrainingDescriptor(YamlConfig):  # pragma: no cover
+    """Stores the task and outcome information specific to run training sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    """The ID of the experimenter running the session."""
+    mouse_weight_g: float
+    """The weight of the animal, in grams, at the beginning of the session."""
+    final_run_speed_threshold_cm_s: float = 1.5
+    """The running speed threshold, in centimeters per second, at the end of training."""
+    final_run_duration_threshold_s: float = 1.5
+    """The running duration threshold, in seconds, at the end of training."""
+    initial_run_speed_threshold_cm_s: float = 0.8
+    """The initial running speed threshold, in centimeters per second."""
+    initial_run_duration_threshold_s: float = 1.5
+    """The initial running duration threshold, in seconds."""
+    increase_threshold_ml: float = 0.1
+    """The threshold volume of water delivered to the animal, in milliliters, that triggers the increase in the running 
+    speed and duration thresholds."""
+    run_speed_increase_step_cm_s: float = 0.05
+    """The value, in centimeters per second, used by the system to increment the running speed threshold each
+    time the animal receives 'increase_threshold' volume of water."""
+    run_duration_increase_step_s: float = 0.1
+    """The value, in seconds, used by the system to increment the duration threshold each time the animal 
+    receives 'increase_threshold' volume of water."""
+    maximum_water_volume_ml: float = 1.0
+    """The maximum volume of water the system is allowed to dispense during training."""
+    maximum_training_time_min: int = 40
+    """The maximum time, in minutes, the system is allowed to run the training."""
+    maximum_unconsumed_rewards: int = 1
+    """The maximum number of consecutive rewards that can be delivered without the animal consuming them. If 
+    the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal 
+    consumes the delivered rewards."""
+    maximum_idle_time_s: float = 0.3
+    """The maximum time, in seconds, the animal can dip below the running speed threshold to still receive the 
+    reward. This allows animals that 'run' by taking a series of large steps, briefly dipping below speed threshold at 
+    the end of each step, to still get water rewards."""
+    water_reward_size_ul: float = 5.0
+    """The volume of water, in microliters, dispensed to the animal when it achieves the required running speed and 
+    duration thresholds."""
+    reward_tone_duration_ms: int = 300
+    """The duration, in milliseconds, of the auditory tone played to the animal when it receives water rewards."""
+    dispensed_water_volume_ml: float = 0.0
+    """The total water volume, in milliliters, dispensed during runtime. This excludes the water volume 
+    dispensed during the paused (idle) state."""
+    pause_dispensed_water_volume_ml: float = 0.0
+    """The total water volume, in milliliters, dispensed during the paused (idle) state."""
+    experimenter_given_water_volume_ml: float = 0.0
+    """The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.
+    """
+    preferred_session_water_volume_ml: float = 0.0
+    """The volume of water, in milliliters, the animal should be receiving during the session runtime if its 
+    performance matches experimenter-specified threshold."""
+    incomplete: bool = True
+    """Tracks whether the session's data is complete and eligible for unsupervised data processing."""
+    experimenter_notes: str = "Replace this with your notes."
+    """Stores the experimenter's notes made during runtime."""
+
+
+@dataclass()
+class MesoscopeExperimentDescriptor(YamlConfig):  # pragma: no cover
+    """Stores the task and outcome information specific to experiment sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    """The ID of the experimenter running the session."""
+    mouse_weight_g: float
+    """The weight of the animal, in grams, at the beginning of the session."""
+    maximum_unconsumed_rewards: int = 1
+    """The maximum number of consecutive rewards that can be delivered without the animal consuming them. If 
+    the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal 
+    consumes the delivered rewards."""
+    dispensed_water_volume_ml: float = 0.0
+    """The total water volume, in milliliters, dispensed during runtime. This excludes the water volume 
+    dispensed during the paused (idle) state."""
+    pause_dispensed_water_volume_ml: float = 0.0
+    """The total water volume, in milliliters, dispensed during the paused (idle) state."""
+    experimenter_given_water_volume_ml: float = 0.0
+    """The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.
+    """
+    preferred_session_water_volume_ml: float = 0.0
+    """The volume of water, in milliliters, the animal should be receiving during the session runtime if its 
+    performance matches experimenter-specified threshold."""
+    incomplete: bool = True
+    """Tracks whether the session's data is complete and eligible for unsupervised data processing."""
+    experimenter_notes: str = "Replace this with your notes."
+    """Stores the experimenter's notes made during runtime."""
+
+
+@dataclass()
+class WindowCheckingDescriptor(YamlConfig):  # pragma: no cover
+    """Stores the outcome information specific to window checking sessions that use the Mesoscope-VR system."""
+
+    experimenter: str
+    """The ID of the experimenter running the session."""
+    surgery_quality: int = 0
+    """The quality of the cranial window and surgical intervention on a scale from 0 (non-usable) to 
+    3 (high-tier publication grade) inclusive."""
+    incomplete: bool = True
+    """Tracks whether the session's data is complete and eligible for unsupervised data processing."""
+    experimenter_notes: str = "Replace this with your notes."
+    """Stores the experimenter's notes made during runtime."""
+
+
+@dataclass()
+class ZaberPositions(YamlConfig):  # pragma: no cover
+    """Stores Zaber motor positions reused between data acquisition sessions that use the Mesoscope-VR system."""
+
+    headbar_z: int = 0
+    """The absolute position, in native motor units, of the HeadBar z-axis motor."""
+    headbar_pitch: int = 0
+    """The absolute position, in native motor units, of the HeadBar pitch-axis motor."""
+    headbar_roll: int = 0
+    """The absolute position, in native motor units, of the HeadBar roll-axis motor."""
+    lickport_z: int = 0
+    """The absolute position, in native motor units, of the LickPort z-axis motor."""
+    lickport_y: int = 0
+    """The absolute position, in native motor units, of the LickPort y-axis motor."""
+    lickport_x: int = 0
+    """The absolute position, in native motor units, of the LickPort x-axis motor."""
+    wheel_x: int = 0
+    """The absolute position, in native motor units, of the running wheel platform x-axis motor."""
+
+
+@dataclass()
+class MesoscopePositions(YamlConfig):  # pragma: no cover
+    """Stores the positions of real and virtual Mesoscope imaging axes reused between experiment sessions that use the
+    Mesoscope-VR system.
+    """
+
+    mesoscope_x: float = 0.0
+    """The Mesoscope objective's X-axis position, in micrometers."""
+    mesoscope_y: float = 0.0
+    """The Mesoscope objective's Y-axis position, in micrometers."""
+    mesoscope_roll: float = 0.0
+    """The Mesoscope objective's Roll-axis position, in degrees."""
+    mesoscope_z: float = 0.0
+    """The Mesoscope objective's Z-axis position, in micrometers."""
+    mesoscope_fast_z: float = 0.0
+    """The ScanImage's FastZ (virtual Z-axis) position, in micrometers."""
+    mesoscope_tip: float = 0.0
+    """The ScanImage's Tilt position, in degrees.."""
+    mesoscope_tilt: float = 0.0
+    """The ScanImage's Tip position, in degrees."""
+    laser_power_mw: float = 0.0
+    """The laser excitation power at the sample, in milliwatts."""
+    red_dot_alignment_z: float = 0.0
+    """The Mesoscope objective's Z-axis position, in micrometers, used for the red-dot alignment procedure."""