dragon-ml-toolbox 3.7.0__py3-none-any.whl → 3.8.0__py3-none-any.whl

{dragon_ml_toolbox-3.7.0.dist-info → dragon_ml_toolbox-3.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dragon-ml-toolbox
-Version: 3.7.0
+Version: 3.8.0
 Summary: A collection of tools for data science and machine learning projects.
 Author-email: Karl Loza <luigiloza@gmail.com>
 License-Expression: MIT

{dragon_ml_toolbox-3.7.0.dist-info → dragon_ml_toolbox-3.8.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
-dragon_ml_toolbox-3.7.0.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
-dragon_ml_toolbox-3.7.0.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=6cfpIeQ6D4Mcs10nkogQrkVyq1T7i2qXjjNHFoUMOyE,1892
+dragon_ml_toolbox-3.8.0.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
+dragon_ml_toolbox-3.8.0.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=6cfpIeQ6D4Mcs10nkogQrkVyq1T7i2qXjjNHFoUMOyE,1892
 ml_tools/ETL_engineering.py,sha256=yeZsW_7zRvEcuMZbM4E2GV1dxwBoWIeJAcFFk2AK0fY,39502
-ml_tools/GUI_tools.py,sha256=3kRxok-QCN5S0q1i7yK137Bsr6c2N4M4nIvgPVAuZU0,20371
+ml_tools/GUI_tools.py,sha256=z0CbN8zOC9bSGxOwcf539gSmvXyn-xP5xXHPxWiywMI,17920
 ml_tools/MICE_imputation.py,sha256=rYqvwQDVtoAJJ0agXWoGzoZEHedWiA6QzcEKEIkiZ08,11388
 ml_tools/ML_callbacks.py,sha256=OT2zwORLcn49megBEgXsSUxDHoW0Ft0_v7hLEVF3jHM,13063
 ml_tools/ML_evaluation.py,sha256=oiDV6HItQloUUKCUpltV-2pogubWLBieGpc-VUwosAQ,10106
@@ -18,8 +18,8 @@ ml_tools/datasetmaster.py,sha256=S3PKHNQZ9cyAOck8xQltVLZhaD1gFLfgHFL-aRjz4JU,300
 ml_tools/ensemble_learning.py,sha256=CDSIygnHaNe92aJ46Fofevd7q6lowTnE98yWuIV3Y6w,37462
 ml_tools/handle_excel.py,sha256=lwds7rDLlGSCWiWGI7xNg-Z7kxAepogp0lstSFa0590,12949
 ml_tools/logger.py,sha256=UkbiU9ihBhw9VKyn3rZzisdClWV94EBV6B09_D0iUU0,6026
-ml_tools/utilities.py,sha256=0w0vka0Aj9IYOHJ6crWIb6gwpQIJnPyj3v2_dnVxHrs,23138
-dragon_ml_toolbox-3.7.0.dist-info/METADATA,sha256=kvgFjd_BRwob7xycC5rbROCkq4C6FVq3J5-VdCXEPrI,3273
-dragon_ml_toolbox-3.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dragon_ml_toolbox-3.7.0.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
-dragon_ml_toolbox-3.7.0.dist-info/RECORD,,
+ml_tools/utilities.py,sha256=ghEOhN5-eozgfDjJ0r8qOBlnDYahn3jaYzfnitL-GDU,31375
+dragon_ml_toolbox-3.8.0.dist-info/METADATA,sha256=FBhxslY5Lx2HlauipzYsoPovFSdGqlYjgaN0oRVxfLk,3273
+dragon_ml_toolbox-3.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dragon_ml_toolbox-3.8.0.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
+dragon_ml_toolbox-3.8.0.dist-info/RECORD,,

ml_tools/GUI_tools.py

@@ -4,14 +4,13 @@ from typing import Optional, Callable, Any
 import traceback
 import FreeSimpleGUI as sg
 from functools import wraps
-from typing import Any, Dict, Tuple, List
+from typing import Any, Dict, Tuple, List, Literal
 from .utilities import _script_info
 import numpy as np
 from .logger import _LOGGER
 
 
 __all__ = [
-    "PathManager", 
     "ConfigManager", 
     "GUIFactory",
     "catch_exceptions", 
@@ -19,68 +18,6 @@ __all__ = [
     "update_target_fields"
 ]
 
-
-# --- Path Management ---
-class PathManager:
-    """
-    Manages paths for a Python application, supporting both development mode and bundled mode via Briefcase.
-    """
-    def __init__(self, anchor_file: str):
-        """
-        Initializes the PathManager. The package name is automatically inferred
-        from the parent directory of the anchor file.
-
-        Args:
-            anchor_file (str): The absolute path to a file within the project's
-                               package, typically `__file__` from a module inside
-                               that package (paths.py).
-
-        Note:
-            This inference assumes that the anchor file's parent directory
-            has the same name as the package (e.g., `.../src/my_app/paths.py`).
-            This is a standard and recommended project structure.
-        """
-        resolved_anchor_path = Path(anchor_file).resolve()
-        self.package_name = resolved_anchor_path.parent.name
-        self._is_bundled, self._resource_path_func = self._check_bundle_status()
-
-        if self._is_bundled:
-            # In a Briefcase bundle, resource_path gives an absolute path
-            # to the resource directory.
-            self.package_root = self._resource_path_func(self.package_name, "") # type: ignore
-        else:
-            # In development mode, the package root is the directory
-            # containing the anchor file.
-            self.package_root = resolved_anchor_path.parent
-
-    def _check_bundle_status(self) -> tuple[bool, Optional[Callable]]:
-        """Checks if the app is running in a bundled environment."""
-        try:
-            # This is the function Briefcase provides in a bundled app
-            from briefcase.platforms.base import resource_path # type: ignore
-            return True, resource_path
-        except ImportError:
-            return False, None
-
-    def get_path(self, relative_path: str | Path) -> Path:
-        """
-        Gets the absolute path for a given resource file or directory
-        relative to the package root.
-
-        Args:
-            relative_path (str | Path): The path relative to the package root (e.g., 'helpers/icon.png').
-
-        Returns:
-            Path: The absolute path to the resource.
-        """
-        if self._is_bundled:
-            # Briefcase's resource_path handles resolving the path within the app bundle 
-            return self._resource_path_func(self.package_name, str(relative_path)) # type: ignore
-        else:
-            # In dev mode, join package root with the relative path.
-            return self.package_root / relative_path
-
-
 # --- Configuration Management ---
 class _SectionProxy:
     """A helper class to represent a section of the .ini file as an object."""
@@ -273,8 +210,8 @@ class GUIFactory:
         self,
         data_dict: Dict[str, Tuple[float, float]],
         is_target: bool = False,
-        layout_mode: str = 'grid',
-        columns_per_row: int = 4
+        layout_mode: Literal["grid", "row"] = 'grid',
+        features_per_column: int = 4
     ) -> List[List[sg.Column]]:
         """
         Generates a layout for continuous features or targets.
@@ -283,7 +220,7 @@ class GUIFactory:
             data_dict (dict): Keys are feature names, values are (min, max) tuples.
             is_target (bool): If True, creates disabled inputs for displaying results.
             layout_mode (str): 'grid' for a multi-row grid layout, or 'row' for a single horizontal row.
-            columns_per_row (int): Number of feature columns per row when layout_mode is 'grid'.
+            features_per_column (int): Number of features per column when `layout_mode` is 'grid'.
 
         Returns:
             A list of lists of sg.Column elements, ready to be used in a window layout.
@@ -294,7 +231,7 @@ class GUIFactory:
         
         columns = []
         for name, (val_min, val_max) in data_dict.items():
-            key = f"TARGET_{name}" if is_target else name
+            key = name
             default_text = "" if is_target else str(val_max)
             
             label = sg.Text(name, font=label_font, background_color=bg_color, key=f"_text_{name}")
@@ -313,6 +250,7 @@ class GUIFactory:
                 range_text = sg.Text(f"Range: {int(val_min)}-{int(val_max)}", font=range_font, background_color=bg_color)
                 layout = [[label], [element], [range_text]]
             
+            # each feature is wrapped as a column element
             layout.append([sg.Text(" ", font=(cfg.fonts.font_family, 2), background_color=bg_color)]) # type: ignore
             columns.append(sg.Column(layout, background_color=bg_color))
 
@@ -320,13 +258,13 @@ class GUIFactory:
             return [columns] # A single row containing all columns
         
         # Default to 'grid' layout
-        return [columns[i:i + columns_per_row] for i in range(0, len(columns), columns_per_row)]
+        return [columns[i:i + features_per_column] for i in range(0, len(columns), features_per_column)]
 
     def generate_combo_layout(
         self,
         data_dict: Dict[str, List[Any]],
-        layout_mode: str = 'grid',
-        columns_per_row: int = 4
+        layout_mode: Literal["grid", "row"] = 'grid',
+        features_per_column: int = 4
     ) -> List[List[sg.Column]]:
         """
         Generates a layout for categorical or binary features using Combo boxes.
@@ -334,7 +272,7 @@ class GUIFactory:
         Args:
             data_dict (dict): Keys are feature names, values are lists of options.
             layout_mode (str): 'grid' for a multi-row grid layout, or 'row' for a single horizontal row.
-            columns_per_row (int): Number of feature columns per row when layout_mode is 'grid'.
+            features_per_column (int): Number of features per column when `layout_mode` is 'grid'.
 
         Returns:
             A list of lists of sg.Column elements, ready to be used in a window layout.
@@ -352,13 +290,14 @@ class GUIFactory:
             )
             layout = [[label], [element]]
             layout.append([sg.Text(" ", font=(cfg.fonts.font_family, 2), background_color=bg_color)]) # type: ignore
+            # each feature is wrapped in a Column element
             columns.append(sg.Column(layout, background_color=bg_color))
 
         if layout_mode == 'row':
             return [columns] # A single row containing all columns
             
         # Default to 'grid' layout
-        return [columns[i:i + columns_per_row] for i in range(0, len(columns), columns_per_row)]
+        return [columns[i:i + features_per_column] for i in range(0, len(columns), features_per_column)]
 
     # --- Window Creation ---
     def create_window(self, title: str, layout: List[List[sg.Element]], **kwargs) -> sg.Window:
@@ -421,8 +360,8 @@ def _default_categorical_processor(feature_name: str, chosen_value: Any) -> List
     return [1.0] if str(chosen_value) == 'True' else [0.0]
 
 def prepare_feature_vector(
-    values: Dict[str, Any],
-    feature_order: List[str],
+    window_values: Dict[str, Any],
+    gui_feature_order: List[str],
     continuous_features: List[str],
     categorical_features: List[str],
     categorical_processor: Optional[Callable[[str, Any], List[float]]] = None
@@ -432,8 +371,8 @@ def prepare_feature_vector(
     This function supports label encoding and one-hot encoding via the processor.
 
     Args:
-        values (dict): The values dictionary from a `window.read()` call.
-        feature_order (list): A list of all feature names that have a GUI element.
+        window_values (dict): The values dictionary from a `window.read()` call.
+        gui_feature_order (list): A list of all feature names that have a GUI element.
                               For one-hot encoding, this should be the name of the
                               single GUI element (e.g., 'material_type'), not the
                               expanded feature names (e.g., 'material_is_steel').
@@ -456,8 +395,8 @@ def prepare_feature_vector(
     cont_set = set(continuous_features)
     cat_set = set(categorical_features)
 
-    for name in feature_order:
-        chosen_value = values.get(name)
+    for name in gui_feature_order:
+        chosen_value = window_values.get(name)
         
         if chosen_value is None or chosen_value == '':
             raise ValueError(f"Feature '{name}' is missing a value.")
@@ -482,12 +421,12 @@ def update_target_fields(window: sg.Window, results_dict: Dict[str, Any]):
 
     Args:
         window (sg.Window): The application's window object.
-        results_dict (dict): A dictionary where keys are target key names (including 'TARGET_' prefix if necessary) and values are the predicted results.
+        results_dict (dict): A dictionary where keys are target element-keys and values are the predicted results to update.
     """
     for target_name, result in results_dict.items():
         # Format numbers to 2 decimal places, leave other types as-is
         display_value = f"{result:.2f}" if isinstance(result, (int, float)) else result
-        window[target_name].update(display_value)
+        window[target_name].update(display_value) # type: ignore
 
 
 def info():

ml_tools/utilities.py

@@ -4,9 +4,10 @@ import pandas as pd
 import polars as pl
 from pathlib import Path
 import re
-from typing import Literal, Union, Sequence, Optional, Any, Iterator, Tuple
+from typing import Literal, Union, Sequence, Optional, Any, Iterator, Tuple, Callable, List, Dict
 import joblib
 from joblib.externals.loky.process_executor import TerminatedWorkerError
+from pprint import pprint
 
 
 # Keep track of available tools
@@ -25,7 +26,8 @@ __all__ = [
     "serialize_object",
     "deserialize_object",
     "distribute_datasets_by_target",
-    "train_dataset_orchestrator"
+    "train_dataset_orchestrator",
+    "PathManager"
 ]
 
 
@@ -643,9 +645,211 @@ def train_dataset_orchestrator(list_of_dirs: list[Union[str,Path]],
     print(f"\n✅ {total_saved} single-target datasets were created.")
 
 
+### Path Manager
+class PathManager:
+    """
+    Manages and stores a project's file paths, acting as a centralized
+    "path database". It supports both development mode and applications
+    bundled with Briefcase.
+    
+    Supports python dictionary syntax.
+    """
+    def __init__(
+        self,
+        anchor_file: str,
+        base_directories: Optional[List[str]] = None
+    ):
+        """
+        The initializer determines the project's root directory and can pre-register
+        a list of base directories relative to that root.
+
+        Args:
+            anchor_file (str): The absolute path to a file whose parent directory will be considered the package root and name. Typically, `__file__`.
+            base_directories (Optional[List[str]]): A list of directory names
+                                located at the same level as the anchor file's
+                                parent directory to register immediately.
+        """
+        resolved_anchor_path = Path(anchor_file).resolve()
+        self._package_name = resolved_anchor_path.parent.name
+        self._is_bundled, self._resource_path_func = self._check_bundle_status()
+        self._paths: Dict[str, Path] = {}
+
+        if self._is_bundled:
+            # In a bundle, resource_path gives the absolute path to the 'app_packages' dir
+            # when given the package name.
+            package_root = self._resource_path_func(self._package_name) # type: ignore
+        else:
+            # In dev mode, the package root is the directory containing the anchor file.
+            package_root = resolved_anchor_path.parent
+
+        # Register the root of the package itself
+        self._paths["ROOT"] = package_root
+
+        # Register all the base directories
+        if base_directories:
+            for dir_name in base_directories:
+                # In dev mode, this is simple. In a bundle, we must resolve
+                # each path from the package root.
+                if self._is_bundled:
+                     self._paths[dir_name] = self._resource_path_func(self._package_name, dir_name) # type: ignore
+                else:
+                     self._paths[dir_name] = package_root / dir_name
+                     
+    # A helper function to find the briefcase-injected resource function
+    def _check_bundle_status(self) -> tuple[bool, Optional[Callable]]:
+        """Checks if the app is running in a Briefcase bundle."""
+        try:
+            # This function is injected by Briefcase into the global scope
+            from briefcase.platforms.base import resource_path # type: ignore
+            return True, resource_path
+        except (ImportError, NameError):
+            return False, None
+
+    def get(self, key: str) -> Path:
+        """
+        Retrieves a stored path by its key.
+
+        Args:
+            key (str): The key of the path to retrieve.
+
+        Returns:
+            Path: The resolved, absolute Path object.
+
+        Raises:
+            KeyError: If the key is not found in the manager.
+        """
+        try:
+            return self._paths[key]
+        except KeyError:
+            print(f"❌ Path key '{key}' not found.")
+            # Consider suggesting close matches if you want to get fancy
+            raise
+
+    def update(self, new_paths: Dict[str, Union[str, Path]], overwrite: bool = False) -> None:
+        """
+        Adds new paths or overwrites existing ones in the manager.
+
+        Args:
+            new_paths (Dict[str, Union[str, Path]]): A dictionary where keys are
+                                    the identifiers and values are the
+                                    Path objects or strings to store.
+            overwrite (bool): If False (default), raises a KeyError if any
+                            key in new_paths already exists. If True,
+                            allows overwriting existing keys.
+        """
+        if not overwrite:
+            for key in new_paths:
+                if key in self._paths:
+                    raise KeyError(
+                        f"Path key '{key}' already exists in the manager. To replace it, call update() with overwrite=True."
+                    )
+
+        # Resolve any string paths to Path objects before storing
+        resolved_new_paths = {k: Path(v) for k, v in new_paths.items()}
+        self._paths.update(resolved_new_paths)
+        
+    def make_dirs(self, keys: Optional[List[str]] = None, verbose: bool = False) -> None:
+        """
+        Creates directory structures for registered paths in writable locations.
+
+        This method identifies paths that are directories (no file suffix) and creates them on the filesystem.
+
+        In a bundled application, this method will NOT attempt to create directories inside the read-only app package, preventing crashes. It
+        will only operate on paths outside of the package (e.g., user data dirs).
+
+        Args:
+            keys (Optional[List[str]]): If provided, only the directories
+                                        corresponding to these keys will be
+                                        created. If None (default), all
+                                        registered directory paths are used.
+            verbose (bool): If True, prints a message for each action.
+        """
+        path_items = []
+        if keys:
+            for key in keys:
+                if key in self._paths:
+                    path_items.append((key, self._paths[key]))
+                elif verbose:
+                    print(f"⚠️ Key '{key}' not found in PathManager, skipping.")
+        else:
+            path_items = self._paths.items()
+
+        # Get the package root to check against.
+        package_root = self._paths.get("ROOT")
+
+        for key, path in path_items:
+            if path.suffix:  # It's a file, not a directory
+                continue
+
+            # --- THE CRITICAL CHECK ---
+            # Determine if the path is inside the main application package.
+            is_internal_path = package_root and path.is_relative_to(package_root)
+
+            if self._is_bundled and is_internal_path:
+                if verbose:
+                    print(f"ℹ️ Skipping internal directory '{key}' in bundled app (read-only).")
+                continue
+            # -------------------------
+
+            if verbose:
+                print(f"📁 Ensuring directory exists for key '{key}': {path}")
+
+            path.mkdir(parents=True, exist_ok=True)
+            
+    def status(self) -> None:
+        """
+        Checks the status of all registered paths on the filesystem and prints a formatted report.
+        """
+        report = {}
+        for key, path in self.items():
+            if path.is_dir():
+                report[key] = "📁 Directory"
+            elif path.is_file():
+                report[key] = "📄 File"
+            else:
+                report[key] = "❌ Not Found"
+
+        print("\n--- Path Status Report ---")
+        pprint(report)
+
+    def __repr__(self) -> str:
+        """Provides a string representation of the stored paths."""
+        path_list = "\n".join(f"  '{k}': '{v}'" for k, v in self._paths.items())
+        return f"PathManager(\n{path_list}\n)"
+    
+    # --- Dictionary-Style Methods ---
+    def __getitem__(self, key: str) -> Path:
+        """Allows dictionary-style getting, e.g., PM['my_key']"""
+        return self.get(key)
+
+    def __setitem__(self, key: str, value: Union[str, Path]):
+        """Allows dictionary-style setting, e.g., PM['my_key'] = path"""
+        self.update({key: value}, overwrite=True)
+
+    def __contains__(self, key: str) -> bool:
+        """Allows checking for a key's existence, e.g., if 'my_key' in PM"""
+        return key in self._paths
+
+    def __len__(self) -> int:
+        """Allows getting the number of paths, e.g., len(PM)"""
+        return len(self._paths)
+
+    def keys(self):
+        """Returns all registered path keys."""
+        return self._paths.keys()
+
+    def values(self):
+        """Returns all registered Path objects."""
+        return self._paths.values()
+
+    def items(self):
+        """Returns all registered (key, Path) pairs."""
+        return self._paths.items()
+
+
 class LogKeys:
     """
-    Used for ML scripts only
+    Used internally for ML scripts.
     
     Centralized keys for logging and history.
     """