dragon-ml-toolbox 12.10.0__tar.gz → 12.12.0__tar.gz

{dragon_ml_toolbox-12.10.0/dragon_ml_toolbox.egg-info → dragon_ml_toolbox-12.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dragon-ml-toolbox
-Version: 12.10.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.10.0 → dragon_ml_toolbox-12.12.0/dragon_ml_toolbox.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dragon-ml-toolbox
-Version: 12.10.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.10.0 → dragon_ml_toolbox-12.12.0}/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

{dragon_ml_toolbox-12.10.0 → dragon_ml_toolbox-12.12.0}/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):

{dragon_ml_toolbox-12.10.0 → dragon_ml_toolbox-12.12.0}/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
         )
         

{dragon_ml_toolbox-12.10.0 → dragon_ml_toolbox-12.12.0}/ml_tools/custom_logger.py

@@ -221,7 +221,7 @@ def compare_lists(
             - If True: Compares only the `type()` of the items.
 
     Returns:
-        A dictionary detailing the differences. (saved to `save_dir`).
+        dict: A dictionary detailing the differences. (saved to `save_dir`).
     """
     MISSING_A_KEY = "missing_in_A"
     MISSING_B_KEY = "missing_in_B"

{dragon_ml_toolbox-12.10.0 → dragon_ml_toolbox-12.12.0}/ml_tools/serde.py

@@ -83,8 +83,7 @@ def deserialize_object(
     filepath: Union[str, Path],
     expected_type: Optional[Type[T]] = None,
     verbose: bool = True,
-    raise_on_error: bool = True
-    ) -> Optional[T]:
+    ) -> T:
     """
     Loads a serialized object from a .joblib file.
 
@@ -96,22 +95,17 @@ def deserialize_object(
             like `list[str]` by checking the base type (e.g., `list`).
             Defaults to None, which skips the type check.
         verbose (bool): If True, logs success messages.
-        raise_on_error (bool): If True, raises exceptions on errors. If False, returns None instead.
 
     Returns:
-        (Any | None): The deserialized Python object, which will match the
-            `expected_type` if provided. Returns None if an error
-            occurs and `raise_on_error` is False.
+        (Any): The deserialized Python object, which will match the `expected_type` if provided.
     """
-    true_filepath = make_fullpath(filepath)
+    true_filepath = make_fullpath(filepath, enforce="file")
     
     try:
         obj = joblib.load(true_filepath)
     except (IOError, OSError, EOFError, TypeError, ValueError) as e:
         _LOGGER.error(f"Failed to deserialize object from '{true_filepath}'.")
-        if raise_on_error:
-            raise e
-        return None
+        raise e
     else:
         # --- Type Validation Step ---
         if expected_type:
@@ -126,9 +120,7 @@ def deserialize_object(
                     f"but found '{type(obj)}' in '{true_filepath}'."
                 )
                 _LOGGER.error(error_msg)
-                if raise_on_error:
-                    raise TypeError()
-                return None
+                raise TypeError()
         
         if verbose:
             _LOGGER.info(f"Loaded object of type '{type(obj)}' from '{true_filepath}'.")

{dragon_ml_toolbox-12.10.0 → dragon_ml_toolbox-12.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dragon-ml-toolbox"
-version = "12.10.0"
+version = "12.12.0"
 description = "A collection of tools for data science and machine learning projects."
 authors = [
     { name = "Karl L. Loza Vidaurre", email = "luigiloza@gmail.com" }