dragon-ml-toolbox 12.11.0__py3-none-any.whl → 12.12.0__py3-none-any.whl

{dragon_ml_toolbox-12.11.0.dist-info → dragon_ml_toolbox-12.12.0.dist-info}/METADATA

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

{dragon_ml_toolbox-12.11.0.dist-info → dragon_ml_toolbox-12.12.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
-dragon_ml_toolbox-12.11.0.dist-info/licenses/LICENSE,sha256=L35WDmmLZNTlJvxF6Vy7Uy4SYNi6rCfWUqlTHpoRMoU,1081
-dragon_ml_toolbox-12.11.0.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=iy2r_R7wjzsCbz_Q_jMsp_jfZ6oP8XW9QhwzRBH0mGY,1904
+dragon_ml_toolbox-12.12.0.dist-info/licenses/LICENSE,sha256=L35WDmmLZNTlJvxF6Vy7Uy4SYNi6rCfWUqlTHpoRMoU,1081
+dragon_ml_toolbox-12.12.0.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=iy2r_R7wjzsCbz_Q_jMsp_jfZ6oP8XW9QhwzRBH0mGY,1904
 ml_tools/ETL_cleaning.py,sha256=2VBRllV8F-ZiPylPp8Az2gwn5ztgazN0BH5OKnRUhV0,20402
 ml_tools/ETL_engineering.py,sha256=KfYqgsxupAx6e_TxwO1LZXeu5mFkIhVXJrNjP3CzIZc,54927
 ml_tools/GUI_tools.py,sha256=Va6ig-dHULPVRwQYYtH3fvY5XPIoqRcJpRW8oXC55Hw,45413
 ml_tools/MICE_imputation.py,sha256=X273Qlgoqqg7KTmoKd75YDyAPB0UIbTzGP3xsCmRh3E,11717
-ml_tools/ML_callbacks.py,sha256=-XRIZEy3CPJWTHcoReyIw53FZlTs3pWcTVVnncTQQSc,13909
-ml_tools/ML_datasetmaster.py,sha256=t6q6mU9lz2rYKTVPKjA7yZ5ImV7_NykiciHaYnqIEpA,30822
+ml_tools/ML_callbacks.py,sha256=2ZazJjlbClP-ALc8q0ru2oalkugbhO3TFwPg4RFZpck,14056
+ml_tools/ML_datasetmaster.py,sha256=kedCGneR3S2zui0_JFZN6TBL5e69XWkdpkE_QohyqSM,31433
 ml_tools/ML_evaluation.py,sha256=tLswOPgH4G1KExSMn0876YtNkbxPh-W3J4MYOjomMWA,16208
 ml_tools/ML_evaluation_multi.py,sha256=6OZyQ4SM9ALh38mOABmiHgIQDWcovsD_iOo7Bg9YZCE,12516
 ml_tools/ML_inference.py,sha256=ymFvncFsU10PExq87xnEj541DKV5ck0nMuK8ToJHzVQ,23067
-ml_tools/ML_models.py,sha256=pSCV6KbmVnPZr49Kbyg7g25CYaWBWJr6IinBHKgVKGw,28042
+ml_tools/ML_models.py,sha256=G64NPhYZfYvHTIUwkIrMrNLgfDTKJwqdc8jwesPqB9E,28090
 ml_tools/ML_optimization.py,sha256=es3TlQbY7RYgJMZnznkjYGbUxFnAqzZxE_g3_qLK9Q8,22960
 ml_tools/ML_scaler.py,sha256=tw6onj9o8_kk3FQYb930HUzvv1zsFZe2YZJdF3LtHkU,7538
 ml_tools/ML_simple_optimization.py,sha256=W2mce1XFCuiOHTOjOsCNbETISHn5MwYlYsTIXH5hMMo,18177
@@ -35,7 +35,7 @@ ml_tools/optimization_tools.py,sha256=P074YCuZzkqkONnAsM-Zb9DTX_i8cRkkJLpwAWz6CR
 ml_tools/path_manager.py,sha256=CyDU16pOKmC82jPubqJPT6EBt-u-3rGVbxyPIZCvDDY,18432
 ml_tools/serde.py,sha256=ll2mVC0sO2jIEdG3K6xMcgEN13N4YSb8VjviGvw_ers,4949
 ml_tools/utilities.py,sha256=OcAyV1tEcYAfOWlGjRgopsjDLxU3DcI5EynzvWV4q3A,15754
-dragon_ml_toolbox-12.11.0.dist-info/METADATA,sha256=VOs19HzZ0j8xvEuKO9sIMDCGIPPQA22x3Lnh2H9Mw9c,6167
-dragon_ml_toolbox-12.11.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dragon_ml_toolbox-12.11.0.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
-dragon_ml_toolbox-12.11.0.dist-info/RECORD,,
+dragon_ml_toolbox-12.12.0.dist-info/METADATA,sha256=PKf7t2ojMJs9-6STvqebRBxS_1rWPv58ff0BqPk2d_A,6167
+dragon_ml_toolbox-12.12.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dragon_ml_toolbox-12.12.0.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
+dragon_ml_toolbox-12.12.0.dist-info/RECORD,,

ml_tools/ML_callbacks.py

@@ -113,18 +113,19 @@ class TqdmProgressBar(Callback):
 class EarlyStopping(Callback):
     """
     Stop training when a monitored metric has stopped improving.
-    
-    Args:
-        monitor (str): Quantity to be monitored. Defaults to 'val_loss'.
-        min_delta (float): Minimum change in the monitored quantity to qualify as an improvement.
-        patience (int): Number of epochs with no improvement after which training will be stopped.
-        mode (str): One of {'auto', 'min', 'max'}. In 'min' mode, training will stop when the quantity
-                    monitored has stopped decreasing; in 'max' mode it will stop when the quantity
-                    monitored has stopped increasing; in 'auto' mode, the direction is automatically
-                    inferred from the name of the monitored quantity.
-        verbose (int): Verbosity mode.
     """
     def __init__(self, monitor: str=PyTorchLogKeys.VAL_LOSS, min_delta: float=0.0, patience: int=5, mode: Literal['auto', 'min', 'max']='auto', verbose: int=1):
+        """
+        Args:
+            monitor (str): Quantity to be monitored. Defaults to 'val_loss'.
+            min_delta (float): Minimum change in the monitored quantity to qualify as an improvement.
+            patience (int): Number of epochs with no improvement after which training will be stopped.
+            mode (str): One of {'auto', 'min', 'max'}. In 'min' mode, training will stop when the quantity
+                        monitored has stopped decreasing; in 'max' mode it will stop when the quantity
+                        monitored has stopped increasing; in 'auto' mode, the direction is automatically
+                        inferred from the name of the monitored quantity.
+            verbose (int): Verbosity mode.
+        """
         super().__init__()
         self.monitor = monitor
         self.patience = patience
@@ -188,22 +189,23 @@ class EarlyStopping(Callback):
 
 class ModelCheckpoint(Callback):
     """
-    Saves the model to a directory with automated filename generation and rotation. The filename includes the epoch and score.
-
-    - If `save_best_only` is True, it saves the single best model, deleting the
-      previous best. 
-    - If `save_best_only` is False, it keeps the 3 most recent checkpoints,
-      deleting the oldest ones automatically.
-
-    Args:
-        save_dir (str): Directory where checkpoint files will be saved.
-        monitor (str): Metric to monitor for `save_best_only=True`.
-        save_best_only (bool): If true, save only the best model.
-        mode (str): One of {'auto', 'min', 'max'}.
-        verbose (int): Verbosity mode.
+    Saves the model weights to a directory with automated filename generation and rotation. 
     """
     def __init__(self, save_dir: Union[str,Path], checkpoint_name: Optional[str]=None, monitor: str = PyTorchLogKeys.VAL_LOSS,
                  save_best_only: bool = True, mode: Literal['auto', 'min', 'max']= 'auto', verbose: int = 0):
+        """
+        - If `save_best_only` is True, it saves the single best model, deleting the previous best. 
+        - If `save_best_only` is False, it keeps the 3 most recent checkpoints, deleting the oldest ones automatically.
+
+        Args:
+            save_dir (str): Directory where checkpoint files will be saved.
+            checkpoint_name (str| None): If None, the filename will include the epoch and score.
+            monitor (str): Metric to monitor for `save_best_only=True`.
+            save_best_only (bool): If true, save only the best model.
+            mode (str): One of {'auto', 'min', 'max'}.
+            verbose (int): Verbosity mode.
+        """
+        
         super().__init__()
         self.save_dir = make_fullpath(save_dir, make=True, enforce="directory")
         if not self.save_dir.is_dir():
@@ -306,17 +308,16 @@ class ModelCheckpoint(Callback):
 class LRScheduler(Callback):
     """
     Callback to manage a PyTorch learning rate scheduler.
-
-    This callback automatically calls the scheduler's `step()` method at the
-    end of each epoch. It also logs a message when the learning rate changes.
-
-    Args:
-        scheduler: An initialized PyTorch learning rate scheduler.
-        monitor (str, optional): The metric to monitor for schedulers that
-                                 require it, like `ReduceLROnPlateau`.
-                                 Should match a key in the logs (e.g., 'val_loss').
     """
     def __init__(self, scheduler, monitor: Optional[str] = None):
+        """
+        This callback automatically calls the scheduler's `step()` method at the
+        end of each epoch. It also logs a message when the learning rate changes.
+
+        Args:
+            scheduler: An initialized PyTorch learning rate scheduler.
+            monitor (str, optional): The metric to monitor for schedulers that require it, like `ReduceLROnPlateau`. Should match a key in the logs (e.g., 'val_loss').
+        """
         super().__init__()
         self.scheduler = scheduler
         self.monitor = monitor

ml_tools/ML_datasetmaster.py

@@ -81,8 +81,7 @@ class _PytorchDataset(Dataset):
             _LOGGER.error(f"Dataset {self.__class__} has not been initialized with any target names.")
 
 
-# --- Abstract Base Class (New) ---
-# --- Abstract Base Class (Corrected) ---
+# --- Abstract Base Class ---
 class _BaseDatasetMaker(ABC):
     """
     Abstract base class for dataset makers. Contains shared logic for
@@ -150,6 +149,14 @@ class _BaseDatasetMaker(ABC):
     @property
     def target_names(self) -> list[str]:
         return self._target_names
+    
+    @property
+    def number_of_features(self) -> int:
+        return len(self._feature_names)
+    
+    @property
+    def number_of_targets(self) -> int:
+        return len(self._target_names)
 
     @property
     def id(self) -> Optional[str]:
@@ -180,14 +187,14 @@ class _BaseDatasetMaker(ABC):
                           filename=DatasetKeys.TARGET_NAMES,
                           verbose=verbose)
 
-    def save_scaler(self, save_dir: Union[str, Path], verbose: bool=True) -> None:
+    def save_scaler(self, directory: Union[str, Path], verbose: bool=True) -> None:
         """
         Saves the fitted PytorchScaler's state to a .pth file.
 
         The filename is automatically generated based on the dataset id.
         
         Args:
-            save_dir (str | Path): The directory where the scaler will be saved.
+            directory (str | Path): The directory where the scaler will be saved.
         """
         if not self.scaler: 
             _LOGGER.error("No scaler was fitted or provided.")
@@ -195,7 +202,7 @@ class _BaseDatasetMaker(ABC):
         if not self.id: 
             _LOGGER.error("Must set the dataset `id` before saving scaler.")
             raise ValueError()
-        save_path = make_fullpath(save_dir, make=True, enforce="directory")
+        save_path = make_fullpath(directory, make=True, enforce="directory")
         sanitized_id = sanitize_filename(self.id)
         filename = f"{DatasetKeys.SCALER_PREFIX}{sanitized_id}.pth"
         filepath = save_path / filename
@@ -203,6 +210,15 @@ class _BaseDatasetMaker(ABC):
         if verbose:
             _LOGGER.info(f"Scaler for dataset '{self.id}' saved as '{filepath.name}'.")
 
+    def save_artifacts(self, directory: Union[str, Path], verbose: bool=True) -> None:
+        """
+        Convenience method to save feature names, target names, and the scaler (if a scaler was fitted)
+        """
+        self.save_feature_names(directory=directory, verbose=verbose)
+        self.save_target_names(directory=directory, verbose=verbose)
+        if self.scaler is not None:
+            self.save_scaler(directory=directory, verbose=verbose)
+
 
 # Single target dataset
 class DatasetMaker(_BaseDatasetMaker):

ml_tools/ML_models.py

@@ -304,7 +304,7 @@ class TabularTransformer(nn.Module, _ArchitectureHandlerMixin):
     def __init__(self, *,
                  in_features: int,
                  out_targets: int,
-                 categorical_map: Dict[int, int],
+                 categorical_index_map: Dict[int, int],
                  embedding_dim: int = 32,
                  num_heads: int = 8,
                  num_layers: int = 6,
@@ -313,7 +313,7 @@ class TabularTransformer(nn.Module, _ArchitectureHandlerMixin):
         Args:
             in_features (int): The total number of columns in the input data (features).
             out_targets (int): Number of output targets (1 for regression).
-            categorical_map (Dict[int, int]): Maps categorical column index to its cardinality (number of unique categories).
+            categorical_index_map (Dict[int, int]): Maps categorical column index to its cardinality (number of unique categories).
             embedding_dim (int): The dimension for all feature embeddings. Must be divisible by num_heads.
             num_heads (int): The number of heads in the multi-head attention mechanism.
             num_layers (int): The number of sub-encoder-layers in the transformer encoder.
@@ -340,20 +340,20 @@ class TabularTransformer(nn.Module, _ArchitectureHandlerMixin):
         super().__init__()
         
          # --- Validation ---
-        if categorical_map and max(categorical_map.keys()) >= in_features:
-            _LOGGER.error(f"A categorical index ({max(categorical_map.keys())}) is out of bounds for the provided input features ({in_features}).")
+        if categorical_index_map and max(categorical_index_map.keys()) >= in_features:
+            _LOGGER.error(f"A categorical index ({max(categorical_index_map.keys())}) is out of bounds for the provided input features ({in_features}).")
             raise ValueError()
         
         # --- Derive numerical indices ---
         all_indices = set(range(in_features))
-        categorical_indices_set = set(categorical_map.keys())
+        categorical_indices_set = set(categorical_index_map.keys())
         numerical_indices = sorted(list(all_indices - categorical_indices_set))
         
         # --- Save configuration ---
         self.in_features = in_features
         self.out_targets = out_targets
         self.numerical_indices = numerical_indices
-        self.categorical_map = categorical_map
+        self.categorical_map = categorical_index_map
         self.embedding_dim = embedding_dim
         self.num_heads = num_heads
         self.num_layers = num_layers
@@ -362,7 +362,7 @@ class TabularTransformer(nn.Module, _ArchitectureHandlerMixin):
         # --- 1. Feature Tokenizer ---
         self.tokenizer = _FeatureTokenizer(
             numerical_indices=numerical_indices,
-            categorical_map=categorical_map,
+            categorical_map=categorical_index_map,
             embedding_dim=embedding_dim
         )