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

sl_shared_assets/tools/ascension_tools.py

@@ -0,0 +1,277 @@
+"""This module provides tools for translating ('ascending') old Tyche data to use the modern data structure used in the
+Sun lab. The tools from this module will not work for any other data and also assume that the Tyche data has been
+preprocessed with an early version of the Sun lab mesoscope processing pipeline. However, this module can be used as
+an example for how to convert other data formats to match use the Sun lab data structure."""
+
+from pathlib import Path
+import datetime
+
+import numpy as np
+from ataraxis_base_utilities import LogLevel, console, ensure_directory_exists
+from ataraxis_time.time_helpers import extract_timestamp_from_bytes
+
+from ..data_classes import SessionData, ProjectConfiguration, get_system_configuration_data
+from .transfer_tools import transfer_directory
+from .packaging_tools import calculate_directory_checksum
+
+
+def _generate_session_name(acquisition_path: Path) -> str:
+    """Generates a session name using the last modification time of a zstack.mat or MotionEstimator.me file.
+
+    This worker function uses one of the motion estimation files stored in each Tyche 'acquisition' subfolder to
+    generate a modern Sun lab timestamp-based session name. This is used to translate the original Tyche session naming
+    pattern into the pattern used by all modern Sun lab projects and pipelines.
+
+    Args:
+        acquisition_path: The absolute path to the target acquisition folder. These folders are found under the 'day'
+            folders for each animal, e.g.: Tyche-A7/2022_01_03/1.
+
+    Returns:
+        The modernized session name.
+    """
+
+    # All well-formed sessions are expected to contain both the zstack.mat and the MotionEstimator.me file.
+    # We use the last modification time from one of these files to infer when the session was carried out. This allows
+    # us to gather the time information, which is missing from the original session naming pattern.
+    source: Path
+    if acquisition_path.joinpath("zstack.mat").exists():
+        source = acquisition_path.joinpath("zstack.mat")
+    elif acquisition_path.joinpath("MotionEstimator.me").exists():
+        source = acquisition_path.joinpath("MotionEstimator.me")
+    else:
+        message = (
+            f"Unable to find zstack.mat or MotionEstimator.me file in the target acquisition subfolder "
+            f"{acquisition_path} of the session {acquisition_path.parent}. Manual intervention is required to ascend "
+            f"the target session folder to the latest Sun lab data format."
+        )
+        console.error(message=message, error=FileNotFoundError)
+        raise FileNotFoundError(message)  # Fall-back to appease mypy
+
+    # Gets last modified time (available on all platforms) and converts it to a UTC timestamp object.
+    mod_time = source.stat().st_mtime
+    mod_datetime = datetime.datetime.fromtimestamp(mod_time)
+
+    # Converts the timestamp to microseconds as uint64, then to an array of 8 uint8 bytes. The array is then reformatted
+    # to match the session name pattern used in the modern Sun lab data pipelines.
+    timestamp_microseconds = np.uint64(int(mod_datetime.timestamp() * 1_000_000))
+    timestamp_bytes = np.array([(timestamp_microseconds >> (8 * i)) & 0xFF for i in range(8)], dtype=np.uint8)
+    stamp = extract_timestamp_from_bytes(timestamp_bytes=timestamp_bytes)
+
+    # Returns the generated session name to caller.
+    return stamp
+
+
+def _reorganize_data(session_data: SessionData, source_root: Path) -> bool:
+    """Reorganizes and moves the session's data from the source folder in the old Tyche data hierarchy to the raw_data
+    folder in the newly created modern hierarchy.
+
+    This worker function is used to physically rearrange the data from the original Tyche data structure to the
+    new data structure. It both moves the existing files to their new destinations and renames certain files to match
+    the modern naming convention used in the Sun lab.
+
+    Args:
+        session_data: The initialized SessionData instance managing the 'ascended' (modernized) session data hierarchy.
+        source_root: The absolute path to the old Tyche data hierarchy folder that stores session's data.
+
+    Returns:
+        True if the ascension process was successfully completed. False if the process encountered missing data or
+        otherwise did not go as expected. When the method returns False, the runtime function requests user intervention
+        to finalize the process manually.
+    """
+
+    # Resolves expected data targets:
+
+    # These files should be present in all well-formed session data folders. While not all session folders are
+    # well-formed, we will likely exclude any non-well-formed folders from processing.
+    zstack_path = source_root.joinpath("zstack.mat")
+    motion_estimator_path = source_root.joinpath("MotionEstimator.me")
+    ops_path = source_root.joinpath("ops.json")
+    mesoscope_frames_path = source_root.joinpath("mesoscope_frames")
+    ax_checksum_path = source_root.joinpath("ax_checksum.txt")
+
+    # These two file types are present for some, but not all folders. They are not as important as the group of files
+    # above though, as, currently, the data stored in these files is not used during processing.
+    frame_metadata_path = source_root.joinpath("frame_metadata.npz")
+    metadata_path = source_root.joinpath("metadata.json")
+
+    # This tracker is used to mark the session for manual intervention if any expected data is missing from the source
+    # session folder. At the end of this function's runtime, it determines whether the function returns True or False
+    data_missing = False
+
+    # First, moves the mesoscope TIFF stacks to the newly created session data hierarchy as mesoscope_data subfolder
+    if mesoscope_frames_path.exists():
+        mesoscope_frames_path.rename(session_data.raw_data.mesoscope_data_path)
+    else:
+        data_missing = True
+
+    # Then, moves 'loose' mesoscope-related data files to the mesoscope_data folder.
+    if zstack_path.exists():
+        zstack_path.rename(Path(session_data.raw_data.mesoscope_data_path).joinpath("zstack.mat"))
+    else:
+        data_missing = True
+
+    if motion_estimator_path.exists():
+        motion_estimator_path.rename(Path(session_data.raw_data.mesoscope_data_path).joinpath("MotionEstimator.me"))
+    else:
+        data_missing = True
+
+    if ops_path.exists():
+        ops_path.rename(Path(session_data.raw_data.mesoscope_data_path).joinpath("ops.json"))
+    else:
+        data_missing = True
+
+    # If variant and invariant metadata files exist, also moves them to the mesoscope data folder and renames the
+    # files to use the latest naming convention. Missing any of these files is not considered a user-intervention-worthy
+    # situation.
+    if frame_metadata_path.exists():
+        frame_metadata_path.rename(
+            Path(session_data.raw_data.mesoscope_data_path).joinpath("frame_variant_metadata.npz")
+        )
+    if metadata_path.exists():
+        metadata_path.rename(Path(session_data.raw_data.mesoscope_data_path).joinpath("frame_invariant_metadata.json"))
+
+    # Loops over all camera video files (using the .avi extension) and moves them to the camera_data folder.
+    videos_found = 0
+    for video in source_root.glob("*.avi"):
+        videos_found += 1
+        video.rename(Path(session_data.raw_data.camera_data_path).joinpath(video.name))
+    if videos_found == 0:
+        data_missing = True
+
+    # Loops over all behavior log files (old GIMBL format) and moves them to the behavior_data folder.
+    logs_found = 0
+    for log in source_root.glob("Log Tyche-* ????-??-?? session *.json"):
+        logs_found += 1
+        log.rename(Path(session_data.raw_data.behavior_data_path).joinpath(log.name))
+    if logs_found == 0:
+        data_missing = True
+
+    # Removes the checksum file if it exists. Due to file name and location changes, the session data folder has to
+    # be re-checksummed after the reorganization anyway, so there is no need to keep the original file.
+    ax_checksum_path.unlink(missing_ok=True)
+
+    # Loops over all remaining contents of the directory.
+    for path in source_root.glob("*"):
+        # At this point, there should be no more subfolders left inside the root directory. If there are more
+        # subfolders, this case requires user intervention
+        if path.is_dir():
+            data_missing = True
+
+        # All non-subfolder files are moved to the root raw_data directory of the newly created session.
+        else:
+            path.rename(Path(session_data.raw_data.raw_data_path).joinpath(path.name))
+
+    # Session data has been fully reorganized. Depending on whether there was any missing data during processing,
+    # returns the boolean flag for whether user intervention is required
+    if data_missing:
+        return False
+    else:
+        return True
+
+
+def ascend_tyche_data(root_directory: Path) -> None:
+    """Reformats the old Tyche data to use the modern Sun lab layout and metadata files.
+
+    This function is used to convert old Tyche data to the modern data management standard. This is used to make the
+    data compatible with the modern Sun lab data workflows.
+
+    Notes:
+        This function is statically written to work with the raw Tyche dataset featured in the OSM manuscript:
+        https://www.nature.com/articles/s41586-024-08548-w. Additionally, it assumes that the dataset has been
+        preprocessed with the early Sun lab mesoscope compression pipeline. The function will not work for any other
+        project or data hierarchy.
+
+        As part of its runtime, the function automatically transfers the ascended session data to the BioHPC server.
+        Since transferring the data over the network is the bottleneck of this pipeline, it runs in a single-threaded
+        mode and is constrained by the communication channel between the local machine and the BioHPC server. Calling
+        this function for a large number of sessions will result in a long processing time due to the network data
+        transfer.
+
+        Since SessionData can only be created on a PC that has a valid acquisition system config, this function will
+        only work on a machine that is part of an active Sun lab acquisition system.
+
+    Args:
+        root_directory: The directory that stores one or more Tyche animal folders. This can be conceptualized as the
+            root directory for the Tyche project.
+    """
+    # Generates a (shared) project configuration file.
+    project_configuration = ProjectConfiguration()
+
+    # The acquisition system config resolves most paths and filesystem configuration arguments
+    acquisition_system = get_system_configuration_data()
+    output_root_directory = acquisition_system.paths.root_directory
+    server_root_directory = acquisition_system.paths.server_storage_directory
+
+    # Statically defines project name and local root paths
+    project_name = "Tyche"
+    project_configuration.project_name = project_name
+
+    # Uses nonsensical google sheet IDs. Tyche project did not use Google Sheet processing like our modern projects do.
+    project_configuration.water_log_sheet_id = "1xFh9Q2zT7pL3mVkJdR8bN6yXoE4wS5aG0cHu2Kf7D3v"
+    project_configuration.surgery_sheet_id = "1xFh9Q2zT7pL3mVkJdR8bN6yXoE4wS5aG0cHu2Kf7D3v"
+
+    # Dumps project configuration into the 'configuration' subfolder of the Tyche project.
+    configuration_path = output_root_directory.joinpath("Tyche", "configuration", "project_configuration.yaml")
+    ensure_directory_exists(configuration_path)
+    project_configuration.save(path=configuration_path)
+
+    # Assumes that root directory stores all animal folders to be processed
+    for animal_folder in root_directory.iterdir():
+        # Each animal folder is named to include project name and a static animal ID, e.g.: Tyche-A7. This extracts each
+        # animal ID.
+        animal_name = animal_folder.stem.split(sep="-")[1]
+
+        # Under each animal root folder, there are day folders that use YYYY-MM-DD timestamps
+        for session_folder in animal_folder.iterdir():
+            # Inside each day folder, there are one or more acquisitions (sessions)
+            for acquisition_folder in session_folder.iterdir():
+                # For each session, we extract the modification time from either (preferentially) zstack.mat or
+                # MotionEstimator.me file. Any session without these files is flagged for additional user intervention.
+                # This procedure generates timestamp-based session names, analogous to how our modern pipeline does it.
+                session_name = _generate_session_name(acquisition_path=acquisition_folder)
+
+                # Uses derived session name and the statically created project configuration file to create the
+                # session data hierarchy using the output root. This generates a 'standard' Sun lab directory structure
+                # for the Tyche data.
+                session_data = SessionData.create(
+                    project_name=project_configuration.project_name,
+                    session_name=session_name,
+                    animal_id=animal_name,
+                    session_type="mesoscope experiment",
+                    experiment_name=None,
+                )
+
+                # Moves the data from the old hierarchy to the new hierarchy. If the process runs as expected, and
+                # fully empties the source acquisition folder, destroys the folder. Otherwise, notifies the user that
+                # the runtime did not fully process the session data and requests intervention.
+                success = _reorganize_data(session_data, acquisition_folder)
+                if not success:
+                    message = (
+                        f"Encountered issues when reorganizing {animal_name} session {session_name}. "
+                        f"User intervention is required to finish data reorganization process for this session."
+                    )
+                    # noinspection PyTypeChecker
+                    console.echo(message=message, level=LogLevel.WARNING)
+                else:
+                    # Generates the telomere.bin file to mark the session as 'complete'
+                    session_data.raw_data.telomere_path.touch()
+
+                    # If the local transfer process was successful, generates a new checksum for the moved data
+                    calculate_directory_checksum(directory=Path(session_data.raw_data.raw_data_path))
+
+                    # Next, copies the data to the BioHPC server for further processing
+                    transfer_directory(
+                        source=Path(session_data.raw_data.raw_data_path),
+                        destination=Path(
+                            server_root_directory.joinpath(project_name, animal_name, session_name, "raw_data")
+                        ),
+                        verify_integrity=False,
+                    )
+
+                    # Removes the now-empty old session data directory.
+                    acquisition_folder.rmdir()
+
+            # If the loop above removed all acquisition folders, all data for that day has been successfully converted
+            # to use the new session format. Removes the now-empty 'day' folder from the target animal
+            if len([folder for folder in session_folder.iterdir()]) == 0:
+                session_folder.rmdir()

sl_shared_assets/tools/ascension_tools.pyi

@@ -0,0 +1,68 @@
+from pathlib import Path
+
+from ..data_classes import (
+    SessionData as SessionData,
+    ProjectConfiguration as ProjectConfiguration,
+    get_system_configuration_data as get_system_configuration_data,
+)
+from .transfer_tools import transfer_directory as transfer_directory
+from .packaging_tools import calculate_directory_checksum as calculate_directory_checksum
+
+def _generate_session_name(acquisition_path: Path) -> str:
+    """Generates a session name using the last modification time of a zstack.mat or MotionEstimator.me file.
+
+    This worker function uses one of the motion estimation files stored in each Tyche 'acquisition' subfolder to
+    generate a modern Sun lab timestamp-based session name. This is used to translate the original Tyche session naming
+    pattern into the pattern used by all modern Sun lab projects and pipelines.
+
+    Args:
+        acquisition_path: The absolute path to the target acquisition folder. These folders are found under the 'day'
+            folders for each animal, e.g.: Tyche-A7/2022_01_03/1.
+
+    Returns:
+        The modernized session name.
+    """
+
+def _reorganize_data(session_data: SessionData, source_root: Path) -> bool:
+    """Reorganizes and moves the session's data from the source folder in the old Tyche data hierarchy to the raw_data
+    folder in the newly created modern hierarchy.
+
+    This worker function is used to physically rearrange the data from the original Tyche data structure to the
+    new data structure. It both moves the existing files to their new destinations and renames certain files to match
+    the modern naming convention used in the Sun lab.
+
+    Args:
+        session_data: The initialized SessionData instance managing the 'ascended' (modernized) session data hierarchy.
+        source_root: The absolute path to the old Tyche data hierarchy folder that stores session's data.
+
+    Returns:
+        True if the ascension process was successfully completed. False if the process encountered missing data or
+        otherwise did not go as expected. When the method returns False, the runtime function requests user intervention
+        to finalize the process manually.
+    """
+
+def ascend_tyche_data(root_directory: Path) -> None:
+    """Reformats the old Tyche data to use the modern Sun lab layout and metadata files.
+
+    This function is used to convert old Tyche data to the modern data management standard. This is used to make the
+    data compatible with the modern Sun lab data workflows.
+
+    Notes:
+        This function is statically written to work with the raw Tyche dataset featured in the OSM manuscript:
+        https://www.nature.com/articles/s41586-024-08548-w. Additionally, it assumes that the dataset has been
+        preprocessed with the early Sun lab mesoscope compression pipeline. The function will not work for any other
+        project or data hierarchy.
+
+        As part of its runtime, the function automatically transfers the ascended session data to the BioHPC server.
+        Since transferring the data over the network is the bottleneck of this pipeline, it runs in a single-threaded
+        mode and is constrained by the communication channel between the local machine and the BioHPC server. Calling
+        this function for a large number of sessions will result in a long processing time due to the network data
+        transfer.
+
+        Since SessionData can only be created on a PC that has a valid acquisition system config, this function will
+        only work on a machine that is part of an active Sun lab acquisition system.
+
+    Args:
+        root_directory: The directory that stores one or more Tyche animal folders. This can be conceptualized as the
+            root directory for the Tyche project.
+    """

sl_shared_assets/tools/packaging_tools.py

@@ -0,0 +1,148 @@
+"""This module provides methods for packaging session runtime data for transmission over the network. The methods from
+this module work in tandem with methods offered by transfer_tools.py to ensure the integrity of the transferred data.
+"""
+
+import os
+from pathlib import Path
+from functools import partial
+from concurrent.futures import ProcessPoolExecutor, as_completed
+
+from tqdm import tqdm
+import xxhash
+
+# Defines a 'blacklist' set of files. Primarily, this lit contains the service files that may change after the session
+# data has been acquired. Therefore, it does not make sense to include them in the checksum, as they do not reflect the
+# data that should remain permanently unchanged. Note, make sure all service files are added to this set!
+_excluded_files = {
+    "ax_checksum.txt",
+    "ubiquitin.bin",
+    "telomere.bin",
+    "single_day_suite2p.bin",
+    "multi_day_suite2p.bin",
+    "behavior.bin",
+    "dlc.bin",
+    "verified.bin",
+}
+
+
+def _calculate_file_checksum(base_directory: Path, file_path: Path) -> tuple[str, bytes]:
+    """Calculates xxHash3-128 checksum for a single file and its path relative to the base directory.
+
+    This function is passed to parallel workers used by the calculate_directory_hash() method that iteratively
+    calculates the checksum for all files inside a directory. Each call to this function returns the checksum for the
+    target file, which includes both the contents of the file and its path relative to the base directory.
+
+    Args:
+        base_directory: The path to the base (root) directory which is being checksummed by the main
+            'calculate_directory_checksum' function.
+        file_path: The absolute path to the target file.
+
+    Returns:
+        A tuple with two elements. The first element is the path to the file relative to the base directory. The second
+        element is the xxHash3-128 checksum that covers the relative path and the contents of the file.
+    """
+    # Initializes the hashsum object.
+    checksum = xxhash.xxh3_128()
+
+    # Encodes the relative path and appends it to the checksum. This ensures that the hashsum reflects both the state
+    # of individual files and the layout of the overall encoded directory structure.
+    relative_path = str(file_path.relative_to(base_directory))
+    checksum.update(relative_path.encode())
+
+    # Extends the checksum to reflect the file data state. Uses 8 MB chunks to avoid excessive RAM hogging at the cost
+    # of slightly reduced throughput.
+    with open(file_path, "rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024 * 8), b""):
+            checksum.update(chunk)
+
+    # Returns both path and file checksum. Although the relative path information is already encoded in the hashsum, the
+    # relative path information is re-encoded at the directory level to protect against future changes to the per-file
+    # hashsum calculation logic. It is extra work, but it improves the overall checksum security.
+    return relative_path, checksum.digest()
+
+
+def calculate_directory_checksum(
+    directory: Path, num_processes: int | None = None, batch: bool = False, save_checksum: bool = True
+) -> str:
+    """Calculates xxHash3-128 checksum for the input directory, which includes the data of all contained files and
+    the directory structure information.
+
+    This function is used to generate a checksum for the raw_data directory of each experiment or training session.
+    Checksums are used to verify the session data integrity during transmission between the PC that acquired the data
+    and long-term storage locations, such as the Synology NAS or the BioHPC server. The function can be configured to
+    write the generated checksum as a hexadecimal string to the ax_checksum.txt file stored at the highest level of the
+    input directory.
+
+    Note:
+        This method uses multiprocessing to efficiently parallelize checksum calculation for multiple files. In
+        combination with xxHash3, this achieves a significant speedup over more common checksums, such as MD5 and
+        SHA256. Note that xxHash3 is not suitable for security purposes and is only used to ensure data integrity.
+
+        The method notifies the user about the checksum calculation process via the terminal.
+
+        The returned checksum accounts for both the contents of each file and the layout of the input directory
+        structure.
+
+    Args:
+        directory: The Path to the directory to be checksummed.
+        num_processes: The number of CPU processes to use for parallelizing checksum calculation. If set to None, the
+            function defaults to using (logical CPU count - 4).
+        batch: Determines whether the function is called as part of batch-processing multiple directories. This is used
+            to optimize progress reporting to avoid cluttering the terminal.
+        save_checksum: Determines whether the checksum should be saved (written to) a .txt file.
+
+    Returns:
+        The xxHash3-128 checksum for the input directory as a hexadecimal string.
+    """
+    # Determines the number of parallel processes to use.
+    if num_processes is None:
+        num_processes = max(1, os.cpu_count() - 4)  # type: ignore
+
+    # Determines the path to each file inside the input directory structure and sorts them for consistency
+    path: Path
+    files = sorted(
+        path
+        for path in directory.rglob("*")
+        if path.is_file() and f"{path.stem}{path.suffix}" not in _excluded_files  # Excludes service files
+    )
+
+    # Precreates the directory checksum
+    checksum = xxhash.xxh3_128()
+
+    # Process files in parallel
+    with ProcessPoolExecutor(max_workers=num_processes) as executor:
+        # Creates the partial function with fixed base_directory (the first argument of _calculate_file_hash())
+        process_file = partial(_calculate_file_checksum, directory)
+
+        # Submits all tasks to be executed in parallel
+        # noinspection PyTypeChecker
+        future_to_path = {executor.submit(process_file, file): file for file in files}
+
+        # Collects results as they complete
+        results = []
+        if not batch:
+            with tqdm(
+                total=len(files), desc=f"Calculating checksum for {Path(*directory.parts[-6:])}", unit="files"
+            ) as pbar:
+                for future in as_completed(future_to_path):
+                    results.append(future.result())
+                    pbar.update(1)
+        else:
+            # For batch mode, uses a direct list comprehension with as_completed. This avoids the overhead of progress
+            # tracking while maintaining parallel processing, avoiding terminal clutter in batched contexts.
+            results = [future.result() for future in as_completed(future_to_path)]
+
+        # Sorts results for consistency and combines them into the final checksum
+        for file_path, file_checksum in sorted(results):
+            checksum.update(file_path.encode())
+            checksum.update(file_checksum)
+
+    checksum_hexstr = checksum.hexdigest()
+
+    # Writes the hash to ax_checksum.txt in the root directory
+    if save_checksum:
+        checksum_path = directory / "ax_checksum.txt"
+        with open(checksum_path, "w") as f:
+            f.write(checksum_hexstr)
+
+    return checksum_hexstr

sl_shared_assets/tools/packaging_tools.pyi

@@ -0,0 +1,56 @@
+from pathlib import Path
+
+from _typeshed import Incomplete
+
+_excluded_files: Incomplete
+
+def _calculate_file_checksum(base_directory: Path, file_path: Path) -> tuple[str, bytes]:
+    """Calculates xxHash3-128 checksum for a single file and its path relative to the base directory.
+
+    This function is passed to parallel workers used by the calculate_directory_hash() method that iteratively
+    calculates the checksum for all files inside a directory. Each call to this function returns the checksum for the
+    target file, which includes both the contents of the file and its path relative to the base directory.
+
+    Args:
+        base_directory: The path to the base (root) directory which is being checksummed by the main
+            'calculate_directory_checksum' function.
+        file_path: The absolute path to the target file.
+
+    Returns:
+        A tuple with two elements. The first element is the path to the file relative to the base directory. The second
+        element is the xxHash3-128 checksum that covers the relative path and the contents of the file.
+    """
+
+def calculate_directory_checksum(
+    directory: Path, num_processes: int | None = None, batch: bool = False, save_checksum: bool = True
+) -> str:
+    """Calculates xxHash3-128 checksum for the input directory, which includes the data of all contained files and
+    the directory structure information.
+
+    This function is used to generate a checksum for the raw_data directory of each experiment or training session.
+    Checksums are used to verify the session data integrity during transmission between the PC that acquired the data
+    and long-term storage locations, such as the Synology NAS or the BioHPC server. The function can be configured to
+    write the generated checksum as a hexadecimal string to the ax_checksum.txt file stored at the highest level of the
+    input directory.
+
+    Note:
+        This method uses multiprocessing to efficiently parallelize checksum calculation for multiple files. In
+        combination with xxHash3, this achieves a significant speedup over more common checksums, such as MD5 and
+        SHA256. Note that xxHash3 is not suitable for security purposes and is only used to ensure data integrity.
+
+        The method notifies the user about the checksum calculation process via the terminal.
+
+        The returned checksum accounts for both the contents of each file and the layout of the input directory
+        structure.
+
+    Args:
+        directory: The Path to the directory to be checksummed.
+        num_processes: The number of CPU processes to use for parallelizing checksum calculation. If set to None, the
+            function defaults to using (logical CPU count - 4).
+        batch: Determines whether the function is called as part of batch-processing multiple directories. This is used
+            to optimize progress reporting to avoid cluttering the terminal.
+        save_checksum: Determines whether the checksum should be saved (written to) a .txt file.
+
+    Returns:
+        The xxHash3-128 checksum for the input directory as a hexadecimal string.
+    """