spacr 1.0.9__py3-none-any.whl → 1.1.1__py3-none-any.whl

spacr/gui_utils.py

@@ -18,7 +18,20 @@ except AttributeError:
 
 def initialize_cuda():
     """
-    Initializes CUDA in the main process by performing a simple GPU operation.
+    Initializes CUDA for the main process if a compatible GPU is available.
+
+    This function checks if CUDA is available on the system. If it is, it allocates
+    a small tensor on the GPU to ensure that CUDA is properly initialized. A message
+    is printed to indicate whether CUDA was successfully initialized or if it is not
+    available.
+
+    Note:
+        This function is intended to be used in environments where CUDA-enabled GPUs
+        are present and PyTorch is installed.
+
+    Prints:
+        - "CUDA initialized in the main process." if CUDA is available and initialized.
+        - "CUDA is not available." if no compatible GPU is detected.
     """
     if torch.cuda.is_available():
         # Allocate a small tensor on the GPU
@@ -28,6 +41,27 @@ def initialize_cuda():
         print("CUDA is not available.")
 
 def set_high_priority(process):
+    """
+    Sets the priority of a given process to high.
+
+    On Windows systems, the process priority is set to HIGH_PRIORITY_CLASS.
+    On Unix-like systems, the process priority is adjusted to a higher level
+    by setting its niceness value to -10.
+
+    Args:
+        process (psutil.Process): The process whose priority is to be adjusted.
+
+    Raises:
+        psutil.AccessDenied: If the current user does not have permission to change
+                             the priority of the process.
+        psutil.NoSuchProcess: If the specified process does not exist.
+        Exception: For any other errors encountered during the operation.
+
+    Notes:
+        - This function requires the `psutil` library to interact with system processes.
+        - Adjusting process priority may require elevated privileges depending on the
+          operating system and user permissions.
+    """
     try:
         p = psutil.Process(process.pid)
         if os.name == 'nt':  # Windows
@@ -43,10 +77,49 @@ def set_high_priority(process):
         print(f"Failed to set high priority for process {process.pid}: {e}")
 
 def set_cpu_affinity(process):
+    """
+    Set the CPU affinity for a given process to use all available CPUs.
+
+    This function modifies the CPU affinity of the specified process, allowing
+    it to run on all CPUs available on the system.
+
+    Args:
+        process (psutil.Process): A psutil.Process object representing the process
+                                  whose CPU affinity is to be set.
+
+    Raises:
+        psutil.NoSuchProcess: If the process does not exist.
+        psutil.AccessDenied: If the process cannot be accessed due to insufficient permissions.
+        psutil.ZombieProcess: If the process is a zombie process.
+    """
     p = psutil.Process(process.pid)
     p.cpu_affinity(list(range(os.cpu_count())))
     
 def proceed_with_app(root, app_name, app_func):
+    """
+    Prepares the application window to load a new app by clearing the current 
+    content frame and initializing the specified app.
+
+    Args:
+        root (tk.Tk or tk.Toplevel): The root window or parent container that 
+            contains the content frame.
+        app_name (str): The name of the application to be loaded (not used in 
+            the current implementation but could be useful for logging or 
+            debugging purposes).
+        app_func (callable): A function that initializes the new application 
+            within the content frame. It should accept the content frame as 
+            its only argument.
+
+    Behavior:
+        - Destroys all widgets in the `content_frame` attribute of `root` 
+          (if it exists).
+        - Calls `app_func` with `root.content_frame` to initialize the new 
+          application.
+
+    Note:
+        Ensure that `root` has an attribute `content_frame` that is a valid 
+        tkinter container (e.g., a `tk.Frame`) before calling this function.
+    """
     # Clear the current content frame
     if hasattr(root, 'content_frame'):
         for widget in root.content_frame.winfo_children():
@@ -59,6 +132,31 @@ def proceed_with_app(root, app_name, app_func):
     app_func(root.content_frame)
 
 def load_app(root, app_name, app_func):
+    """
+    Load a new application into the GUI framework.
+
+    This function handles the transition between applications in the GUI by 
+    clearing the current canvas, canceling scheduled tasks, and invoking 
+    exit functionality for specific applications if necessary.
+
+    Args:
+        root: The root object of the GUI, which contains the canvas, 
+              after_tasks, and other application state.
+        app_name (str): The name of the application to load.
+        app_func (callable): The function to initialize the new application.
+
+    Behavior:
+        - Clears the current canvas if it exists.
+        - Cancels all scheduled `after` tasks associated with the root object.
+        - If the current application has an exit function and the new app is 
+          not "Annotate" or "make_masks", the exit function is invoked before 
+          proceeding to the new application.
+        - Proceeds to load the new application using the provided `app_func`.
+
+    Note:
+        The `proceed_with_app` function is used internally to finalize the 
+        transition to the new application.
+    """
     # Clear the canvas if it exists
     if root.canvas is not None:
         root.clear_frame(root.canvas)
@@ -184,31 +282,83 @@ def create_input_field(frame, label_text, row, var_type='entry', options=None, d
 
 def process_stdout_stderr(q):
     """
-    Redirect stdout and stderr to the queue q.
+    Redirects the standard output (stdout) and standard error (stderr) streams
+    to a queue for processing.
+
+    This function replaces the default `sys.stdout` and `sys.stderr` with
+    instances of `WriteToQueue`, which write all output to the provided queue.
+
+    :param q: A queue object where the redirected output will be stored.
+    :type q: queue.Queue
     """
     sys.stdout = WriteToQueue(q)
     sys.stderr = WriteToQueue(q)
 
 class WriteToQueue(io.TextIOBase):
     """
-    A custom file-like class that writes any output to a given queue.
-    This can be used to redirect stdout and stderr.
+    A file-like object that redirects writes to a queue.
+
+    :param q: The queue to write output to.
+    :type q: queue.Queue
     """
     def __init__(self, q):
         self.q = q
     def write(self, msg):
+        """
+        Write string to stream.
+
+        :param msg: The string message to write.
+        :type msg: str
+        :returns: Number of characters written.
+        :rtype: int
+        """
         if msg.strip():  # Avoid empty messages
             self.q.put(msg)
     def flush(self):
+        """
+        Flush write buffers, if applicable.
+
+        This is a no-op in this implementation.
+        """
         pass
 
 def cancel_after_tasks(frame):
+    """
+    Cancels all scheduled 'after' tasks associated with a given frame.
+
+    This function checks if the provided frame object has an attribute 
+    named 'after_tasks', which is expected to be a list of task IDs 
+    scheduled using the `after` method (e.g., in a Tkinter application). 
+    If such tasks exist, it cancels each of them using the `after_cancel` 
+    method and then clears the list.
+
+    Args:
+        frame: An object (typically a Tkinter widget) that may have an 
+               'after_tasks' attribute containing scheduled task IDs.
+
+    Raises:
+        AttributeError: If the frame does not have the required methods 
+                        (`after_cancel` or `after_tasks` attribute).
+    """
     if hasattr(frame, 'after_tasks'):
         for task in frame.after_tasks:
             frame.after_cancel(task)
         frame.after_tasks.clear()
 
 def load_next_app(root):
+    """
+    Loads the next application by invoking the function stored in the `next_app_func` 
+    attribute of the provided `root` object. If the current root window has been 
+    destroyed, a new root window is initialized before invoking the next application.
+
+    Args:
+        root (tk.Tk): The current root window object, which contains the attributes 
+                      `next_app_func` (a callable for the next application) and 
+                      `next_app_args` (a tuple of arguments to pass to the callable).
+
+    Raises:
+        tk.TclError: If the root window does not exist and needs to be reinitialized.
+    """
     # Get the next app function and arguments
     next_app_func = root.next_app_func
     next_app_args = root.next_app_args
@@ -228,6 +378,29 @@ def load_next_app(root):
             next_app_func(new_root, *next_app_args)
 
 def convert_settings_dict_for_gui(settings):
+    """
+    Convert a dictionary of settings into a format suitable for GUI rendering.
+
+    Each key in the input dictionary is mapped to a tuple of the form:
+    (input_type, options, default_value), where:
+    
+    - input_type (str): The type of GUI element. One of:
+        * 'combo' for dropdown menus
+        * 'check' for checkboxes
+        * 'entry' for entry fields
+    - options (list or None): A list of selectable options for 'combo' types, or None for other types.
+    - default_value: The current or default value to be displayed in the GUI.
+
+    Special keys are mapped to pre-defined configurations with known option sets
+    (e.g., 'metadata_type', 'channels', 'model_type').
+
+    :param settings: Dictionary where keys are setting names and values are their current values.
+    :type settings: dict
+
+    :return: Dictionary mapping setting names to tuples for GUI rendering.
+    :rtype: dict
+    """
+
     from torchvision import models as torch_models
     torchvision_models = [name for name, obj in torch_models.__dict__.items() if callable(obj)]
     chans = ['0', '1', '2', '3', '4', '5', '6', '7', '8', None]
@@ -280,10 +453,21 @@ def convert_settings_dict_for_gui(settings):
     
     return variables
 
-
 def spacrFigShow(fig_queue=None):
     """
-    Replacement for plt.show() that queues figures instead of displaying them.
+    Displays the current matplotlib figure or adds it to a queue.
+
+    This function retrieves the current matplotlib figure using `plt.gcf()`. 
+    If a `fig_queue` is provided, the figure is added to the queue. 
+    Otherwise, the figure is displayed using the `show()` method. 
+    After the figure is either queued or displayed, it is closed using `plt.close()`.
+
+    Args:
+        fig_queue (queue.Queue, optional): A queue to store the figure. 
+                                           If None, the figure is displayed instead.
+
+    Returns:
+        None
     """
     fig = plt.gcf()
     if fig_queue:
@@ -297,7 +481,7 @@ def function_gui_wrapper(function=None, settings={}, q=None, fig_queue=None, imp
     """
     Wraps the run_multiple_simulations function to integrate with GUI processes.
     
-    Parameters:
+    Args:
     - settings: dict, The settings for the run_multiple_simulations function.
     - q: multiprocessing.Queue, Queue for logging messages to the GUI.
     - fig_queue: multiprocessing.Queue, Queue for sending figures to the GUI.
@@ -322,7 +506,44 @@ def function_gui_wrapper(function=None, settings={}, q=None, fig_queue=None, imp
         plt.show = original_show
         
 def run_function_gui(settings_type, settings, q, fig_queue, stop_requested):
-    
+    """
+    Executes a specified processing function in the GUI context based on `settings_type`.
+
+    This function selects and runs one of the core `spaCR` processing functions 
+    (e.g., segmentation, measurement, classification, barcode mapping) based on the 
+    provided `settings_type` string. It wraps the execution with a logging mechanism 
+    to redirect stdout/stderr to the GUI console and handles exceptions cleanly.
+
+    Args
+    ----------
+    settings_type : str
+        A string indicating which processing function to execute. Supported values include:
+        'mask', 'measure', 'classify', 'train_cellpose', 'ml_analyze', 'cellpose_masks',
+        'cellpose_all', 'map_barcodes', 'regression', 'recruitment', 'analyze_plaques', 'convert'.
+
+    settings : dict
+        A dictionary of parameters required by the selected function.
+
+    q : multiprocessing.Queue
+        Queue for redirecting standard output and errors to the GUI console.
+
+    fig_queue : multiprocessing.Queue
+        Queue used to transfer figures (e.g., plots) from the worker process to the GUI.
+
+    stop_requested : multiprocessing.Value
+        A shared value to signal whether execution has completed or was interrupted.
+
+    Raises
+    ------
+    ValueError
+        If an invalid `settings_type` is provided.
+
+    Notes
+    -----
+    - Redirects stdout/stderr to the GUI using `process_stdout_stderr`.
+    - Catches and reports any exceptions to the GUI queue.
+    - Sets `stop_requested.value = 1` when the task finishes (whether successful or not).
+    """
     from .core import preprocess_generate_masks
     from .spacr_cellpose import identify_masks_finetune, check_cellpose_models
     from .submodules import analyze_recruitment
@@ -387,7 +608,7 @@ def hide_all_settings(vars_dict, categories):
     """
     Function to initially hide all settings in the GUI.
 
-    Parameters:
+    Args:
     - categories: dict, The categories of settings with their corresponding settings.
     - vars_dict: dict, The dictionary containing the settings and their corresponding widgets.
     """
@@ -409,6 +630,32 @@ def hide_all_settings(vars_dict, categories):
     return vars_dict
 
 def setup_frame(parent_frame):
+    """
+    Set up the main GUI layout within the given parent frame.
+
+    This function initializes a dark-themed, resizable GUI layout using `PanedWindow` 
+    containers. It organizes the layout into left-hand settings, central vertical content, 
+    and bottom horizontal panels. It also sets initial sash positions and layout weights.
+
+    Args
+    ----------
+    parent_frame : tk.Frame
+        The parent Tkinter frame to populate with the GUI layout.
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - parent_frame (tk.Frame): The modified parent frame with the layout initialized.
+        - vertical_container (tk.PanedWindow): Top container in the right-hand area for main content.
+        - horizontal_container (tk.PanedWindow): Bottom container for additional widgets.
+        - settings_container (tk.PanedWindow): Left-hand container for GUI settings.
+    
+    Notes
+    -----
+    - Uses `set_dark_style` and `set_element_size` from `gui_elements` to theme and size widgets.
+    - Dynamically positions the sash between the left and right panes to 25% of the screen width.
+    """
     from .gui_elements import set_dark_style, set_element_size
 
     style = ttk.Style(parent_frame)
@@ -457,8 +704,29 @@ def setup_frame(parent_frame):
 
     return parent_frame, vertical_container, horizontal_container, settings_container
 
-
 def download_hug_dataset(q, vars_dict):
+    """
+    Downloads a dataset and settings files from the Hugging Face Hub and updates the provided variables dictionary.
+
+    Args:
+        q (queue.Queue): A queue object used for logging messages during the download process.
+        vars_dict (dict): A dictionary containing variables to be updated. If 'src' is present in the dictionary,
+                          the third element of 'src' will be updated with the downloaded dataset path.
+
+    The function performs the following steps:
+        1. Downloads a dataset from the Hugging Face Hub using the specified repository ID and subfolder.
+        2. Updates the 'src' variable in `vars_dict` with the local path of the downloaded dataset, if applicable.
+        3. Logs the dataset download status to the provided queue.
+        4. Downloads settings files from another repository on the Hugging Face Hub.
+        5. Logs the settings download status to the provided queue.
+
+    Notes:
+        - The dataset is downloaded to a local directory under the user's home directory named "datasets".
+        - Any exceptions during the download process are caught and logged to the queue.
+
+    Raises:
+        None: All exceptions are handled internally and logged to the queue.
+    """
     dataset_repo_id = "einarolafsson/toxo_mito"
     settings_repo_id = "einarolafsson/spacr_settings"
     dataset_subfolder = "plate1"
@@ -629,6 +897,31 @@ def display_gif_in_plot_frame(gif_path, parent_frame):
     update_frame(0)
     
 def display_media_in_plot_frame(media_path, parent_frame):
+    """
+    Display a media file (MP4, AVI, or GIF) in a Tkinter frame, playing it on repeat 
+    while fully filling the frame and maintaining the aspect ratio.
+
+    Args:
+        media_path (str): The file path to the media file (MP4, AVI, or GIF).
+        parent_frame (tk.Frame): The Tkinter frame where the media will be displayed.
+
+    Behavior:
+        - For MP4 and AVI files:
+            - Uses OpenCV to read and play the video.
+            - Resizes and crops the video to fully fill the parent frame while maintaining aspect ratio.
+            - Plays the video on repeat.
+        - For GIF files:
+            - Uses PIL to read and play the GIF.
+            - Resizes and crops the GIF to fully fill the parent frame while maintaining aspect ratio.
+            - Plays the GIF on repeat.
+
+    Raises:
+        ValueError: If the file format is not supported (only MP4, AVI, and GIF are supported).
+
+    Notes:
+        - The function clears any existing widgets in the parent frame before displaying the media.
+        - The parent frame is configured to expand and adapt to the media's aspect ratio.
+    """
     """Display an MP4, AVI, or GIF and play it on repeat in the parent_frame, fully filling the frame while maintaining aspect ratio."""
     # Clear parent_frame if it contains any previous widgets
     for widget in parent_frame.winfo_children():
@@ -773,8 +1066,7 @@ def display_media_in_plot_frame(media_path, parent_frame):
     else:
         raise ValueError("Unsupported file format. Only .mp4, .avi, and .gif are supported.")
 
-def print_widget_structure(widget, indent=0):
-    """Recursively print the widget structure."""
+def print_widget_structure(widget, indent=0):    
     # Print the widget's name and class
     print(" " * indent + f"{widget}: {widget.winfo_class()}")