dragon-ml-toolbox 1.3.2__py3-none-any.whl → 1.4.1__py3-none-any.whl

ml_tools/particle_swarm_optimization.py

@@ -5,23 +5,29 @@ import xgboost as xgb
 import lightgbm as lgb
 from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
 from sklearn.base import ClassifierMixin
-from sklearn.preprocessing import StandardScaler
+from sklearn.preprocessing import StandardScaler, MaxAbsScaler, MinMaxScaler
 from typing import Literal, Union, Tuple, Dict
-from collections.abc import Sequence
 import polars as pl
 from functools import partial
+from .utilities import sanitize_filename, _script_info
+
+
+__all__ = [
+    "ObjectiveFunction",
+    "run_pso"
+]
 
 
 class ObjectiveFunction():
     """
     Callable objective function designed for optimizing continuous outputs from regression models.
     
-    The trained model must include a 'model' and a 'scaler'. Additionally 'feature_names' and 'target_name' will be parsed if present.
+    The target serialized file (joblib) must include a 'model' and a 'scaler'. Additionally 'feature_names' and 'target_name' will be parsed if present.
 
     Parameters
     ----------
     trained_model_path : str
-        Path to a serialized model (joblib) compatible with scikit-learn-like `.predict`. 
+        Path to a serialized model and its scaler (joblib) compatible with scikit-learn-like `.predict`. 
     add_noise : bool
         Whether to apply multiplicative noise to the input features during evaluation.
     binary_features : int, default=0
@@ -67,8 +73,18 @@ class ObjectiveFunction():
         return new_feature_values
     
     def _handle_hybrid(self, features_array):
-        feat_continuous = features_array[:self.binary_features]
-        feat_binary = (features_array[self.binary_features:] > 0.5).astype(int) #threshold binary values
+        total_features = features_array.shape[0]
+        if self.binary_features > total_features:
+            raise ValueError("self.binary_features exceeds total number of features.")
+        
+        # Handle corner case where all features are binary
+        if self.binary_features == total_features:
+            feat_binary = (features_array > 0.5).astype(int)
+            return feat_binary
+        
+        # Normal case: split into continuous and binary parts
+        feat_continuous = features_array[:-self.binary_features]
+        feat_binary = (features_array[-self.binary_features:] > 0.5).astype(int) #threshold binary values
         new_feature_values = np.concatenate([feat_continuous, feat_binary])
         return new_feature_values
     
@@ -92,7 +108,7 @@ class ObjectiveFunction():
         return (f"<ObjectiveFunction(model={type(self.model).__name__}, scaler={type(self.scaler).__name__}, use_noise={self.use_noise}, is_hybrid={self.is_hybrid}, task='{self.task}')>")
 
 
-def _set_boundaries(lower_boundaries: Sequence[float], upper_boundaries: Sequence[float]):
+def _set_boundaries(lower_boundaries: list[float], upper_boundaries: list[float]):
     assert len(lower_boundaries) == len(upper_boundaries), "Lower and upper boundaries must have the same length."
     assert len(lower_boundaries) >= 1, "At least one boundary pair is required."
     lower = np.array(lower_boundaries)
@@ -112,31 +128,40 @@ def _save_results(*dicts, save_dir: str, target_name: str):
     combined_dict = dict()
     for single_dict in dicts:
         combined_dict.update(single_dict)
-        
-    full_path = os.path.join(save_dir, f"results_{target_name}.csv")
+    
+    sanitized_target_name = sanitize_filename(target_name)
+    
+    full_path = os.path.join(save_dir, f"Optimization_{sanitized_target_name}.csv")
     pl.DataFrame(combined_dict).write_csv(full_path)
 
 
-def run_pso(lower_boundaries: Sequence[float], upper_boundaries: Sequence[float], objective_function: ObjectiveFunction,
-            save_results_dir: str, 
+def run_pso(lower_boundaries: list[float], 
+            upper_boundaries: list[float], 
+            objective_function: ObjectiveFunction,
+            save_results_dir: str,
+            auto_binary_boundaries: bool=True,
             target_name: Union[str, None]=None, 
             feature_names: Union[list[str], None]=None,
-            swarm_size: int=100, max_iterations: int=100,
+            swarm_size: int=100, 
+            max_iterations: int=100,
             inequality_constrain_function=None, 
-            post_hoc_analysis: Union[int, None]=None) -> Tuple[Dict[str, float | list[float]], Dict[str, float | list[float]]]:
+            post_hoc_analysis: Union[int, None]=None,
+            workers: int=5) -> Tuple[Dict[str, float | list[float]], Dict[str, float | list[float]]]:
     """
-    Executes Particle Swarm Optimization (PSO) to optimize a given objective function and saves the results.
+    Executes Particle Swarm Optimization (PSO) to optimize a given objective function and saves the results as a CSV file.
 
     Parameters
     ----------
-    lower_boundaries : Sequence[float]
-        Lower bounds for each feature in the search space.
-    upper_boundaries : Sequence[float]
-        Upper bounds for each feature in the search space.
+    lower_boundaries : list[float]
+        Lower bounds for each feature in the search space (as many as features expected by the model).
+    upper_boundaries : list[float]
+        Upper bounds for each feature in the search space (as many as features expected by the model).
     objective_function : ObjectiveFunction
         A callable object encapsulating a regression model and its scaler.
     save_results_dir : str
         Directory path to save the results CSV file.
+    auto_binary_boundaries : bool
+        Use `ObjectiveFunction.binary_features` to append as many binary boundaries as needed to `lower_boundaries` and `upper_boundaries` automatically.
     target_name : str or None, optional
         Name of the target variable. If None, attempts to retrieve from the ObjectiveFunction object.
     feature_names : list[str] or None, optional
@@ -149,30 +174,38 @@ def run_pso(lower_boundaries: Sequence[float], upper_boundaries: Sequence[float]
         Optional function defining inequality constraints to be respected by the optimization.
     post_hoc_analysis : int or None, optional
         If specified, runs the optimization multiple times to perform post hoc analysis. The value indicates the number of repetitions.
+    workers : int
+        Number of parallel processes to use.
 
     Returns
     -------
     Tuple[Dict[str, float | list[float]], Dict[str, float | list[float]]]
         If `post_hoc_analysis` is None, returns two dictionaries:
-            - best_features_named: Feature values (after inverse scaling) that yield the best result.
-            - best_target_named: Best result obtained for the target variable.
+            - feature_names: Feature values (after inverse scaling) that yield the best result.
+            - target_name: Best result obtained for the target variable.
 
         If `post_hoc_analysis` is an integer, returns two dictionaries:
-            - all_best_features_named: Lists of best feature values (after inverse scaling) for each repetition.
-            - all_best_targets_named: List of best target values across repetitions.
+            - feature_names: Lists of best feature values (after inverse scaling) for each repetition.
+            - target_name: List of best target values across repetitions.
 
     Notes
     -----
     - PSO minimizes the objective function by default; if maximization is desired, it should be handled inside the ObjectiveFunction.
     - Feature values are scaled before being passed to the model and inverse-transformed before result saving.
     """
+    # Append binary boundaries
+    binary_number = objective_function.binary_features
+    if auto_binary_boundaries and binary_number > 0:
+        lower_boundaries.extend([0] * binary_number)
+        upper_boundaries.extend([1] * binary_number)
+
     lower, upper = _set_boundaries(lower_boundaries, upper_boundaries)
-    
+
     # feature names
     if feature_names is None and objective_function.feature_names is not None:
         feature_names = objective_function.feature_names
     names = _set_feature_names(size=len(lower_boundaries), names=feature_names)
-        
+
     # target name
     if target_name is None and objective_function.target_name is not None:
         target_name = objective_function.target_name
@@ -186,13 +219,15 @@ def run_pso(lower_boundaries: Sequence[float], upper_boundaries: Sequence[float]
             "f_ieqcons": inequality_constrain_function,
             "swarmsize": swarm_size,
             "maxiter": max_iterations,
-            "processes": 1,
-            "particle_output": True
+            "processes": workers,
+            "particle_output": False
     }
     
-    if post_hoc_analysis is None:
-        # best_features, best_target = pso(**arguments)
-        best_features, best_target, _particle_positions, _target_values_per_position = pso(**arguments)
+    os.makedirs(save_results_dir, exist_ok=True)
+    
+    if post_hoc_analysis is None or post_hoc_analysis == 1:
+        best_features, best_target, *_ = _pso(**arguments)
+        # best_features, best_target, _particle_positions, _target_values_per_position = _pso(**arguments)
         
         # inverse transformation
         best_features = np.array(best_features).reshape(1, -1)
@@ -209,9 +244,9 @@ def run_pso(lower_boundaries: Sequence[float], upper_boundaries: Sequence[float]
     else:
         all_best_targets = list()
         all_best_features = [[] for _ in range(len(lower_boundaries))]
-        for  _ in range(post_hoc_analysis):
-            # best_features, best_target = pso(**arguments)
-            best_features, best_target, _particle_positions, _target_values_per_position = pso(**arguments)
+        for _ in range(post_hoc_analysis):
+            best_features, best_target, *_ = _pso(**arguments)
+            # best_features, best_target, _particle_positions, _target_values_per_position = _pso(**arguments)
             
             # inverse transformation
             best_features = np.array(best_features).reshape(1, -1)
@@ -231,6 +266,8 @@ def run_pso(lower_boundaries: Sequence[float], upper_boundaries: Sequence[float]
         return all_best_features_named, all_best_targets_named # type: ignore
 
 
+def info():
+    _script_info(__all__)
 
 
 ### SOURCE CODE FOR PSO ###
@@ -249,7 +286,7 @@ def _cons_ieqcons_wrapper(ieqcons, args, kwargs, x):
 def _cons_f_ieqcons_wrapper(f_ieqcons, args, kwargs, x):
     return np.array(f_ieqcons(x, *args, **kwargs))
     
-def pso(func, lb, ub, ieqcons=[], f_ieqcons=None, args=(), kwargs={}, 
+def _pso(func, lb, ub, ieqcons=[], f_ieqcons=None, args=(), kwargs={}, 
         swarmsize=100, omega=0.5, phip=0.5, phig=0.5, maxiter=100, 
         minstep=1e-8, minfunc=1e-8, debug=False, processes=1,
         particle_output=False):
@@ -377,7 +414,7 @@ def pso(func, lb, ub, ieqcons=[], f_ieqcons=None, args=(), kwargs={},
         for i in range(S):
             fx[i] = obj(x[i, :])
             fs[i] = is_feasible(x[i, :])
-       
+    
     # Store particle's best position (if constraints are satisfied)
     i_update = np.logical_and((fx < fp), fs)
     p[i_update, :] = x[i_update, :].copy()

ml_tools/pytorch_models.py

@@ -1,5 +1,12 @@
 import torch
 from torch import nn
+from .utilities import _script_info
+
+
+__all__ = [
+    "MyNeuralNetwork",
+    "MyLSTMNetwork"
+]
 
 
 class MyNeuralNetwork(nn.Module):
@@ -73,9 +80,11 @@ class MyNeuralNetwork(nn.Module):
         return X
 
 
-class MyConvolutionalNetwork(nn.Module):
+class _MyConvolutionalNetwork(nn.Module):
     def __init__(self, outputs: int, color_channels: int=3, img_size: int=256, drop_out: float=0.2):
         """
+        - EDUCATIONAL PURPOSES ONLY, not optimized and requires lots of memory.
+        
         Create a basic Convolutional Neural Network with two convolution layers with a pooling layer after each convolution.
 
         Args:
@@ -225,3 +234,6 @@ class MyLSTMNetwork(nn.Module):
         else:
             return output
 
+
+def info():
+    _script_info(__all__)

ml_tools/trainer.py

@@ -6,6 +6,12 @@ import matplotlib.pyplot as plt
 import torch
 from torch import nn
 from sklearn.metrics import mean_squared_error, classification_report, ConfusionMatrixDisplay, roc_curve, roc_auc_score, r2_score, median_absolute_error
+from .utilities import _script_info
+
+
+__all__ = [
+    "MyTrainer"
+]
 
 
 class MyTrainer():
@@ -288,36 +294,6 @@ class MyTrainer():
                 print(f"Area under the curve score: {area_under_curve:4.2f}")
         else:
             print("Error encountered while retrieving 'model.kind' attribute.")
-            
-
-    def forecast(self, samples_list: list[torch.Tensor], view_as: tuple[int,int]=(1,-1)):
-        """
-            DEPRECATED - Use `helpers.model_predict()` instead
-        
-        Returns a list containing lists of predicted values, one for each sample. 
-        
-        Each sample must be a tensor and have the same shape and normalization expected by the model 
-        (this method will add the batch dimension automatically).
-
-        Args:
-            `samples_list`: list of tensors.
-            
-            `view_as`: reshape each output, default is (1,-1).
-
-        Returns: List of lists.
-        """
-        self.model.eval()
-        results = list()
-        with torch.no_grad():
-            for data_point in samples_list:
-                data_point = data_point.unsqueeze(0).to(self.device)
-                output = self.model(data_point)
-                if self.kind == "classification":
-                    results.append(output.argmax(dim=1).view(view_as).cpu().tolist())
-                else:  #regression
-                    results.append(output.view(view_as).cpu().tolist())
-        
-        return results
     
     
     def rnn_forecast(self, sequence: torch.Tensor, steps: int):
@@ -364,3 +340,7 @@ class MyTrainer():
         # Cast to array and return
         predictions = numpy.array(predictions)
         return predictions
+
+
+def info():
+    _script_info(__all__)

ml_tools/utilities.py

@@ -4,19 +4,30 @@ import pandas as pd
 import os
 from pathlib import Path
 import re
+from typing import Literal
 
 
-def list_csv_paths(directory: str) -> tuple[list[str], list[str]]:
+# Keep track of available tools
+__all__ = [
+    "list_csv_paths",
+    "load_dataframe",
+    "yield_dataframes_from_dir",
+    "merge_dataframes",
+    "save_dataframe",
+    "normalize_mixed_list",
+    "sanitize_filename"
+]
+
+
+def list_csv_paths(directory: str) -> dict[str, str]:
     """
-    Lists all CSV files in a given directory and returns their paths with corresponding base names.
+    Lists all `.csv` files in the specified directory and returns a mapping: filenames (without extensions) to their absolute paths.
 
     Parameters:
         directory (str): Path to the directory containing `.csv` files.
 
     Returns:
-        Tuple ([List[str], List[str]]):
-        - List of absolute paths to `.csv` files.
-        - List of corresponding base names (without extensions).
+        (dict[str, str]): Mapping {name, path}.
     """
     dir_path = Path(directory).expanduser().resolve()
 
@@ -26,11 +37,15 @@ def list_csv_paths(directory: str) -> tuple[list[str], list[str]]:
     csv_paths = list(dir_path.glob("*.csv"))
     if not csv_paths:
         raise IOError(f"No CSV files found in directory: {dir_path}")
+    
+    # make a dictionary of paths and names
+    name_path_dict = {p.stem: str(p) for p in csv_paths}
+    
+    print("🗂️ CSV files found:")
+    for name in name_path_dict.keys():
+        print(f"\t{name}")
 
-    paths = [str(p) for p in csv_paths]
-    names = [p.stem for p in csv_paths]
-
-    return paths, names
+    return name_path_dict
 
 
 def load_dataframe(df_path: str) -> tuple[pd.DataFrame, str]:
@@ -49,7 +64,7 @@ def load_dataframe(df_path: str) -> tuple[pd.DataFrame, str]:
     df_name = path.stem
     if df.empty:
         raise ValueError(f"DataFrame '{df_name}' is empty.")
-    print(f"Loaded dataset: '{df_name}' with shape: {df.shape}")
+    print(f"\n💿 Loaded dataset: '{df_name}' with shape: {df.shape}")
     return df, df_name
 
 
@@ -71,15 +86,96 @@ def yield_dataframes_from_dir(datasets_dir: str):
     - CSV files are read using UTF-8 encoding.
     - Output is streamed via a generator to support lazy loading of multiple datasets.
     """
-    for df_path, df_name in list_csv_paths(datasets_dir):
-        df = pd.read_csv(df_path)
-        print(f"Loaded dataset: '{df_name}' with shape: {df.shape}")
+    for df_name, df_path in list_csv_paths(datasets_dir).items():
+        df, _ = load_dataframe(df_path)
         yield df, df_name
+
+
+def merge_dataframes(
+    *dfs: pd.DataFrame,
+    reset_index: bool = False,
+    direction: Literal["horizontal", "vertical"] = "horizontal"
+) -> pd.DataFrame:
+    """
+    Merges multiple DataFrames either horizontally or vertically.
+
+    Parameters:
+        *dfs (pd.DataFrame): Variable number of DataFrames to merge.
+        reset_index (bool): Whether to reset index in the final merged DataFrame.
+        direction (["horizontal" | "vertical"]):
+            - "horizontal": Merge on index, adding columns.
+            - "vertical": Append rows; all DataFrames must have identical columns.
+
+    Returns:
+        pd.DataFrame: A single merged DataFrame.
+
+    Raises:
+        ValueError:
+            - If fewer than 2 DataFrames are provided.
+            - If indexes do not match for horizontal merge.
+            - If column names or order differ for vertical merge.
+    """
+    if len(dfs) < 2:
+        raise ValueError("At least 2 DataFrames must be provided.")
+    
+    for i, df in enumerate(dfs, start=1):
+        print(f"DataFrame {i} shape: {df.shape}")
+    
+
+    if direction == "horizontal":
+        reference_index = dfs[0].index
+        for i, df in enumerate(dfs, start=1):
+            if not df.index.equals(reference_index):
+                raise ValueError(f"Indexes do not match: Dataset 1 and Dataset {i}.")
+        merged_df = pd.concat(dfs, axis=1)
+
+    elif direction == "vertical":
+        reference_columns = dfs[0].columns
+        for i, df in enumerate(dfs, start=1):
+            if not df.columns.equals(reference_columns):
+                raise ValueError(f"Column names/order do not match: Dataset 1 and Dataset {i}.")
+        merged_df = pd.concat(dfs, axis=0)
+
+    else:
+        raise ValueError(f"Invalid merge direction: {direction}")
+
+    if reset_index:
+        merged_df = merged_df.reset_index(drop=True)
+
+    print(f"Merged DataFrame shape: {merged_df.shape}")
+
+    return merged_df
+
+
+def save_dataframe(df: pd.DataFrame, save_dir: str, filename: str) -> None:
+    """
+    Save a pandas DataFrame to a CSV file.
+
+    Parameters:
+        df: pandas.DataFrame to save
+        save_dir: str, directory where the CSV file will be saved.
+        filename: str, CSV filename, extension will be added if missing.
+    """
+    if df.empty:
+        print(f"⚠️ Attempting to save an empty DataFrame: '{filename}'. Process Skipped.")
+        return
+    
+    os.makedirs(save_dir, exist_ok=True)
+    
+    filename = sanitize_filename(filename)
+    
+    if not filename.endswith('.csv'):
+        filename += '.csv'
         
+    output_path = os.path.join(save_dir, filename)
         
+    df.to_csv(output_path, index=False, encoding='utf-8')
+    print(f"✅ Saved file: '{filename}'")
+
+
 def normalize_mixed_list(data: list, threshold: int = 2) -> list[float]:
     """
-    Normalize a mixed list of numeric values and strings so that the sum of the values equals 1.0,
+    Normalize a mixed list of numeric values and strings casted to floats so that the sum of the values equals 1.0,
     applying heuristic adjustments to correct for potential data entry scale mismatches.
 
     Parameters:
@@ -166,3 +262,15 @@ def sanitize_filename(filename: str) -> str:
 
     return sanitized
 
+
+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}")
+
+
+def info():
+    _script_info(__all__)

ml_tools/vision_helpers.py

@@ -4,9 +4,18 @@ from PIL import Image, ImageOps
 from typing import Literal
 from torchvision import transforms
 import torch
+from .utilities import _script_info
+
+
+__all__ = [
+    "inspect_images",
+    "image_augmentation",
+    "ResizeAspectFill",
+    "is_image",
+    "model_predict"
+]
 
 
-# --- Helper Functions ---
 def inspect_images(path: str):
     """
     Prints out the types, sizes and channels of image files found in the directory and its subdirectories.
@@ -216,3 +225,7 @@ def model_predict(model: torch.nn.Module, kind: Literal["regression", "classific
                 results.append(output.view(view_as).cpu().tolist())
     
     return results
+
+
+def info():
+    _script_info(__all__)

dragon_ml_toolbox-1.3.2.dist-info/RECORD

@@ -1,18 +0,0 @@
-dragon_ml_toolbox-1.3.2.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
-dragon_ml_toolbox-1.3.2.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=e1Hg5ZtaBpDV7ZvxhLe1ac28l7nMjvi1MSE5YvB1s-o,1472
-ml_tools/MICE_imputation.py,sha256=71Kdi5rhPePIT5rJKIyRCM7ORPSjeujQCzKcLIwXs90,9428
-ml_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ml_tools/data_exploration.py,sha256=laTNbN5_xlhqWiKfF-cJ9yMZ8zAM2a-AryqgiIQBBLg,26649
-ml_tools/datasetmaster.py,sha256=VUneKshnmjOGbtqVVGTFcIMRKF3s6ZDYrosIYKDjD80,28956
-ml_tools/ensemble_learning.py,sha256=5UmlXI3Orm5zL0P07Ub_Y0gwjruH-REHY-cFWQpJWb0,29085
-ml_tools/handle_excel.py,sha256=IR0VQc3hYdmjwC31E5YxDnRcWig4jSIx7Y_7to-KZz4,11969
-ml_tools/logger.py,sha256=XwSpCUzw2Le24fJHyljBxNLgw63SwjZ0pMjTJqf0ylI,4622
-ml_tools/particle_swarm_optimization.py,sha256=jpkje4OETC9fyISxxUTx4XGrImSU6gDEcwz46ZDs2bQ,19250
-ml_tools/pytorch_models.py,sha256=Oykw02sOZLCjvSadQd64UGesBN7kq0x1EGXHusvYiQI,9908
-ml_tools/trainer.py,sha256=Zd7AaHeoNd8dEas2JChWoHaCUpWUVRDUMybuHaKJ0XY,16740
-ml_tools/utilities.py,sha256=mG_--EFplfI9H7OhrWI8VkdNJtTbs4Wbz32xvcFWps8,5518
-ml_tools/vision_helpers.py,sha256=lBAW6dzAK-HOswAt1fU_tfP9hkNLY5D8c_I_7hhEXno,7528
-dragon_ml_toolbox-1.3.2.dist-info/METADATA,sha256=NgNKZD1v97kBBdE96OJELolvlAXviJ-DgJvZAjjy5Ik,2309
-dragon_ml_toolbox-1.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dragon_ml_toolbox-1.3.2.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
-dragon_ml_toolbox-1.3.2.dist-info/RECORD,,