sl-shared-assets 3.0.0rc14__py3-none-any.whl → 3.0.1__py3-none-any.whl

sl_shared_assets/cli.py

@@ -49,11 +49,11 @@ def verify_session_integrity(
     """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. if the session data
-    is intact, generates a 'verified.bin' marker file inside the session's raw_data folder.
+    that stores the data checksum generated before transferring the data to the 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. If the
+    session data is intact, it generates a 'verified.bin' marker file inside the session's raw_data folder.
 
     The command is also used by Sun lab data acquisition systems to generate the processed data hierarchy for each
     processed session. This use case is fully automated and should not be triggered manually by the user.
@@ -366,7 +366,7 @@ def start_jupyter_server(
     server = Server(credentials_path)
     job: JupyterJob | None = None
     try:
-        # If the caller did not provide an explicit notebook directory, defaults to user's working directory
+        # If the caller did not provide an explicit notebook directory, defaults to the user's working directory
         if directory is None:
             directory = (server.user_working_root,)
 
@@ -394,7 +394,7 @@ def start_jupyter_server(
         if job is not None:
             server.abort_job(job)
 
-        # Closes server connection if it is still open
+        # Closes the server connection if it is still open
         server.close()
 
 
@@ -446,10 +446,6 @@ def resolve_dataset_marker(
     processing pipelines are not allowed to work with the session data, ensuring that all processed data remains
     unchanged. If the marker does not exist, dataset integration pipelines are not allowed to work with the session
     data, enabling processing pipelines to safely modify the data at any time.
-
-    This command is automatically called at the end of each processing runtime to automatically transfer processed
-    sessions to the dataset integration step by creating the p53.bin marker. In contrast, removing the marker can only
-    be done manually.
     """
     resolve_p53_marker(
         session_path=session_path,

sl_shared_assets/cli.pyi

@@ -22,11 +22,11 @@ def verify_session_integrity(
     """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. if the session data
-    is intact, generates a 'verified.bin' marker file inside the session's raw_data folder.
+    that stores the data checksum generated before transferring the data to the 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. If the
+    session data is intact, it generates a 'verified.bin' marker file inside the session's raw_data folder.
 
     The command is also used by Sun lab data acquisition systems to generate the processed data hierarchy for each
     processed session. This use case is fully automated and should not be triggered manually by the user.
@@ -94,8 +94,4 @@ def resolve_dataset_marker(
     processing pipelines are not allowed to work with the session data, ensuring that all processed data remains
     unchanged. If the marker does not exist, dataset integration pipelines are not allowed to work with the session
     data, enabling processing pipelines to safely modify the data at any time.
-
-    This command is automatically called at the end of each processing runtime to automatically transfer processed
-    sessions to the dataset integration step by creating the p53.bin marker. In contrast, removing the marker can only
-    be done manually.
     """

sl_shared_assets/data_classes/__init__.py

@@ -1,7 +1,7 @@
 """This package provides the classes used to store data acquired at various stages of the data workflow and to
 configure various pipelines used in the Sun lab. These classes are used across all stages of data acquisition,
-preprocessing, and processing in the lab that run on multiple machines (PCs). Many classes in this package are designed
-to be saved to disk as .yaml files and restored from the .yaml files as needed."""
+preprocessing, and processing in the lab. Many classes in this package are designed to be saved to disk as .yaml files
+and restored from the .yaml files as needed."""
 
 from .runtime_data import (
     ZaberPositions,

sl_shared_assets/data_classes/configuration_data.py

@@ -24,10 +24,10 @@ class AcquisitionSystems(StrEnum):
 class ExperimentState:
     """Encapsulates the information used to set and maintain the desired experiment and system state.
 
-    Broadly, each experiment runtime can be conceptualized as a two state-system. The first is the experiment task,
+    Broadly, each experiment runtime can be conceptualized as a two-state-system. The first is the experiment task,
     which reflects the behavior goal, the rules for achieving the goal, and the reward for achieving the goal. The
     second is the data acquisition system state, which is a snapshot of all hardware module states that make up the
-    system that acquires the data and controls the task environment. Overall, experiment state is about
+    system that acquires the data and controls the task environment. Overall, the experiment state is about
     'what the animal is doing', while the system state is about 'what the hardware is doing'.
 
     Note:
@@ -96,16 +96,16 @@ class ExperimentTrial:
 class MesoscopeExperimentConfiguration(YamlConfig):
     """Stores the configuration of a single experiment runtime that uses the Mesoscope_VR data acquisition system.
 
-    Primarily, this includes the sequence of experiment and system states that defines the flow of the experiment
+    Primarily, this includes the sequence of experiment and system states that define the flow of the experiment
     runtime and the configuration of various trials supported by 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
+    order specified by the user. Together with custom Unity projects, which 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 using the Mesoscope-VR system.
 
     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-experiment' CLI command exposed by the sl-experiment library is executed.
+    the experiment configuration when the 'sl-experiment' CLI command exposed by the sl-experiment library is executed.
 
     Notes:
         This class is designed exclusively for the Mesoscope-VR system. Any other system needs to define a separate
@@ -126,6 +126,9 @@ class MesoscopeExperimentConfiguration(YamlConfig):
     track. This offset statically shifts the entire track (in centimeters) against the set of VR wall cues used during 
     runtime. Storing this static offset as part of experiment configuration is crucial for correctly mapping what the 
     animal sees during runtime to the real-world distance it travels on the running wheel."""
+    unity_scene_name: str = "IvanScene"
+    """The name of the Virtual Reality task (Unity Scene) used during experiment. This is used as an extra security 
+    measure to ensure that Unity game engine is running the correct scene when starting the experiment runtime."""
     experiment_states: dict[str, ExperimentState] = field(
         default_factory=lambda: {
             "baseline": ExperimentState(
@@ -415,7 +418,7 @@ class MesoscopeSystemConfiguration(YamlConfig):
         self.paths.mesoscope_directory = Path(self.paths.mesoscope_directory)
         self.paths.harvesters_cti_path = Path(self.paths.harvesters_cti_path)
 
-        # Converts valve_calibration data from dictionary to a tuple of tuples format
+        # Converts valve_calibration data from a dictionary to a tuple of tuples format
         if not isinstance(self.microcontrollers.valve_calibration_data, tuple):
             self.microcontrollers.valve_calibration_data = tuple(
                 (k, v) for k, v in self.microcontrollers.valve_calibration_data.items()
@@ -483,7 +486,7 @@ def set_system_configuration_file(path: Path) -> None:
     the managed machine (PC).
 
     This function is used to initially configure or override the existing configuration of any data acquisition system
-    used in the lab. The path to the configuration file is stored inside the user's data directory, so that all
+    used in the lab. The path to the configuration file is stored inside the user's data directory so that all
     Sun lab libraries can automatically access that information during every runtime. Since the storage directory is
     typically hidden and varies between OSes and machines, this function provides a convenient way for setting that
     path without manually editing the storage cache.

sl_shared_assets/data_classes/configuration_data.pyi

@@ -14,10 +14,10 @@ class AcquisitionSystems(StrEnum):
 class ExperimentState:
     """Encapsulates the information used to set and maintain the desired experiment and system state.
 
-    Broadly, each experiment runtime can be conceptualized as a two state-system. The first is the experiment task,
+    Broadly, each experiment runtime can be conceptualized as a two-state-system. The first is the experiment task,
     which reflects the behavior goal, the rules for achieving the goal, and the reward for achieving the goal. The
     second is the data acquisition system state, which is a snapshot of all hardware module states that make up the
-    system that acquires the data and controls the task environment. Overall, experiment state is about
+    system that acquires the data and controls the task environment. Overall, the experiment state is about
     'what the animal is doing', while the system state is about 'what the hardware is doing'.
 
     Note:
@@ -53,16 +53,16 @@ class ExperimentTrial:
 class MesoscopeExperimentConfiguration(YamlConfig):
     """Stores the configuration of a single experiment runtime that uses the Mesoscope_VR data acquisition system.
 
-    Primarily, this includes the sequence of experiment and system states that defines the flow of the experiment
+    Primarily, this includes the sequence of experiment and system states that define the flow of the experiment
     runtime and the configuration of various trials supported by 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
+    order specified by the user. Together with custom Unity projects, which 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 using the Mesoscope-VR system.
 
     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-experiment' CLI command exposed by the sl-experiment library is executed.
+    the experiment configuration when the 'sl-experiment' CLI command exposed by the sl-experiment library is executed.
 
     Notes:
         This class is designed exclusively for the Mesoscope-VR system. Any other system needs to define a separate
@@ -73,6 +73,7 @@ class MesoscopeExperimentConfiguration(YamlConfig):
 
     cue_map: dict[int, float] = field(default_factory=Incomplete)
     cue_offset_cm: float = ...
+    unity_scene_name: str = ...
     experiment_states: dict[str, ExperimentState] = field(default_factory=Incomplete)
     trial_structures: dict[str, ExperimentTrial] = field(default_factory=Incomplete)
 
@@ -197,7 +198,7 @@ def set_system_configuration_file(path: Path) -> None:
     the managed machine (PC).
 
     This function is used to initially configure or override the existing configuration of any data acquisition system
-    used in the lab. The path to the configuration file is stored inside the user's data directory, so that all
+    used in the lab. The path to the configuration file is stored inside the user's data directory so that all
     Sun lab libraries can automatically access that information during every runtime. Since the storage directory is
     typically hidden and varies between OSes and machines, this function provides a convenient way for setting that
     path without manually editing the storage cache.

sl_shared_assets/data_classes/runtime_data.py

@@ -35,7 +35,7 @@ class MesoscopeHardwareState(YamlConfig):
         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 _MesoscopeVRSystem class from sl-experiment library to facilitate
+        This class is automatically configured by _MesoscopeVRSystem class from the sl-experiment library to facilitate
         proper log parsing.
     """
 
@@ -200,7 +200,7 @@ class WindowCheckingDescriptor(YamlConfig):
 
     Notes:
         Window Checking sessions are different from all other sessions. Unlike other sessions, their purpose is not to
-        generate data, but rather to assess the suitability of the particular animal to be included in training and
+        generate data but rather to assess the suitability of the particular animal to be included in training and
         experiment cohorts. These sessions are automatically excluded from any automated data processing and analysis.
     """
 

sl_shared_assets/data_classes/runtime_data.pyi

@@ -28,7 +28,7 @@ class MesoscopeHardwareState(YamlConfig):
         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 _MesoscopeVRSystem class from sl-experiment library to facilitate
+        This class is automatically configured by _MesoscopeVRSystem class from the sl-experiment library to facilitate
         proper log parsing.
     """
 
@@ -102,7 +102,7 @@ class WindowCheckingDescriptor(YamlConfig):
 
     Notes:
         Window Checking sessions are different from all other sessions. Unlike other sessions, their purpose is not to
-        generate data, but rather to assess the suitability of the particular animal to be included in training and
+        generate data but rather to assess the suitability of the particular animal to be included in training and
         experiment cohorts. These sessions are automatically excluded from any automated data processing and analysis.
     """
 

sl_shared_assets/data_classes/session_data.py

@@ -29,7 +29,7 @@ class SessionTypes(StrEnum):
 
     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
+        support different session types and may not be suited for acquiring some of the session types listed in this
         enumeration.
     """
 
@@ -288,7 +288,7 @@ class SessionData(YamlConfig):
     name. If the session is not an experiment session, this field should be left as Null (None)."""
     python_version: str = "3.11.13"
     """Stores the Python version that was used to acquire session data."""
-    sl_experiment_version: str = "2.0.0"
+    sl_experiment_version: str = "3.0.0"
     """Stores the version of the sl-experiment library that was used to acquire the session data."""
     raw_data: RawData = field(default_factory=lambda: RawData())
     """Stores absolute paths to all directories and files that jointly make the session's raw data hierarchy. This 
@@ -405,7 +405,7 @@ class SessionData(YamlConfig):
         raw_data.resolve_paths(root_directory_path=session_path.joinpath("raw_data"))
         raw_data.make_directories()  # Generates the local 'raw_data' directory tree
 
-        # Resolves, but does not make processed_data directories. All runtimes that require access to 'processed_data'
+        # Resolves but does not make processed_data directories. All runtimes that require access to 'processed_data'
         # are configured to generate those directories if necessary, so there is no need to make them here.
         processed_data = ProcessedData()
         processed_data.resolve_paths(root_directory_path=session_path.joinpath("processed_data"))
@@ -425,18 +425,18 @@ class SessionData(YamlConfig):
             sl_experiment_version=sl_experiment_version,
         )
 
-        # Saves the configured instance data to the session's folder, so that it can be reused during processing or
+        # Saves the configured instance data to the session's folder so that it can be reused during processing or
         # preprocessing.
         instance._save()
 
         # Also saves the SystemConfiguration and ExperimentConfiguration instances to the same folder using the paths
         # resolved for the RawData instance above.
 
-        # Dumps the acquisition system's configuration data to session's folder
+        # Dumps the acquisition system's configuration data to the session's folder
         acquisition_system.save(path=instance.raw_data.system_configuration_path)
 
         if experiment_name is not None:
-            # Copies the experiment_configuration.yaml file to session's folder
+            # Copies the experiment_configuration.yaml file to the session's folder
             experiment_configuration_path = acquisition_system.paths.root_directory.joinpath(
                 project_name, "configuration", f"{experiment_name}.yaml"
             )
@@ -473,8 +473,8 @@ class SessionData(YamlConfig):
                 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 processed_data directory if it
-                does not exist.
+            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.
@@ -484,7 +484,7 @@ class SessionData(YamlConfig):
 
         """
         # To properly initialize the SessionData instance, the provided path should contain the raw_data directory
-        # with session_data.yaml file.
+        # with the session_data.yaml file.
         session_data_path = session_path.joinpath("raw_data", "session_data.yaml")
         if not session_data_path.exists():
             message = (
@@ -495,7 +495,7 @@ class SessionData(YamlConfig):
             )
             console.error(message=message, error=FileNotFoundError)
 
-        # Loads class data from .yaml file
+        # Loads class data from the .yaml file
         instance: SessionData = cls.from_yaml(file_path=session_data_path)  # type: ignore
 
         # The method assumes that the 'donor' .yaml file is always stored inside the raw_data directory of the session
@@ -538,7 +538,7 @@ class SessionData(YamlConfig):
     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
+        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.
         """
@@ -547,9 +547,9 @@ class SessionData(YamlConfig):
         # processing
         origin = copy.deepcopy(self)
 
-        # Resets all path fields to null. These fields are not loaded from disk when the instance is loaded, so setting
-        # them to null has no negative consequences. Conversely, keeping these fields with Path objects prevents the
-        # SessionData instance from being loaded from disk.
+        # Resets all path fields to null. These fields are not loaded from the disk when the instance is loaded, so
+        # setting them to null has no negative consequences. Conversely, keeping these fields with Path objects
+        # prevents the SessionData instance from being loaded from the disk.
         origin.raw_data = None  # type: ignore
         origin.processed_data = None  # type: ignore
 
@@ -585,6 +585,10 @@ class ProcessingTracker(YamlConfig):
     _lock_path: str = field(init=False)
     """Stores the path to the .lock file for the target tracker .yaml file. This file is used to ensure that only one 
     process can simultaneously read from or write to the wrapped .yaml file."""
+    _started_runtime: bool = False
+    """This internal service field tracks when the class instance is used to start a runtime. It is set automatically by
+    the ProcessingTracker instance and is used to prevent runtime errors from deadlocking the specific processing 
+    pipeline tracked by the class instance."""
 
     def __post_init__(self) -> None:
         # Generates the lock file for the target .yaml file path.
@@ -594,19 +598,18 @@ class ProcessingTracker(YamlConfig):
             self._lock_path = ""
 
     def __del__(self) -> None:
-        """If the instance is garbage-collected without calling the stop() method, assumes this is due to a runtime
-        error.
+        """If the instance as used to start a runtime, ensures that the instance properly marks the runtime as completed
+        or erred before being garbage-collected.
 
-        It is essential to always resolve the runtime as either 'stopped' or 'erred' to avoid deadlocking the session
-        data.
+        This is a security mechanism to prevent deadlocking the processed session and pipeline for future runtimes.
         """
-        if self._is_running:
+        if self._started_runtime and self._is_running:
             self.error()
 
     def _load_state(self) -> None:
         """Reads the current processing state from the wrapped .YAML file."""
         if self.file_path.exists():
-            # Loads the data for the state values, but does not replace the file path or lock attributes.
+            # 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)  # type: ignore
             self._is_complete = instance._is_complete
             self._encountered_error = instance._encountered_error
@@ -622,6 +625,7 @@ class ProcessingTracker(YamlConfig):
         original = copy.deepcopy(self)
         original.file_path = None  # type: ignore
         original._lock_path = None  # type: ignore
+        original._started_runtime = False  # This field is only used by the instance stored in memory.
         original.to_yaml(file_path=self.file_path)
 
     def start(self) -> None:
@@ -631,13 +635,13 @@ class ProcessingTracker(YamlConfig):
         with an error.
 
         Raises:
-            TimeoutError: If the file lock for the target .YAML file cannot be acquired within the timeout period.
+            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
         """
         try:
             # Acquires the lock
             lock = FileLock(self._lock_path)
             with lock.acquire(timeout=10.0):
-                # Loads tracker state from .yaml file
+                # Loads tracker state from the .yaml file
                 self._load_state()
 
                 # If the runtime is already running, aborts with an error
@@ -656,6 +660,10 @@ class ProcessingTracker(YamlConfig):
                 self._encountered_error = False
                 self._save_state()
 
+                # Sets the start tracker flag to True, which ensures that the class tries to mark the runtime as
+                # completed or erred before it being garbage-collected.
+                self._started_runtime = True
+
         # If lock acquisition fails for any reason, aborts with an error
         except Timeout:
             message = (
@@ -676,14 +684,14 @@ class ProcessingTracker(YamlConfig):
         from the process that calls this method.
 
         Raises:
-            TimeoutError: If the file lock for the target .YAML file cannot be acquired within the timeout period.
+            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
         """
 
         try:
             # Acquires the lock
             lock = FileLock(self._lock_path)
             with lock.acquire(timeout=10.0):
-                # Loads tracker state from .yaml file
+                # Loads tracker state from the .yaml file
                 self._load_state()
 
                 # If the runtime is not running, aborts with an error
@@ -702,6 +710,9 @@ class ProcessingTracker(YamlConfig):
                 self._encountered_error = True
                 self._save_state()
 
+                # Disables the security flag
+                self._started_runtime = False
+
         # If lock acquisition fails for any reason, aborts with an error
         except Timeout:
             message = (
@@ -720,14 +731,14 @@ class ProcessingTracker(YamlConfig):
         at the end of the runtime.
 
         Raises:
-            TimeoutError: If the file lock for the target .YAML file cannot be acquired within the timeout period.
+            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
         """
 
         try:
             # Acquires the lock
             lock = FileLock(self._lock_path)
             with lock.acquire(timeout=10.0):
-                # Loads tracker state from .yaml file
+                # Loads tracker state from the .yaml file
                 self._load_state()
 
                 # If the runtime is not running, aborts with an error
@@ -746,6 +757,9 @@ class ProcessingTracker(YamlConfig):
                 self._encountered_error = False
                 self._save_state()
 
+                # Disables the security flag
+                self._started_runtime = False
+
         # If lock acquisition fails for any reason, aborts with an error
         except Timeout:
             message = (
@@ -764,7 +778,7 @@ class ProcessingTracker(YamlConfig):
             # Acquires the lock
             lock = FileLock(self._lock_path)
             with lock.acquire(timeout=10.0):
-                # Loads tracker state from .yaml file
+                # Loads tracker state from the .yaml file
                 self._load_state()
                 return self._is_complete
 
@@ -786,7 +800,7 @@ class ProcessingTracker(YamlConfig):
             # Acquires the lock
             lock = FileLock(self._lock_path)
             with lock.acquire(timeout=10.0):
-                # Loads tracker state from .yaml file
+                # Loads tracker state from the .yaml file
                 self._load_state()
                 return self._encountered_error
 
@@ -808,7 +822,7 @@ class ProcessingTracker(YamlConfig):
             # Acquires the lock
             lock = FileLock(self._lock_path)
             with lock.acquire(timeout=10.0):
-                # Loads tracker state from .yaml file
+                # Loads tracker state from the .yaml file
                 self._load_state()
                 return self._is_running
 

sl_shared_assets/data_classes/session_data.pyi

@@ -20,7 +20,7 @@ class SessionTypes(StrEnum):
 
     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
+        support different session types and may not be suited for acquiring some of the session types listed in this
         enumeration.
     """
 
@@ -206,8 +206,8 @@ class SessionData(YamlConfig):
                 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 processed_data directory if it
-                does not exist.
+            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.
@@ -226,7 +226,7 @@ class SessionData(YamlConfig):
     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
+        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.
         """
@@ -245,13 +245,13 @@ class ProcessingTracker(YamlConfig):
     _encountered_error: bool = ...
     _is_running: bool = ...
     _lock_path: str = field(init=False)
+    _started_runtime: bool = ...
     def __post_init__(self) -> None: ...
     def __del__(self) -> None:
-        """If the instance is garbage-collected without calling the stop() method, assumes this is due to a runtime
-        error.
+        """If the instance as used to start a runtime, ensures that the instance properly marks the runtime as completed
+        or erred before beign garbage-collected.
 
-        It is essential to always resolve the runtime as either 'stopped' or 'erred' to avoid deadlocking the session
-        data.
+        This is a security mechanism to prevent deadlocking the processed session and pipeline for future runtimes.
         """
     def _load_state(self) -> None:
         """Reads the current processing state from the wrapped .YAML file."""
@@ -264,7 +264,7 @@ class ProcessingTracker(YamlConfig):
         with an error.
 
         Raises:
-            TimeoutError: If the file lock for the target .YAML file cannot be acquired within the timeout period.
+            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
         """
     def error(self) -> None:
         """Configures the tracker file to indicate that the tracked processing runtime encountered an error and failed
@@ -276,7 +276,7 @@ class ProcessingTracker(YamlConfig):
         from the process that calls this method.
 
         Raises:
-            TimeoutError: If the file lock for the target .YAML file cannot be acquired within the timeout period.
+            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
         """
     def stop(self) -> None:
         """Configures the tracker file to indicate that the tracked processing runtime has been completed successfully.
@@ -286,7 +286,7 @@ class ProcessingTracker(YamlConfig):
         at the end of the runtime.
 
         Raises:
-            TimeoutError: If the file lock for the target .YAML file cannot be acquired within the timeout period.
+            TimeoutError: If the .lock file for the target .YAML file cannot be acquired within the timeout period.
         """
     @property
     def is_complete(self) -> bool:

sl_shared_assets/server/__init__.py

@@ -1,5 +1,5 @@
 """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
+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, JupyterJob

sl_shared_assets/server/job.py

@@ -1,6 +1,6 @@
 """This module provides the core Job class, used as the starting point for all SLURM-managed job executed on lab compute
 server(s). Specifically, the Job class acts as a wrapper around the SLURM configuration and specific logic of each
-job. During runtime, Server class interacts with input job objects to manage their transfer and execution on the
+job. During runtime, the Server class interacts with input job objects to manage their transfer and execution on the
 remote servers.
 
 Since version 3.0.0, this module also provides the specialized JupyterJob class used to launch remote Jupyter
@@ -97,8 +97,8 @@ class Job:
     Attributes:
         remote_script_path: Stores the path to the script file relative to the root of the remote server that runs the
             command.
-        job_id: Stores the unique job identifier assigned by the SLURM manager to this job, when it is accepted for
-            execution. This field initialized to None and is overwritten by the Server class that submits the job.
+        job_id: Stores the unique job identifier assigned by the SLURM manager to this job when it is accepted for
+            execution. This field is initialized to None and is overwritten by the Server class that submits the job.
         job_name: Stores the descriptive name of the SLURM job.
         _command: Stores the managed SLURM command object.
     """
@@ -174,7 +174,7 @@ class Job:
         # initialization would not work as expected.
         fixed_script_content = script_content.replace("\\$", "$")
 
-        # Returns the script content to caller as a string
+        # Returns the script content to the caller as a string
         return fixed_script_content
 
 
@@ -202,8 +202,8 @@ class JupyterJob(Job):
         conda_environment: The name of the conda environment to activate on the server before running the job logic. The
             environment should contain the necessary Python packages and CLIs to support running the job's logic. For
             Jupyter jobs, this necessarily includes the Jupyter notebook and jupyterlab packages.
-        port: The connection port number for Jupyter server. Do not change the default value unless you know what you
-            are doing, as the server has most common communication ports closed for security reasons.
+        port: The connection port number for the Jupyter server. Do not change the default value unless you know what
+            you are doing, as the server has most common communication ports closed for security reasons.
         notebook_directory: The directory to use as Jupyter's root. During runtime, Jupyter will only have access to
             items stored in or under this directory. For most runtimes, this should be set to the user's root data or
             working directory.
@@ -270,7 +270,7 @@ class JupyterJob(Job):
         self._build_jupyter_command(jupyter_args)
 
     def _build_jupyter_command(self, jupyter_args: str) -> None:
-        """Builds the command to launch Jupyter notebook server on the remote Sun lab server."""
+        """Builds the command to launch the Jupyter notebook server on the remote Sun lab server."""
 
         # Gets the hostname of the compute node and caches it in the connection data file. Also caches the port name.
         self.add_command('echo "COMPUTE_NODE: $(hostname)" > {}'.format(self.connection_info_file))
@@ -297,7 +297,7 @@ class JupyterJob(Job):
         if jupyter_args:
             jupyter_cmd.append(jupyter_args)
 
-        # Adds resolved jupyter command to the list of job commands.
+        # Adds the resolved jupyter command to the list of job commands.
         jupyter_cmd_str = " ".join(jupyter_cmd)
         self.add_command(jupyter_cmd_str)
 
@@ -324,7 +324,7 @@ class JupyterJob(Job):
             message = f"Could not parse connection information file for the Jupyter server job with id {self.job_id}."
             console.error(message, ValueError)
 
-        # Stores extracted data inside connection_info attribute as a JupyterConnectionInfo instance.
+        # Stores extracted data inside the connection_info attribute as a JupyterConnectionInfo instance.
         self.connection_info = _JupyterConnectionInfo(
             compute_node=compute_node_match.group(1).strip(),  # type: ignore
             port=int(port_match.group(1)),  # type: ignore
@@ -352,7 +352,7 @@ class JupyterJob(Job):
             )
             return  # No connection information available, so does not proceed with printing.
 
-        # Prints generic connection details to terminal
+        # Prints generic connection details to the terminal
         console.echo(f"Jupyter is running on: {self.connection_info.compute_node}")
         console.echo(f"Port: {self.connection_info.port}")
         console.echo(f"Token: {self.connection_info.token}")