dragon-ml-toolbox 3.12.5__py3-none-any.whl → 4.0.0__py3-none-any.whl

ml_tools/ML_trainer.py

@@ -7,9 +7,9 @@ import numpy as np
 
 from .ML_callbacks import Callback, History, TqdmProgressBar
 from .ML_evaluation import classification_metrics, regression_metrics, plot_losses, shap_summary_plot
-from .utilities import _script_info
+from ._script_info import _script_info
 from .keys import LogKeys
-from .logger import _LOGGER
+from ._logger import _LOGGER
 
 
 __all__ = [
@@ -105,7 +105,7 @@ class MyTrainer:
             pin_memory=(self.device.type == "cuda")
         )
 
-    def fit(self, epochs: int = 10, batch_size: int = 32, shuffle: bool = True):
+    def fit(self, epochs: int = 10, batch_size: int = 10, shuffle: bool = True):
         """
         Starts the training-validation process of the model.
 
@@ -113,6 +113,13 @@ class MyTrainer:
             epochs (int): The total number of epochs to train for.
             batch_size (int): The number of samples per batch.
             shuffle (bool): Whether to shuffle the training data at each epoch.
+            
+        Note:
+            For regression tasks using `nn.MSELoss` or `nn.L1Loss`, the trainer
+            automatically aligns the model's output tensor with the target tensor's
+            shape using `output.view_as(target)`. This handles the common case
+            where a model outputs a shape of `[batch_size, 1]` and the target has a
+            shape of `[batch_size]`.
         """
         self.epochs = epochs
         self._create_dataloaders(batch_size, shuffle)
@@ -189,9 +196,10 @@ class MyTrainer:
         logs = {LogKeys.VAL_LOSS: running_loss / len(self.test_loader.dataset)} # type: ignore
         return logs
     
-    def predict(self, dataloader: DataLoader):
+    def _predict_for_eval(self, dataloader: DataLoader):
         """
-        Yields model predictions batch by batch, avoids loading all predictions into memory at once.
+        Private method to yield model predictions batch by batch for evaluation.
+        This is used internally by the `evaluate` method.
 
         Args:
             dataloader (DataLoader): The dataloader to predict on.
@@ -213,13 +221,14 @@ class MyTrainer:
                     preds = torch.argmax(probs, dim=1)
                     y_pred_batch = preds.numpy()
                     y_prob_batch = probs.numpy()
+                # regression
                 else:
                     y_pred_batch = output.numpy()
                     y_prob_batch = None
                 
                 yield y_pred_batch, y_prob_batch, y_true_batch
     
-    def evaluate(self, data: Optional[Union[DataLoader, Dataset]] = None, save_dir: Optional[Union[str,Path]] = None):
+    def evaluate(self, save_dir: Optional[Union[str,Path]], data: Optional[Union[DataLoader, Dataset]] = None):
         """
         Evaluates the model on the given data.
 
@@ -251,7 +260,7 @@ class MyTrainer:
 
         # Collect results from the predict generator
         all_preds, all_probs, all_true = [], [], []
-        for y_pred_b, y_prob_b, y_true_b in self.predict(eval_loader):
+        for y_pred_b, y_prob_b, y_true_b in self._predict_for_eval(eval_loader):
             all_preds.append(y_pred_b)
             if y_prob_b is not None:
                 all_probs.append(y_prob_b)
@@ -270,7 +279,7 @@ class MyTrainer:
         plot_losses(self.history, save_dir=save_dir)
     
     def explain(self, explain_dataset: Optional[Dataset] = None, n_samples: int = 100, 
-                feature_names: Optional[List[str]] = None, save_dir: Optional[str] = None):
+                feature_names: Optional[List[str]] = None, save_dir: Optional[Union[str,Path]] = None):
         """
         Explains model predictions using SHAP and saves all artifacts.
 

ml_tools/PSO_optimization.py

@@ -2,28 +2,23 @@ import numpy as np
 from pathlib import Path
 import xgboost as xgb
 import lightgbm as lgb
-from sklearn.ensemble import HistGradientBoostingRegressor
-from sklearn.base import ClassifierMixin
 from typing import Literal, Union, Tuple, Dict, Optional
 import pandas as pd
 from copy import deepcopy
 from .utilities import (
-    _script_info, 
-    list_csv_paths,
     threshold_binary_values, 
     threshold_binary_values_batch, 
-    deserialize_object, 
-    list_files_by_extension, 
-    save_dataframe, 
-    make_fullpath, 
-    yield_dataframes_from_dir, 
-    sanitize_filename)
+    deserialize_object,
+    save_dataframe,
+    yield_dataframes_from_dir)
+from .path_manager import sanitize_filename, make_fullpath, list_files_by_extension, list_csv_paths
 import torch
 from tqdm import trange
 import matplotlib.pyplot as plt
 import seaborn as sns
-from .logger import _LOGGER
+from ._logger import _LOGGER
 from .keys import ModelSaveKeys
+from ._script_info import _script_info
 
 
 __all__ = [
@@ -125,7 +120,7 @@ class ObjectiveFunction():
             return features_array * noise
     
     def check_model(self):
-        if isinstance(self.model, ClassifierMixin) or isinstance(self.model, xgb.XGBClassifier) or isinstance(self.model, lgb.LGBMClassifier):
+        if isinstance(self.model, xgb.XGBClassifier) or isinstance(self.model, lgb.LGBMClassifier):
             raise ValueError(f"[Model Check Failed] ❌\nThe loaded model ({type(self.model).__name__}) is a Classifier.\nOptimization is not suitable for standard classification tasks.")
         if self.model is None:
             raise ValueError("Loaded model is None")

ml_tools/RNN_forecast.py

@@ -1,6 +1,7 @@
 import torch
 from torch import nn
 import numpy as np
+from ._script_info import _script_info
 
 __all__ = [
     "rnn_forecast"
@@ -47,3 +48,7 @@ def rnn_forecast(model: nn.Module, start_sequence: torch.Tensor, steps: int, dev
             
     # Concatenate all predictions and flatten the array for easy use
     return np.concatenate(predictions).flatten()
+
+
+def info():
+    _script_info

ml_tools/VIF_factor.py

@@ -7,9 +7,10 @@ from statsmodels.stats.outliers_influence import variance_inflation_factor
 from statsmodels.tools.tools import add_constant
 import warnings
 from pathlib import Path
-from .utilities import sanitize_filename, yield_dataframes_from_dir, save_dataframe, _script_info, make_fullpath
-from .logger import _LOGGER
-
+from .utilities import yield_dataframes_from_dir, save_dataframe
+from .path_manager import sanitize_filename, make_fullpath
+from ._logger import _LOGGER
+from ._script_info import _script_info
 
 __all__ = [
     "compute_vif",

ml_tools/_logger.py

@@ -0,0 +1,36 @@
+import logging
+import sys
+
+
+def _get_logger(name: str = "ml_tools", level: int = logging.INFO):
+    """
+    Initializes and returns a configured logger instance.
+    
+    - `logger.info()`
+    - `logger.warning()`
+    - `logger.error()` the program can potentially recover.
+    - `logger.critical()` the program is going to crash.
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Prevents adding handlers multiple times if the function is called again
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        
+        # Define the format string and the date format separately
+        log_format = '\n🐉%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        date_format = '%Y-%m-%d %H:%M' # Format: Year-Month-Day Hour:Minute
+        
+        # Pass both the format and the date format to the Formatter
+        formatter = logging.Formatter(log_format, datefmt=date_format)
+        
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    
+    logger.propagate = False
+    
+    return logger
+
+# Create a single logger instance to be imported by other modules
+_LOGGER = _get_logger()

ml_tools/_pytorch_models.py

@@ -1,6 +1,6 @@
 import torch
 from torch import nn
-from .utilities import _script_info
+from ._script_info import _script_info
 
 
 __all__ = [

ml_tools/_script_info.py

@@ -0,0 +1,8 @@
+
+def _script_info(all_data: list[str]):
+    """
+    List available names.
+    """
+    print("Available functions and objects:")
+    for i, name in enumerate(all_data, start=1):
+            print(f"{i} - {name}")

ml_tools/{logger.py → custom_logger.py}

@@ -2,12 +2,11 @@ from pathlib import Path
 from datetime import datetime
 from typing import Union, List, Dict, Any
 import pandas as pd
-from openpyxl.styles import Font, PatternFill
 import traceback
 import json
-from .utilities import sanitize_filename, _script_info, make_fullpath
-import logging
-import sys
+from .path_manager import sanitize_filename, make_fullpath
+from ._script_info import _script_info
+from ._logger import _LOGGER
 
 
 __all__ = [
@@ -38,9 +37,6 @@ def custom_logger(
     - dict[str, scalar]           → .json
         Dictionary is treated as structured data and serialized as JSON.
 
-    - pandas.DataFrame            → .xlsx
-        Written to an Excel file with styled headers.
-
     - str                         → .log
         Plain text string is written to a .log file.
 
@@ -72,9 +68,6 @@ def custom_logger(
             else:
                 _log_dict_to_json(data, base_path.with_suffix(".json"))
 
-        elif isinstance(data, pd.DataFrame):
-            _log_dataframe_to_xlsx(data, base_path.with_suffix(".xlsx"))
-
         elif isinstance(data, str):
             _log_string_to_log(data, base_path.with_suffix(".log"))
 
@@ -117,27 +110,6 @@ def _log_dict_to_csv(data: Dict[Any, List[Any]], path: Path) -> None:
     df.to_csv(path, index=False)
 
 
-def _log_dataframe_to_xlsx(data: pd.DataFrame, path: Path) -> None:
-    writer = pd.ExcelWriter(path, engine='openpyxl')
-    data.to_excel(writer, index=True, sheet_name='Data')
-
-    workbook = writer.book
-    worksheet = writer.sheets['Data']
-
-    header_font = Font(bold=True)
-    header_fill = PatternFill(
-        start_color="ADD8E6",  # Light blue
-        end_color="ADD8E6",
-        fill_type="solid"
-    )
-
-    for cell in worksheet[1]:
-        cell.font = header_font
-        cell.fill = header_fill
-
-    writer.close()
-
-
 def _log_string_to_log(data: str, path: Path) -> None:
     with open(path, 'w', encoding='utf-8') as f:
         f.write(data.strip() + '\n')
@@ -155,38 +127,4 @@ def _log_dict_to_json(data: Dict[Any, Any], path: Path) -> None:
 
 
 def info():
-    _script_info(__all__)
-
-
-def _get_logger(name: str = "ml_tools", level: int = logging.INFO):
-    """
-    Initializes and returns a configured logger instance.
-    
-    - `logger.info()`
-    - `logger.warning()`
-    - `logger.error()` the program can potentially recover.
-    - `logger.critical()` the program is going to crash.
-    """
-    logger = logging.getLogger(name)
-    logger.setLevel(level)
-
-    # Prevents adding handlers multiple times if the function is called again
-    if not logger.handlers:
-        handler = logging.StreamHandler(sys.stdout)
-        
-        # Define the format string and the date format separately
-        log_format = '\n🐉%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-        date_format = '%Y-%m-%d %H:%M' # Format: Year-Month-Day Hour:Minute
-        
-        # Pass both the format and the date format to the Formatter
-        formatter = logging.Formatter(log_format, datefmt=date_format)
-        
-        handler.setFormatter(formatter)
-        logger.addHandler(handler)
-    
-    logger.propagate = False
-    
-    return logger
-
-# Create a single logger instance to be imported by other modules
-_LOGGER = _get_logger()
+    _script_info(__all__)

ml_tools/data_exploration.py

@@ -3,12 +3,10 @@ from pandas.api.types import is_numeric_dtype
 import numpy as np
 import matplotlib.pyplot as plt
 import seaborn as sns
-from IPython import get_ipython
-from IPython.display import clear_output
-import time
 from typing import Union, Literal, Dict, Tuple, List, Optional
 from pathlib import Path
-from .utilities import sanitize_filename, _script_info, make_fullpath
+from .path_manager import sanitize_filename, make_fullpath
+from ._script_info import _script_info
 import re
 
 
@@ -22,7 +20,6 @@ __all__ = [
     "drop_columns_with_missing_data",
     "split_continuous_binary", 
     "plot_correlation_heatmap", 
-    "check_value_distributions", 
     "plot_value_distributions", 
     "clip_outliers_single", 
     "clip_outliers_multi",
@@ -343,63 +340,6 @@ def plot_correlation_heatmap(df: pd.DataFrame,
     plt.close()
 
 
-def check_value_distributions(df: pd.DataFrame, view_frequencies: bool=True, bin_threshold: int=10, skip_cols_with_key: Union[str, None]=None):
-    """
-    Analyzes value counts for each column in a DataFrame, optionally plots distributions, 
-    and saves them as .png files in the specified directory.
-
-    Args:
-        df (pd.DataFrame): The dataset to analyze.
-        view_frequencies (bool): Print relative frequencies instead of value counts.
-        bin_threshold (int): Threshold of unique values to start using bins.
-        skip_cols_with_key (str | None): Skip column names containing the key. If None, don't skip any column.
-    
-    Notes:
-        - Binning is adaptive: if quantile binning results in ≤ 2 unique bins, raw values are used instead.
-    """
-    # cherry-pick columns
-    if skip_cols_with_key is not None:
-        columns = [col for col in df.columns if skip_cols_with_key not in col]
-    else:
-        columns = df.columns.to_list()
-    
-    for col in columns:
-        if _is_notebook():
-            clear_output(wait=False)
-        if pd.api.types.is_numeric_dtype(df[col]) and df[col].nunique() > bin_threshold:
-            bins_number = 10
-            binned = pd.qcut(df[col], q=bins_number, duplicates='drop')
-            while binned.nunique() <= 2:
-                bins_number -= 1
-                binned = pd.qcut(df[col], q=bins_number, duplicates='drop')
-                if bins_number <= 2:
-                    break
-            
-            if binned.nunique() <= 2:
-                view_std = df[col].value_counts(ascending=False)
-            else:
-                view_std = binned.value_counts(sort=False)
-            
-        else:
-            view_std = df[col].value_counts(ascending=False)
-
-        view_std.name = col
-
-        # unlikely scenario where the series is empty
-        if view_std.sum() == 0:
-            view_freq = view_std
-        else:
-            view_freq = view_std / view_std.sum()
-        # view_freq = df[col].value_counts(normalize=True, bins=10)  # relative percentages
-        view_freq.name = col
-
-        # Print value counts
-        print(view_freq if view_frequencies else view_std)
-        
-        time.sleep(1)
-        user_input_ = input("Press enter to continue")
-
-
 def plot_value_distributions(df: pd.DataFrame, save_dir: Union[str, Path], bin_threshold: int=10, skip_cols_with_key: Union[str, None]=None):
     """
     Plots and saves the value distributions for all (or selected) columns in a DataFrame, 
@@ -691,9 +631,5 @@ def standardize_percentages(
     return df_copy
 
 
-def _is_notebook():
-    return get_ipython() is not None
-
-
 def info():
     _script_info(__all__)

ml_tools/datasetmaster.py

@@ -13,8 +13,9 @@ from torchvision.datasets import ImageFolder
 from torchvision import transforms
 import matplotlib.pyplot as plt
 from pathlib import Path
-from .utilities import _script_info, make_fullpath
-from .logger import _LOGGER
+from .path_manager import make_fullpath
+from ._logger import _LOGGER
+from ._script_info import _script_info
 
 
 # --- public-facing API ---

ml_tools/ensemble_inference.py

@@ -0,0 +1,249 @@
+from ._script_info import _script_info
+from ._logger import _LOGGER
+from .path_manager import make_fullpath, list_files_by_extension
+from .keys import ModelSaveKeys
+
+from typing import Union, Literal, Dict, Any, Optional, List
+from pathlib import Path
+import json
+
+import joblib
+import numpy as np
+# Inference models
+import xgboost
+import lightgbm
+
+
+__all__ = [
+    "InferenceHandler",
+    "model_report"
+]
+
+
+class InferenceHandler:
+    """
+    Handles loading ensemble models and performing inference for either regression or classification tasks.
+    """
+    def __init__(self, 
+                 models_dir: Union[str,Path], 
+                 task: Literal["classification", "regression"],
+                 verbose: bool=True) -> None:
+        """
+        Initializes the handler by loading all models from a directory.
+
+        Args:
+            models_dir (Path): The directory containing the saved .joblib model files.
+            task ("regression" | "classification"): The type of task the models perform.
+        """
+        self.models: Dict[str, Any] = dict()
+        self.task: str = task
+        self.verbose = verbose
+        self._feature_names: Optional[List[str]] = None
+        
+        model_files = list_files_by_extension(directory=models_dir, extension="joblib")
+        
+        for fname, fpath in model_files.items():
+            try:
+                full_object: dict
+                full_object = _deserialize_object(filepath=fpath, 
+                                                 verbose=self.verbose, 
+                                                 raise_on_error=True) # type: ignore
+                
+                model: Any = full_object[ModelSaveKeys.MODEL]
+                target_name: str = full_object[ModelSaveKeys.TARGET]
+                feature_names_list: List[str] = full_object[ModelSaveKeys.FEATURES]
+                
+                # Check that feature names match
+                if self._feature_names is None:
+                    # Store the feature names from the first model loaded.
+                    self._feature_names = feature_names_list
+                elif self._feature_names != feature_names_list:
+                    # Add a warning if subsequent models have different feature names.
+                    _LOGGER.warning(f"⚠️ Mismatched feature names in {fname}. Using feature order from the first model loaded.")
+                
+                self.models[target_name] = model
+                if self.verbose:
+                    _LOGGER.info(f"✅ Loaded model for target: {target_name}")
+
+            except Exception as e:
+                _LOGGER.warning(f"⚠️ Failed to load or parse {fname}: {e}")
+                
+    @property
+    def feature_names(self) -> List[str]:
+        """
+        Getter for the list of feature names the models expect.
+        Returns an empty list if no models were loaded.
+        """
+        return self._feature_names if self._feature_names is not None else []
+    
+    def predict(self, features: np.ndarray) -> Dict[str, Any]:
+        """
+        Predicts on a single feature vector.
+
+        Args:
+            features (np.ndarray): A 1D or 2D NumPy array for a single sample.
+
+        Returns:
+            Dict[str, Any]: A dictionary where keys are target names.
+                - For regression: The value is the single predicted float.
+                - For classification: The value is another dictionary {'label': ..., 'probabilities': ...}.
+        """
+        if features.ndim == 1:
+            features = features.reshape(1, -1)
+        
+        if features.shape[0] != 1:
+            raise ValueError("The predict() method is for a single sample. Use predict_batch() for multiple samples.")
+
+        results: Dict[str, Any] = dict()
+        for target_name, model in self.models.items():
+            if self.task == "regression":
+                prediction = model.predict(features)
+                results[target_name] = prediction.item()
+            else: # Classification
+                label = model.predict(features)[0]
+                probabilities = model.predict_proba(features)[0]
+                results[target_name] = {ModelSaveKeys.CLASSIFICATION_LABEL: label, 
+                                        ModelSaveKeys.CLASSIFICATION_PROBABILITIES: probabilities}
+        
+        if self.verbose:
+            _LOGGER.info("✅ Inference process complete.")
+        return results
+
+    def predict_batch(self, features: np.ndarray) -> Dict[str, Any]:
+        """
+        Predicts on a batch of feature vectors.
+
+        Args:
+            features (np.ndarray): A 2D NumPy array where each row is a sample.
+
+        Returns:
+            Dict[str, Any]: A dictionary where keys are target names.
+                - For regression: The value is a NumPy array of predictions.
+                - For classification: The value is another dictionary {'labels': ..., 'probabilities': ...}.
+        """
+        if features.ndim != 2:
+            raise ValueError("Input for batch prediction must be a 2D array.")
+
+        results: Dict[str, Any] = dict()
+        for target_name, model in self.models.items():
+            if self.task == "regression":
+                results[target_name] = model.predict(features)
+            else: # Classification
+                labels = model.predict(features)
+                probabilities = model.predict_proba(features)
+                results[target_name] = {"labels": labels, "probabilities": probabilities}
+                
+        if self.verbose:
+            _LOGGER.info("✅ Inference process complete.")
+
+        return results
+
+
+def model_report(
+        model_path: Union[str,Path],
+        output_dir: Optional[Union[str,Path]] = None,
+        verbose: bool = True
+    ) -> Dict[str, Any]:
+    """
+    Deserializes a model and generates a summary report.
+
+    This function loads a serialized model object (joblib), prints a summary to the
+    console (if verbose), and saves a detailed JSON report.
+
+    Args:
+        model_path (str): The path to the serialized model file.
+        output_dir (str, optional): Directory to save the JSON report.
+            If None, it defaults to the same directory as the model file.
+        verbose (bool, optional): If True, prints summary information
+            to the console. Defaults to True.
+
+    Returns:
+        (Dict[str, Any]): A dictionary containing the model metadata.
+
+    Raises:
+        FileNotFoundError: If the model_path does not exist.
+        KeyError: If the deserialized object is missing required keys from `ModelSaveKeys`.
+    """
+    # 1. Convert to Path object
+    model_p = make_fullpath(model_path)
+
+    # --- 2. Deserialize and Extract Info ---
+    try:
+        full_object: dict = _deserialize_object(model_p) # type: ignore
+        model = full_object[ModelSaveKeys.MODEL]
+        target = full_object[ModelSaveKeys.TARGET]
+        features = full_object[ModelSaveKeys.FEATURES]
+    except FileNotFoundError:
+        _LOGGER.error(f"❌ Model file not found at '{model_p}'")
+        raise
+    except (KeyError, TypeError) as e:
+        _LOGGER.error(
+            f"❌ The serialized object is missing required keys '{ModelSaveKeys.MODEL}', '{ModelSaveKeys.TARGET}', '{ModelSaveKeys.FEATURES}'"
+        )
+        raise e
+
+    # --- 3. Print Summary to Console (if verbose) ---
+    if verbose:
+        print("\n--- 📝 Model Summary ---")
+        print(f"Source File:    {model_p.name}")
+        print(f"Model Type:     {type(model).__name__}")
+        print(f"Target:         {target}")
+        print(f"Feature Count:  {len(features)}")
+        print("-----------------------")
+
+    # --- 4. Generate JSON Report ---
+    report_data = {
+        "source_file": model_p.name,
+        "model_type": str(type(model)),
+        "target_name": target,
+        "feature_count": len(features),
+        "feature_names": features
+    }
+
+    # Determine output path
+    output_p = make_fullpath(output_dir, make=True) if output_dir else model_p.parent
+    json_filename = model_p.stem + "_info.json"
+    json_filepath = output_p / json_filename    
+
+    try:
+        with open(json_filepath, 'w') as f:
+            json.dump(report_data, f, indent=4)
+        if verbose:
+            _LOGGER.info(f"✅ JSON report saved to: '{json_filepath}'")
+    except PermissionError:
+        _LOGGER.error(f"❌ Permission denied to write JSON report at '{json_filepath}'")
+
+    # --- 5. Return the extracted data ---
+    return report_data
+
+
+# Local implementation to avoid calling utilities' dependencies
+def _deserialize_object(filepath: Union[str,Path], verbose: bool=True, raise_on_error: bool=True) -> Optional[Any]:
+    """
+    Loads a serialized object from a .joblib file.
+
+    Parameters:
+        filepath (str | Path): Full path to the serialized .joblib file.
+
+    Returns:
+        (Any | None): The deserialized Python object, or None if loading fails.
+    """
+    true_filepath = make_fullpath(filepath)
+    
+    try:
+        obj = joblib.load(true_filepath)
+    except (IOError, OSError, EOFError, TypeError, ValueError) as e:
+        message = f"❌ Failed to deserialize object from '{true_filepath}': {e}"
+        if raise_on_error:
+            raise Exception(message)
+        else:
+            print(message)
+        return None
+    else:
+        if verbose:
+            print(f"\n✅ Loaded object of type '{type(obj)}'")
+        return obj
+
+
+def info():
+    _script_info(__all__)