sl-shared-assets 1.2.0rc2__py3-none-any.whl → 1.2.0rc4__py3-none-any.whl

sl_shared_assets/cli.py

@@ -226,6 +226,26 @@ def generate_system_configuration_file(output_directory: str, acquisition_system
     required=True,
     help="The password to use for server authentication.",
 )
+@click.option(
+    "-rdp",
+    "--raw_data_path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    required=True,
+    help=(
+        "The absolute path to the directory used to store raw data from all Sun lab projects, relative to the server "
+        "root."
+    ),
+)
+@click.option(
+    "-pdp",
+    "--processed_data_path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    required=True,
+    help=(
+        "The absolute path to the directory used to store processed data from all Sun lab projects, relative to the "
+        "server root."
+    ),
+)
 def generate_server_credentials_file(output_directory: str, host: str, username: str, password: str) -> None:
     """Generates a new server_credentials.yaml file under the specified directory, using input information.
 

sl_shared_assets/data_classes/configuration_data.py

@@ -111,12 +111,6 @@ class MesoscopePaths:
     sharing protocol, such as SMB."""
     harvesters_cti_path: Path = Path("/opt/mvIMPACT_Acquire/lib/x86_64/mvGenTLProducer.cti")
     """The path to the GeniCam CTI file used to connect to Harvesters-managed cameras."""
-    server_processed_data_root: Path = Path("/workdir/sun_data")
-    """The absolute path to the BioHPC server directory used to store the processed data from all Sun lab projects. 
-    This path is relative to the server root and is only used when submitting remote jobs to the server."""
-    server_raw_data_root: Path = Path("/storage/sun_data")
-    """The absolute path to the BioHPC server directory used to store the raw data from all Sun lab projects. 
-    This path is relative to the server root and is only used when submitting remote jobs to the server."""
 
 
 @dataclass()
@@ -304,8 +298,6 @@ class MesoscopeSystemConfiguration(YamlConfig):
         self.paths.nas_directory = Path(self.paths.nas_directory)
         self.paths.mesoscope_directory = Path(self.paths.mesoscope_directory)
         self.paths.harvesters_cti_path = Path(self.paths.harvesters_cti_path)
-        self.paths.server_processed_data_root = Path(self.paths.server_processed_data_root)
-        self.paths.server_raw_data_root = Path(self.paths.server_raw_data_root)
 
         # Converts valve_calibration data from dictionary to a tuple of tuples format
         if not isinstance(self.microcontrollers.valve_calibration_data, tuple):
@@ -354,8 +346,6 @@ class MesoscopeSystemConfiguration(YamlConfig):
         original.paths.nas_directory = str(original.paths.nas_directory)  # type: ignore
         original.paths.mesoscope_directory = str(original.paths.mesoscope_directory)  # type: ignore
         original.paths.harvesters_cti_path = str(original.paths.harvesters_cti_path)  # type: ignore
-        original.paths.server_processed_data_root = str(original.paths.server_processed_data_root)  # type: ignore
-        original.paths.server_raw_data_root = str(original.paths.server_raw_data_root)  # type: ignore
 
         # Converts valve calibration data into dictionary format
         if isinstance(original.microcontrollers.valve_calibration_data, tuple):

sl_shared_assets/data_classes/configuration_data.pyi

@@ -58,8 +58,6 @@ class MesoscopePaths:
     nas_directory: Path = ...
     mesoscope_directory: Path = ...
     harvesters_cti_path: Path = ...
-    server_processed_data_root: Path = ...
-    server_raw_data_root: Path = ...
 
 @dataclass()
 class MesoscopeCameras:

sl_shared_assets/data_classes/runtime_data.py

@@ -171,9 +171,6 @@ class MesoscopeExperimentDescriptor(YamlConfig):
     """The weight of the animal, in grams, at the beginning of the session."""
     dispensed_water_volume_ml: float
     """Stores the total water volume, in milliliters, dispensed during runtime."""
-    is_guided: bool = False
-    """Determines whether the animal has to lick in the reward zone to receive water rewards. If this is set to False, 
-    the system automatically dispenses water when the animal enters the reward zone."""
     experimenter_notes: str = "Replace this with your notes."
     """This field is not set during runtime. It is expected that each experimenter will replace this field with their 
     notes made during runtime."""

sl_shared_assets/data_classes/runtime_data.pyi

@@ -88,7 +88,6 @@ class MesoscopeExperimentDescriptor(YamlConfig):
     experimenter: str
     mouse_weight_g: float
     dispensed_water_volume_ml: float
-    is_guided: bool = ...
     experimenter_notes: str = ...
     experimenter_given_water_volume_ml: float = ...
     incomplete: bool = ...

sl_shared_assets/server/server.py

@@ -21,16 +21,35 @@ from .job import Job
 
 
 def generate_server_credentials(
-    output_directory: Path, username: str, password: str, host: str = "cbsuwsun.biohpc.cornell.edu"
+    output_directory: Path,
+    username: str,
+    password: str,
+    host: str = "cbsuwsun.biohpc.cornell.edu",
+    raw_data_root: str = "/workdir/sun_data",
+    processed_data_root: str = "/storage/sun_data",
 ) -> None:
     """Generates a new server_credentials.yaml file under the specified directory, using input information.
 
     This function provides a convenience interface for generating new BioHPC server credential files. Generally, this is
     only used when setting up new host-computers in the lab.
+
+    Args:
+        output_directory: The directory where to save the generated server_credentials.yaml file.
+        username: The username to use for server authentication.
+        password: The password to use for server authentication.
+        host: The hostname or IP address of the server to connect to.
+        raw_data_root: The path to the root directory used to store the raw data from all Sun lab projects on the
+            server.
+        processed_data_root: The path to the root directory used to store the processed data from all Sun lab projects
+            on the server.
     """
-    ServerCredentials(username=username, password=password, host=host).to_yaml(
-        file_path=output_directory.joinpath("server_credentials.yaml")
-    )
+    ServerCredentials(
+        username=username,
+        password=password,
+        host=host,
+        raw_data_root=raw_data_root,
+        processed_data_root=processed_data_root,
+    ).to_yaml(file_path=output_directory.joinpath("server_credentials.yaml"))
 
 
 @dataclass()
@@ -49,6 +68,11 @@ class ServerCredentials(YamlConfig):
     """The password to use for server authentication."""
     host: str = "cbsuwsun.biohpc.cornell.edu"
     """The hostname or IP address of the server to connect to."""
+    raw_data_root: str = "/workdir/sun_data"
+    """The path to the root directory used to store the raw data from all Sun lab projects on the target server."""
+    processed_data_root: str = "/storage/sun_data"
+    """The path to the root directory used to store the processed data from all Sun lab projects on the target 
+    server."""
 
 
 class Server:
@@ -248,3 +272,17 @@ class Server:
         # Prevents closing already closed connections
         if self._open:
             self._client.close()
+
+    @property
+    def raw_data_root(self) -> str:
+        """Returns the absolute path to the directory used to store the raw data for all Sun lab projects on the server
+        accessible through this class.
+        """
+        return self._credentials.raw_data_root
+
+    @property
+    def processed_data_root(self) -> str:
+        """Returns the absolute path to the directory used to store the processed data for all Sun lab projects on the
+        server accessible through this class.
+        """
+        return self._credentials.processed_data_root

sl_shared_assets/server/server.pyi

@@ -8,12 +8,27 @@ from ataraxis_data_structures import YamlConfig
 from .job import Job as Job
 
 def generate_server_credentials(
-    output_directory: Path, username: str, password: str, host: str = "cbsuwsun.biohpc.cornell.edu"
+    output_directory: Path,
+    username: str,
+    password: str,
+    host: str = "cbsuwsun.biohpc.cornell.edu",
+    raw_data_root: str = "/workdir/sun_data",
+    processed_data_root: str = "/storage/sun_data",
 ) -> None:
     """Generates a new server_credentials.yaml file under the specified directory, using input information.
 
     This function provides a convenience interface for generating new BioHPC server credential files. Generally, this is
     only used when setting up new host-computers in the lab.
+
+    Args:
+        output_directory: The directory where to save the generated server_credentials.yaml file.
+        username: The username to use for server authentication.
+        password: The password to use for server authentication.
+        host: The hostname or IP address of the server to connect to.
+        raw_data_root: The path to the root directory used to store the raw data from all Sun lab projects on the
+            server.
+        processed_data_root: The path to the root directory used to store the processed data from all Sun lab projects
+            on the server.
     """
 @dataclass()
 class ServerCredentials(YamlConfig):
@@ -28,6 +43,8 @@ class ServerCredentials(YamlConfig):
     username: str = ...
     password: str = ...
     host: str = ...
+    raw_data_root: str = ...
+    processed_data_root: str = ...
 
 class Server:
     """Encapsulates access to the Sun lab BioHPC processing server.
@@ -114,3 +131,13 @@ class Server:
 
         This method has to be called before destroying the class instance to ensure proper resource cleanup.
         """
+    @property
+    def raw_data_root(self) -> str:
+        """Returns the absolute path to the directory used to store the raw data for all Sun lab projects on the server
+        accessible through this class.
+        """
+    @property
+    def processed_data_root(self) -> str:
+        """Returns the absolute path to the directory used to store the processed data for all Sun lab projects on the
+        server accessible through this class.
+        """

sl_shared_assets/tools/project_management_tools.py

@@ -3,13 +3,212 @@ functionality of SessionData class via a convenient API that allows working with
 up a given project."""
 
 from pathlib import Path
+from datetime import datetime
 
+import pytz
 import polars as pl
 from ataraxis_base_utilities import console
 
-from ..data_classes import SessionData, ProcessingTracker
+from ..data_classes import (
+    SessionData,
+    ProcessingTracker,
+    RunTrainingDescriptor,
+    LickTrainingDescriptor,
+    MesoscopeExperimentDescriptor,
+)
 from .packaging_tools import calculate_directory_checksum
 
+_valid_session_types = {"lick training", "run training", "mesoscope experiment", "window checking"}
+
+
+class ProjectManifest:
+    """Wraps the contents of a Sun lab project manifest .feather file and exposes methods for visualizing and
+    working with the data stored inside the file.
+
+    This class functions as a high-level API for working with Sun lab projects. It is used both to visualize the
+    current state of various projects and during automated data processing to determine which processing steps to
+    apply to different sessions.
+
+    Args:
+        manifest_file: The path to the .feather manifest file that stores the target project's state data.
+
+    Attributes:
+        _data: Stores the manifest data as a Polars DataFrame.
+        _animal_string: Determines whether animal IDs are stored as strings or unsigned integers.
+    """
+
+    def __init__(self, manifest_file: Path):
+        # Reads the data from the target manifest file into the class attribute
+        self._data: pl.DataFrame = pl.read_ipc(source=manifest_file, use_pyarrow=True)
+
+        # Determines whether animal IDs are stored as strings or as numbers
+        self._animal_string = False
+        schema = self._data.collect_schema()
+        if isinstance(schema["animal"], pl.String):
+            self._animal_string = True
+
+    def print_data(self) -> None:
+        """Prints the entire contents of the manifest file to the terminal."""
+        with pl.Config(
+            set_tbl_rows=-1,  # Displays all rows (-1 means unlimited)
+            set_tbl_cols=-1,  # Displays all columns (-1 means unlimited)
+            set_tbl_hide_column_data_types=True,
+            set_tbl_cell_alignment="LEFT",
+            set_tbl_width_chars=250,  # Sets table width to 200 characters
+            set_fmt_str_lengths=600,  # Allows longer strings to display properly (default is 32)
+        ):
+            print(self._data)
+
+    def print_summary(self, animal: str | int | None = None) -> None:
+        """Prints a summary view of the manifest file to the terminal, excluding the 'experimenter notes' data for
+        each session.
+
+        This data view is optimized for tracking which processing steps have been applied to each session inside the
+        project.
+
+        Args:
+            animal: The ID of the animal for which to display the data. If an ID is provided, this method will only
+                display the data for that animal. Otherwise, it will display the data for all animals.
+        """
+        summary_cols = [
+            "animal",
+            "date",
+            "session",
+            "type",
+            "complete",
+            "integrity_verification",
+            "suite2p_processing",
+            "behavior_processing",
+            "video_processing",
+            "dataset_formation",
+        ]
+
+        # Retrieves the data
+        df = self._data.select(summary_cols)
+
+        # Optionally filters the data for the target animal
+        if animal is not None:
+            # Ensures that the 'animal' argument has the same type as the data inside the DataFrame.
+            if self._animal_string:
+                animal = str(animal)
+            else:
+                animal = int(animal)
+        df = df.filter(pl.col("animal") == animal)
+
+        # Ensures the data displays properly
+        with pl.Config(
+            set_tbl_rows=-1,
+            set_tbl_cols=-1,
+            set_tbl_width_chars=250,
+            set_tbl_hide_column_data_types=True,
+            set_tbl_cell_alignment="CENTER",
+        ):
+            print(df)
+
+    def print_notes(self, animal: str | int | None = None) -> None:
+        """Prints only animal, session, and notes data from the manifest file.
+
+        This data view is optimized for experimenters to check what sessions have been recorded for each animal in the
+        project and refresh their memory on the outcomes of each session using experimenter notes.
+
+        Args:
+            animal: The ID of the animal for which to display the data. If an ID is provided, this method will only
+                display the data for that animal. Otherwise, it will display the data for all animals.
+        """
+
+        # Pre-selects the columns to display
+        df = self._data.select(["animal", "date", "session", "type", "notes"])
+
+        # Optionally filters the data for the target animal
+        if animal is not None:
+            # Ensures that the 'animal' argument has the same type as the data inside the DataFrame.
+            if self._animal_string:
+                animal = str(animal)
+            else:
+                animal = int(animal)
+
+            df = df.filter(pl.col("animal") == animal)
+
+        #  Prints the extracted data
+        with pl.Config(
+            set_tbl_rows=-1,
+            set_tbl_cols=-1,
+            set_tbl_hide_column_data_types=True,
+            set_tbl_cell_alignment="LEFT",
+            set_tbl_width_chars=250,  # Wider columns for notes
+            set_fmt_str_lengths=600,  # Allows very long strings for notes
+        ):
+            print(df)
+
+    @property
+    def animals(self) -> tuple[str, ...]:
+        """Returns all unique animal IDs stored inside the manifest file.
+
+        This provides a tuple of all animal IDs participating in the target project.
+        """
+        return tuple(self._data.select("animal").unique().sort("animal").to_series().to_list())
+
+    @property
+    def sessions(self) -> tuple[str, ...]:
+        """Returns all session IDs stored inside the manifest file.
+
+        This provides a tuple of all sessions, independent of the participating animal, that were recorded as part
+        of the target project.
+        """
+        return tuple(self._data.select("session").sort("session").to_series().to_list())
+
+    def get_sessions_for_animal(self, animal: str | int, exclude_incomplete: bool = True) -> tuple[str, ...]:
+        """Returns all session IDs for the target animal.
+
+        This provides a tuple of all sessions performed by the target animal as part of the target project.
+
+        Args:
+            animal: The ID of the animal for which to get the session data.
+            exclude_incomplete: Determines whether to exclude sessions not marked as 'complete' from the output
+                list.
+
+        Raises:
+            ValueError: If the specified animal is not found in the manifest file.
+        """
+
+        # Ensures that the 'animal' argument has the same type as the data inside the DataFrame.
+        if self._animal_string:
+            animal = str(animal)
+        else:
+            animal = int(animal)
+
+        if animal not in self.animals:
+            message = f"Animal ID '{animal}' not found in manifest. Available animals: {self.animals}"
+            console.error(message=message, error=ValueError)
+
+        # Filters by animal ID
+        data = self._data.filter(pl.col("animal") == animal)
+
+        # Optionally filters out incomplete sessions
+        if exclude_incomplete:
+            data = data.filter(pl.col("complete") == 1)
+
+        # Formats and returns session IDs to the caller
+        sessions = data.select("session").sort("session").to_series().to_list()
+        return tuple(sessions)
+
+    def get_session_info(self, animal: str | int, session: str) -> pl.DataFrame:
+        """Returns a Polars DataFrame that stores detailed information for the specified session and animal combination.
+
+        Args:
+            animal: The ID of the animal for which to retrieve the data.
+            session: The ID of the session for which to retrieve the data.
+        """
+        # Ensures that the 'animal' argument has the same type as the data inside the DataFrame.
+        if self._animal_string:
+            animal = str(animal)
+        else:
+            animal = int(animal)
+
+        df = self._data
+        df = df.filter(pl.col("animal").eq(animal) & pl.col("session").eq(session))
+        return df
+
 
 def generate_project_manifest(
     raw_project_directory: Path, output_directory: Path, processed_project_directory: Path | None = None
@@ -18,8 +217,8 @@ def generate_project_manifest(
 
     This function evaluates the input project directory and builds the 'manifest' file for the project. The file
     includes the descriptive information about every session stored inside the input project folder and the state of
-    session's data processing (which processing pipelines have been applied to each session). The file will be created
-    under the 'output_path' directory and use the following name pattern: {ProjectName}}_manifest.feather.
+    the session's data processing (which processing pipelines have been applied to each session). The file will be
+    created under the 'output_path' directory and use the following name pattern: {ProjectName}}_manifest.feather.
 
     Notes:
         The manifest file is primarily used to capture and move project state information between machines, typically
@@ -42,7 +241,7 @@ def generate_project_manifest(
         )
         console.error(message=message, error=FileNotFoundError)
 
-    # Finds all raw data directories
+    # Finds all session directories
     session_directories = [directory.parent for directory in raw_project_directory.rglob("raw_data")]
 
     if len(session_directories) == 0:
@@ -54,29 +253,35 @@ def generate_project_manifest(
         console.error(message=message, error=FileNotFoundError)
 
     # Precreates the 'manifest' dictionary structure
-    manifest: dict[str, list[str | bool]] = {
+    manifest: dict[str, list[str | bool | datetime | int]] = {
         "animal": [],  # Animal IDs.
         "session": [],  # Session names.
+        "date": [],  # Session names stored as timezone-aware date-time objects in EST.
         "type": [],  # Type of the session (e.g., Experiment, Training, etc.).
-        "raw_data": [],  # Server-side raw_data folder path.
-        "processed_data": [],  # Server-side processed_data folder path.
-        # Determines whether the session data is complete. Incomplete sessions are excluded from processing.
+        "notes": [],  # The experimenter notes about the session.
+        # Determines whether the session data is complete (ran for the intended duration and has all expected data).
         "complete": [],
-        # Determines whether the session data integrity has been verified upon transfer to storage machine.
+        # Determines whether the session data integrity has been verified upon transfer to a storage machine.
         "integrity_verification": [],
         "suite2p_processing": [],  # Determines whether the session has been processed with the single-day s2p pipeline.
-        "dataset_formation": [],  # Determines whether the session's data has been integrated into a dataset.
         # Determines whether the session has been processed with the behavior extraction pipeline.
         "behavior_processing": [],
         "video_processing": [],  # Determines whether the session has been processed with the DeepLabCut pipeline.
+        "dataset_formation": [],  # Determines whether the session's data has been integrated into a dataset.
     }
 
     # Loops over each session of every animal in the project and extracts session ID information and information
     # about which processing steps have been successfully applied to the session.
     for directory in session_directories:
+        # Skips processing directories without files (sessions with empty raw-data directories)
+        if len([file for file in directory.joinpath("raw_data").glob("*")]) == 0:
+            continue
+
         # Instantiates the SessionData instance to resolve the paths to all session's data files and locations.
         session_data = SessionData.load(
-            session_path=directory, processed_data_root=processed_project_directory, make_processed_data_directory=False
+            session_path=directory,
+            processed_data_root=processed_project_directory,
+            make_processed_data_directory=False,
         )
 
         # Fills the manifest dictionary with data for the processed session:
@@ -85,8 +290,44 @@ def generate_project_manifest(
         manifest["animal"].append(session_data.animal_id)
         manifest["session"].append(session_data.session_name)
         manifest["type"].append(session_data.session_type)
-        manifest["raw_data"].append(str(session_data.raw_data.raw_data_path))
-        manifest["processed_data"].append(str(session_data.processed_data.processed_data_path))
+
+        # Parses session name into the date-time object to simplify working with date-time data in the future
+        date_time_components = session_data.session_name.split("-")
+        date_time = datetime(
+            year=int(date_time_components[0]),
+            month=int(date_time_components[1]),
+            day=int(date_time_components[2]),
+            hour=int(date_time_components[3]),
+            minute=int(date_time_components[4]),
+            second=int(date_time_components[5]),
+            microsecond=int(date_time_components[6]),
+            tzinfo=pytz.UTC,
+        )
+
+        # Converts from UTC to EST / EDT for user convenience
+        eastern = pytz.timezone("America/New_York")
+        date_time = date_time.astimezone(eastern)
+        manifest["date"].append(date_time)
+
+        # Depending on the session type, instantiates the appropriate descriptor instance and uses it to read the
+        # experimenter notes
+        if session_data.session_type == "lick training":
+            descriptor: LickTrainingDescriptor = LickTrainingDescriptor.from_yaml(  # type: ignore
+                file_path=session_data.raw_data.session_descriptor_path
+            )
+            manifest["notes"].append(descriptor.experimenter_notes)
+        elif session_data.session_type == "run training":
+            descriptor: RunTrainingDescriptor = RunTrainingDescriptor.from_yaml(  # type: ignore
+                file_path=session_data.raw_data.session_descriptor_path
+            )
+            manifest["notes"].append(descriptor.experimenter_notes)
+        elif session_data.session_type == "mesoscope experiment":
+            descriptor: MesoscopeExperimentDescriptor = MesoscopeExperimentDescriptor.from_yaml(  # type: ignore
+                file_path=session_data.raw_data.session_descriptor_path
+            )
+            manifest["notes"].append(descriptor.experimenter_notes)
+        elif session_data.session_type == "window checking":
+            manifest["notes"].append("N/A")
 
         # If the session raw_data folder contains the telomere.bin file, marks the session as complete.
         manifest["complete"].append(session_data.raw_data.telomere_path.exists())
@@ -96,9 +337,9 @@ def generate_project_manifest(
         manifest["integrity_verification"].append(tracker.is_complete)
 
         # If the session is incomplete or unverified, marks all processing steps as FALSE, as automatic processing is
-        # disabled for incomplete sessions. If the session unverified, the case is even more severe, as its data may be
-        # corrupted.
-        if not manifest["complete"][-1] or not not manifest["verified"][-1]:
+        # disabled for incomplete sessions. If the session is unverified, the case is even more severe, as its data may
+        # be corrupted.
+        if not manifest["complete"][-1] or not manifest["integrity_verification"][-1]:
             manifest["suite2p_processing"].append(False)
             manifest["dataset_formation"].append(False)
             manifest["behavior_processing"].append(False)
@@ -118,24 +359,34 @@ def generate_project_manifest(
         manifest["behavior_processing"].append(tracker.is_complete)
 
         # DeepLabCut (video) processing status.
-        tracker = ProcessingTracker(file_path=session_data.processed_data.behavior_processing_tracker_path)
+        tracker = ProcessingTracker(file_path=session_data.processed_data.video_processing_tracker_path)
         manifest["video_processing"].append(tracker.is_complete)
 
-    # Converts the manifest dictionary to a Polars Dataframe
+    # If all animal IDs are integer-convertible, stores them as numbers to promote proper sorting. Otherwise, stores
+    # them as strings. The latter options are primarily kept for compatibility with Tyche data
+    animal_type: type[pl.UInt64] | type[pl.String]
+    if all([str(animal).isdigit() for animal in manifest["animal"]]):
+        # Converts all strings to integers
+        manifest["animal"] = [int(animal) for animal in manifest["animal"]]  # type: ignore
+        animal_type = pl.UInt64  # Uint64 for future proofing
+    else:
+        animal_type = pl.String
+
+    # Converts the manifest dictionary to a Polars Dataframe.
     schema = {
-        "animal": pl.String,
+        "animal": animal_type,
+        "date": pl.Datetime,
         "session": pl.String,
-        "raw_data": pl.String,
-        "processed_data": pl.String,
         "type": pl.String,
-        "complete": pl.Boolean,
-        "integrity_verification": pl.Boolean,
-        "suite2p_processing": pl.Boolean,
-        "dataset_formation": pl.Boolean,
-        "behavior_processing": pl.Boolean,
-        "video_processing": pl.Boolean,
+        "notes": pl.String,
+        "complete": pl.UInt8,
+        "integrity_verification": pl.UInt8,
+        "suite2p_processing": pl.UInt8,
+        "dataset_formation": pl.UInt8,
+        "behavior_processing": pl.UInt8,
+        "video_processing": pl.UInt8,
     }
-    df = pl.DataFrame(manifest, schema=schema)
+    df = pl.DataFrame(manifest, schema=schema, strict=False)
 
     # Sorts the DataFrame by animal and then session. Since we assign animal IDs sequentially and 'name' sessions based
     # on acquisition timestamps, the sort order is chronological.
@@ -158,8 +409,8 @@ def verify_session_checksum(
     matches and to remove the 'telomere.bin' and 'verified.bin' marker files if it does not.
 
     Notes:
-        Removing the telomere.bin marker file from session's raw_data folder marks the session as incomplete, excluding
-        it from all further automatic processing.
+        Removing the telomere.bin marker file from the session's raw_data folder marks the session as incomplete,
+        excluding it from all further automatic processing.
 
         This function is also used to create the processed data hierarchy on the BioHPC server, when it is called as
         part of the data preprocessing runtime performed by a data acquisition system.

sl_shared_assets/tools/project_management_tools.pyi

@@ -1,11 +1,95 @@
 from pathlib import Path
 
+import polars as pl
+from _typeshed import Incomplete
+
 from ..data_classes import (
     SessionData as SessionData,
     ProcessingTracker as ProcessingTracker,
+    RunTrainingDescriptor as RunTrainingDescriptor,
+    LickTrainingDescriptor as LickTrainingDescriptor,
+    MesoscopeExperimentDescriptor as MesoscopeExperimentDescriptor,
 )
 from .packaging_tools import calculate_directory_checksum as calculate_directory_checksum
 
+_valid_session_types: Incomplete
+
+class ProjectManifest:
+    """Wraps the contents of a Sun lab project manifest .feather file and exposes methods for visualizing and
+    working with the data stored inside the file.
+
+    This class functions as a high-level API for working with Sun lab projects. It is used both to visualize the
+    current state of various projects and during automated data processing to determine which processing steps to
+    apply to different sessions.
+
+    Args:
+        manifest_file: The path to the .feather manifest file that stores the target project's state data.
+
+    Attributes:
+        _data: Stores the manifest data as a Polars DataFrame.
+        _animal_string: Determines whether animal IDs are stored as strings or unsigned integers.
+    """
+
+    _data: pl.DataFrame
+    _animal_string: bool
+    def __init__(self, manifest_file: Path) -> None: ...
+    def print_data(self) -> None:
+        """Prints the entire contents of the manifest file to the terminal."""
+    def print_summary(self, animal: str | int | None = None) -> None:
+        """Prints a summary view of the manifest file to the terminal, excluding the 'experimenter notes' data for
+        each session.
+
+        This data view is optimized for tracking which processing steps have been applied to each session inside the
+        project.
+
+        Args:
+            animal: The ID of the animal for which to display the data. If an ID is provided, this method will only
+                display the data for that animal. Otherwise, it will display the data for all animals.
+        """
+    def print_notes(self, animal: str | int | None = None) -> None:
+        """Prints only animal, session, and notes data from the manifest file.
+
+        This data view is optimized for experimenters to check what sessions have been recorded for each animal in the
+        project and refresh their memory on the outcomes of each session using experimenter notes.
+
+        Args:
+            animal: The ID of the animal for which to display the data. If an ID is provided, this method will only
+                display the data for that animal. Otherwise, it will display the data for all animals.
+        """
+    @property
+    def animals(self) -> tuple[str, ...]:
+        """Returns all unique animal IDs stored inside the manifest file.
+
+        This provides a tuple of all animal IDs participating in the target project.
+        """
+    @property
+    def sessions(self) -> tuple[str, ...]:
+        """Returns all session IDs stored inside the manifest file.
+
+        This provides a tuple of all sessions, independent of the participating animal, that were recorded as part
+        of the target project.
+        """
+    def get_sessions_for_animal(self, animal: str | int, exclude_incomplete: bool = True) -> tuple[str, ...]:
+        """Returns all session IDs for the target animal.
+
+        This provides a tuple of all sessions performed by the target animal as part of the target project.
+
+        Args:
+            animal: The ID of the animal for which to get the session data.
+            exclude_incomplete: Determines whether to exclude sessions not marked as 'complete' from the output
+                list.
+
+        Raises:
+            ValueError: If the specified animal is not found in the manifest file.
+        """
+    def get_session_info(self, animal: str | int, session: str) -> pl.DataFrame:
+        """Returns a Polars DataFrame that stores detailed information for the specified session and animal combination.
+
+        Args:
+            animal: The ID of the animal for which to retrieve the data.
+            session: The ID of the session for which to retrieve the data.
+        """
+
 def generate_project_manifest(
     raw_project_directory: Path, output_directory: Path, processed_project_directory: Path | None = None
 ) -> None:
@@ -13,8 +97,8 @@ def generate_project_manifest(
 
     This function evaluates the input project directory and builds the 'manifest' file for the project. The file
     includes the descriptive information about every session stored inside the input project folder and the state of
-    session's data processing (which processing pipelines have been applied to each session). The file will be created
-    under the 'output_path' directory and use the following name pattern: {ProjectName}}_manifest.feather.
+    the session's data processing (which processing pipelines have been applied to each session). The file will be
+    created under the 'output_path' directory and use the following name pattern: {ProjectName}}_manifest.feather.
 
     Notes:
         The manifest file is primarily used to capture and move project state information between machines, typically
@@ -41,8 +125,8 @@ def verify_session_checksum(
     matches and to remove the 'telomere.bin' and 'verified.bin' marker files if it does not.
 
     Notes:
-        Removing the telomere.bin marker file from session's raw_data folder marks the session as incomplete, excluding
-        it from all further automatic processing.
+        Removing the telomere.bin marker file from the session's raw_data folder marks the session as incomplete,
+        excluding it from all further automatic processing.
 
         This function is also used to create the processed data hierarchy on the BioHPC server, when it is called as
         part of the data preprocessing runtime performed by a data acquisition system.

{sl_shared_assets-1.2.0rc2.dist-info → sl_shared_assets-1.2.0rc4.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: sl-shared-assets
-Version: 1.2.0rc2
+Version: 1.2.0rc4
 Summary: Stores assets shared between multiple Sun (NeuroAI) lab data pipelines.
 Project-URL: Homepage, https://github.com/Sun-Lab-NBB/sl-shared-assets
 Project-URL: Documentation, https://sl-shared-assets-api-docs.netlify.app/
-Author: Ivan Kondratyev, Kushaan Gupta, Yuantao Deng, Natalie Yeung
+Author: Ivan Kondratyev, Kushaan Gupta, Natalie Yeung
 Maintainer-email: Ivan Kondratyev <ik278@cornell.edu>
 License:                     GNU GENERAL PUBLIC LICENSE
                                Version 3, 29 June 2007
@@ -690,19 +690,21 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
-Requires-Dist: appdirs<2,>=1
-Requires-Dist: ataraxis-base-utilities<4,>=3
-Requires-Dist: ataraxis-data-structures<4,>=3.1.1
-Requires-Dist: ataraxis-time<4,>=3
-Requires-Dist: click<9,>=8
-Requires-Dist: filelock<4,>=3
-Requires-Dist: natsort<9,>=8
-Requires-Dist: paramiko<4,>=3.5.1
-Requires-Dist: polars<2,>=1
-Requires-Dist: pyarrow<21,>=20
-Requires-Dist: simple-slurm<1,>=0
-Requires-Dist: tqdm<5,>=4
-Requires-Dist: xxhash<4,>=3
+Requires-Dist: appdirs==1.4.4
+Requires-Dist: ataraxis-base-utilities==3.0.1
+Requires-Dist: ataraxis-data-structures==3.1.1
+Requires-Dist: ataraxis-time==3.0.0
+Requires-Dist: click==8.2.1
+Requires-Dist: filelock==3.18.0
+Requires-Dist: natsort==8.4.0
+Requires-Dist: numpy==2.2.6
+Requires-Dist: paramiko==3.5.1
+Requires-Dist: polars==1.31.0
+Requires-Dist: pyarrow==20.0.0
+Requires-Dist: pytz==2025.2
+Requires-Dist: simple-slurm==0.3.6
+Requires-Dist: tqdm==4.67.1
+Requires-Dist: xxhash==3.5.0
 Provides-Extra: conda
 Requires-Dist: grayskull<3,>=2; extra == 'conda'
 Requires-Dist: hatchling<2,>=1; extra == 'conda'
@@ -719,14 +721,16 @@ Requires-Dist: types-filelock<4,>=3; extra == 'conda'
 Requires-Dist: types-paramiko<4,>=3; extra == 'conda'
 Requires-Dist: types-tqdm<5,>=4; extra == 'conda'
 Provides-Extra: condarun
-Requires-Dist: appdirs<2,>=1; extra == 'condarun'
-Requires-Dist: click<9,>=8; extra == 'condarun'
-Requires-Dist: filelock<4,>=3; extra == 'condarun'
-Requires-Dist: natsort<9,>=8; extra == 'condarun'
-Requires-Dist: paramiko<4,>=3.5.1; extra == 'condarun'
-Requires-Dist: polars<2,>=1; extra == 'condarun'
-Requires-Dist: pyarrow<21,>=20; extra == 'condarun'
-Requires-Dist: tqdm<5,>=4; extra == 'condarun'
+Requires-Dist: appdirs==1.4.4; extra == 'condarun'
+Requires-Dist: click==8.2.1; extra == 'condarun'
+Requires-Dist: filelock==3.18.0; extra == 'condarun'
+Requires-Dist: natsort==8.4.0; extra == 'condarun'
+Requires-Dist: numpy==2.2.6; extra == 'condarun'
+Requires-Dist: paramiko==3.5.1; extra == 'condarun'
+Requires-Dist: polars==1.31.0; extra == 'condarun'
+Requires-Dist: pyarrow==20.0.0; extra == 'condarun'
+Requires-Dist: pytz==2025.2; extra == 'condarun'
+Requires-Dist: tqdm==4.67.1; extra == 'condarun'
 Provides-Extra: dev
 Requires-Dist: ataraxis-automation<6,>=5; extra == 'dev'
 Requires-Dist: build<2,>=1; extra == 'dev'
@@ -746,6 +750,7 @@ Requires-Dist: twine<7,>=6; extra == 'dev'
 Requires-Dist: types-appdirs<2,>=1; extra == 'dev'
 Requires-Dist: types-filelock<4,>=3; extra == 'dev'
 Requires-Dist: types-paramiko<4,>=3; extra == 'dev'
+Requires-Dist: types-pytz<2026,>=2025; extra == 'dev'
 Requires-Dist: types-tqdm<5,>=4; extra == 'dev'
 Requires-Dist: uv<1,>=0; extra == 'dev'
 Provides-Extra: noconda
@@ -754,6 +759,7 @@ Requires-Dist: build<2,>=1; extra == 'noconda'
 Requires-Dist: sphinx-rtd-dark-mode<2,>=1; extra == 'noconda'
 Requires-Dist: tox-uv<2,>=1; extra == 'noconda'
 Requires-Dist: tox<5,>=4; extra == 'noconda'
+Requires-Dist: types-pytz<2026,>=2025; extra == 'noconda'
 Requires-Dist: uv<1,>=0; extra == 'noconda'
 Description-Content-Type: text/markdown
 

{sl_shared_assets-1.2.0rc2.dist-info → sl_shared_assets-1.2.0rc4.dist-info}/RECORD

@@ -1,14 +1,14 @@
 sl_shared_assets/__init__.py,sha256=_AOpxu9K_0px_xS07H8mqZeYlBS9aD75XBS0dofJzqw,2280
 sl_shared_assets/__init__.pyi,sha256=H1kPervb1A2BjG5EOLsLFQGUWFS_aHWy4cpL4_W71Fs,2525
-sl_shared_assets/cli.py,sha256=2HAgnD7hHnFp3R7_tJAfWBI_jRbhSuyDBFK3TGIHYsw,17771
+sl_shared_assets/cli.py,sha256=SrzbcYbVQQ_fCz29t7JwOdY_ZSUJLHOuH4fJaIdDd1I,18395
 sl_shared_assets/cli.pyi,sha256=Fh8GZBSQzII_Iz6k5nLQOsVMbp7q1R5mp4KNZjdGflY,6119
 sl_shared_assets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sl_shared_assets/data_classes/__init__.py,sha256=ixn972b-3URCinVLRPjMfDXpO2w24_NkEUUjdqByFrA,1890
 sl_shared_assets/data_classes/__init__.pyi,sha256=bDBLkyhlosB4t09GxHBNKH0kaVBhHSY_j-i3MD2iKVo,2088
-sl_shared_assets/data_classes/configuration_data.py,sha256=ZVk1ynk25CfVuQfMofoH90BUaOPqk7zW8ukY6ls_Pp0,30360
-sl_shared_assets/data_classes/configuration_data.pyi,sha256=h7AV3z73SC2ITXWcnsShczuezC1Is7L4WSMnEWGSLPQ,9617
-sl_shared_assets/data_classes/runtime_data.py,sha256=5aGp7HMwUUGUdRkkxC3ZA_G604h0ZDMYlFOHvuQGCeI,15719
-sl_shared_assets/data_classes/runtime_data.pyi,sha256=F151EwpuHorhIyvJ1MBmEC4dzfLZb2D1YaHwQ-qrDyY,6644
+sl_shared_assets/data_classes/configuration_data.py,sha256=eL8eGl1EF2Sl8J4W6qB78L5r092qnnbEjiApxyK6lCw,29402
+sl_shared_assets/data_classes/configuration_data.pyi,sha256=U-snwWQqYT5-zcd8s3ZV8xX27BEpgy9vKlXvie3NKSE,9537
+sl_shared_assets/data_classes/runtime_data.py,sha256=Q7Ykf9hgrw1jYKXa53mn_LW8G2cPmLLuxgGkP6qQcc4,15483
+sl_shared_assets/data_classes/runtime_data.pyi,sha256=PxaCbeF9COR4ri91pdzh7zVrqaz2KEDYB1EoLhZQC_c,6618
 sl_shared_assets/data_classes/session_data.py,sha256=DHfjGXvdMRsOl1fTgNFrF3u9THAQFtTruDU0tsd0y8c,51767
 sl_shared_assets/data_classes/session_data.pyi,sha256=ajVrNwGpk9TQj79WURVYpQ2Bhy-XZsau8VABBgtOzrY,16452
 sl_shared_assets/data_classes/surgery_data.py,sha256=qsMj3NkjhylAT9b_wHBY-1XwTu2xsZcZatdECmkA7Bs,7437
@@ -17,20 +17,20 @@ sl_shared_assets/server/__init__.py,sha256=nyX6-9ACcrQeRQOCNvBVrWSTHGjRPANIG_u0a
 sl_shared_assets/server/__init__.pyi,sha256=7o99f8uf6NuBjMZjNAM1FX69Qbu5uBluRSAyaUWbXOU,263
 sl_shared_assets/server/job.py,sha256=GB31yYPEqXR6MgwNmnQrSQuHRJqUHFXcd6p7hb38q_c,7928
 sl_shared_assets/server/job.pyi,sha256=cxgHMpuwHsJGf_ZcTSSa2tZNzeR_GxqlICOsYGV_oy0,5655
-sl_shared_assets/server/server.py,sha256=s2lOrOxcBGQsELKrWu9yCX4Ga5olyLNmWLSCOFyyC44,11002
-sl_shared_assets/server/server.pyi,sha256=h8wI9rMcEuGLrJulndUjASM7E_nU4G6gXnjPge6mWHg,5263
+sl_shared_assets/server/server.py,sha256=DR0nEO1nZgiLzdG958xmQasRRJ5PCQP9JXdCtBE08iU,12700
+sl_shared_assets/server/server.pyi,sha256=4ZpZXkpVC7Zqksq485HgWP8voCFx-Q4VK4mLalgpwvc,6481
 sl_shared_assets/tools/__init__.py,sha256=N95ZPMz-_HdNPrbVieCFza-QSVS6BV2KRB4K1OLRttc,636
 sl_shared_assets/tools/__init__.pyi,sha256=xeDF8itMc0JRgLrO_IN_9gW7cp_Ld-Gf-rjtrgWvQ2I,551
 sl_shared_assets/tools/ascension_tools.py,sha256=kIqYGX9F8lRao_LaVOacIiT8J9SypTvarb9mgaI9ZPs,15387
 sl_shared_assets/tools/ascension_tools.pyi,sha256=tQCDdWZ20ZjUjpMs8aGIN0yBg5ff3j6spi62b3Han4o,3755
 sl_shared_assets/tools/packaging_tools.py,sha256=c9U0bKB6Btj7sfyeU7xx2Jiqv930qTnXbm0ZbNR-o2k,7594
 sl_shared_assets/tools/packaging_tools.pyi,sha256=vgGbAQCExwg-0A5F72MzEhzHxu97Nqg1yuz-5P89ycU,3118
-sl_shared_assets/tools/project_management_tools.py,sha256=DgMKd6i3iLG4lwVgcCgQeO8jZEfVoWFKU6882JrDvL4,11993
-sl_shared_assets/tools/project_management_tools.pyi,sha256=f_3O8UjnfHRMEe2iZpQxKK9Vb0_lJB2yI1WcJPUqGEU,3498
+sl_shared_assets/tools/project_management_tools.py,sha256=UzvDFvJ8ZohUQlsZya0GdrtUlUQnOMFJEJY5CUXIW3U,22706
+sl_shared_assets/tools/project_management_tools.pyi,sha256=sxjhQzeZ4vIcNwIDtFXYxN9jbTQb-PbCOPZL5P71xa8,7440
 sl_shared_assets/tools/transfer_tools.py,sha256=J26kwOp_NpPSY0-xu5FTw9udte-rm_mW1FJyaTNoqQI,6606
 sl_shared_assets/tools/transfer_tools.pyi,sha256=FoH7eYZe7guGHfPr0MK5ggO62uXKwD2aJ7h1Bu7PaEE,3294
-sl_shared_assets-1.2.0rc2.dist-info/METADATA,sha256=wiTJc7nWlmRmTlAf_5-oIcZIuqvb51g5gt8QsZ7l6-U,49080
-sl_shared_assets-1.2.0rc2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sl_shared_assets-1.2.0rc2.dist-info/entry_points.txt,sha256=76c00fRS4IuXBP2xOBdvycT15Zen-lHiDg2FaSt-HB4,547
-sl_shared_assets-1.2.0rc2.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-sl_shared_assets-1.2.0rc2.dist-info/RECORD,,
+sl_shared_assets-1.2.0rc4.dist-info/METADATA,sha256=IO6x6Y5-KymLtssNsRRlyGjHxI181b9zBpJF7qwDSlA,49345
+sl_shared_assets-1.2.0rc4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sl_shared_assets-1.2.0rc4.dist-info/entry_points.txt,sha256=76c00fRS4IuXBP2xOBdvycT15Zen-lHiDg2FaSt-HB4,547
+sl_shared_assets-1.2.0rc4.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+sl_shared_assets-1.2.0rc4.dist-info/RECORD,,