dragon-ml-toolbox 1.4.4__py3-none-any.whl → 1.4.6__py3-none-any.whl

{dragon_ml_toolbox-1.4.4.dist-info → dragon_ml_toolbox-1.4.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dragon-ml-toolbox
-Version: 1.4.4
+Version: 1.4.6
 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-1.4.6.dist-info/RECORD

@@ -0,0 +1,19 @@
+dragon_ml_toolbox-1.4.6.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
+dragon_ml_toolbox-1.4.6.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=jDnniT0tgD0uw1NpjibsPF-qK3wmOKgTykLG2iNQU7E,1840
+ml_tools/MICE_imputation.py,sha256=JMe9hyidJadFTHW7AHkNQ_fduTxH6CEh7_Ouy2LhCOQ,11096
+ml_tools/VIF_factor.py,sha256=HEBsLJy_qSDaPw1Btha5B7omxN4wjJXg-sqoetCjCJw,10016
+ml_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ml_tools/data_exploration.py,sha256=X9mYZdynRGghT06GeOdVsfGBTFa342Ko-MkMImDll-M,20123
+ml_tools/datasetmaster.py,sha256=EFUEX-tqq94Ak1rXXYR-XaX85olrxvF2EuytdzUK7y0,29131
+ml_tools/ensemble_learning.py,sha256=xJyEbkFObm5YX6DmDW10FOUjSeYeBRhHLvncWZv_uTo,37319
+ml_tools/handle_excel.py,sha256=ZJui5__0rc2T8UGHTheqZGhKmdVZ7Q2I54IoYCjAqJw,12612
+ml_tools/logger.py,sha256=ZTtUB9HTkNs5zHTdYRKNbKADjUkuObsF7s8U5pNnVRA,4716
+ml_tools/particle_swarm_optimization.py,sha256=ByCYFV8PWP9CYGZ0wblphtmDLRbSezY9a0_fGqGWQV4,21891
+ml_tools/pytorch_models.py,sha256=bpWZsrSwCvHJQkR6UfoPpElsMv9AvmiNErNHC8NYB_I,10132
+ml_tools/trainer.py,sha256=WAZ4EdrZuTOAnGXRWV3XcLNce4s7EKGf2-qchLC08Ik,15702
+ml_tools/utilities.py,sha256=Ir3Yw4SuWMLKnbnl4Qzudn5U8CgcQ7zMtNqcllZMHeM,15682
+ml_tools/vision_helpers.py,sha256=idQ-Ugp1IdsvwXiYyhYa9G3rTRTm37YRpkQDLEpANHM,7701
+dragon_ml_toolbox-1.4.6.dist-info/METADATA,sha256=SDqa8Cz72fH669cfuMIcVX02SC0DeK0UmKU-fAPx4AU,2516
+dragon_ml_toolbox-1.4.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dragon_ml_toolbox-1.4.6.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
+dragon_ml_toolbox-1.4.6.dist-info/RECORD,,

ml_tools/MICE_imputation.py

@@ -3,8 +3,9 @@ import miceforest as mf
 import os
 import matplotlib.pyplot as plt
 import numpy as np
-from ml_tools.utilities import load_dataframe, list_csv_paths, sanitize_filename, _script_info, merge_dataframes, save_dataframe
+from ml_tools.utilities import load_dataframe, list_csv_paths, sanitize_filename, _script_info, merge_dataframes, save_dataframe, threshold_binary_values
 from plotnine import ggplot, labs, theme, element_blank # type: ignore
+from typing import Optional
 
 
 __all__ = [
@@ -17,7 +18,7 @@ __all__ = [
 ]
 
 
-def apply_mice(df: pd.DataFrame, df_name: str, resulting_datasets: int=1, iterations: int=20, random_state: int=101):
+def apply_mice(df: pd.DataFrame, df_name: str, binary_columns: Optional[list[str]]=None, resulting_datasets: int=1, iterations: int=20, random_state: int=101):
     
     # Initialize kernel with number of imputed datasets to generate
     kernel = mf.ImputationKernel(
@@ -35,6 +36,16 @@ def apply_mice(df: pd.DataFrame, df_name: str, resulting_datasets: int=1, iterat
     if imputed_datasets is None or len(imputed_datasets) == 0:
         raise ValueError("No imputed datasets were generated. Check the MICE process.")
     
+    # threshold binary columns
+    if binary_columns is not None:
+        invalid_binary_columns = set(binary_columns) - set(df.columns)
+        if invalid_binary_columns:
+            print(f"⚠️ These 'binary columns' are not in the dataset: {invalid_binary_columns}")
+        valid_binary_columns = [col for col in binary_columns if col not in invalid_binary_columns]
+        for imputed_df in imputed_datasets:
+            for binary_column_name in valid_binary_columns:
+                imputed_df[binary_column_name] = threshold_binary_values(imputed_df[binary_column_name]) # type: ignore
+            
     if resulting_datasets == 1:
         imputed_dataset_names = [f"{df_name}_MICE"]
     else:
@@ -106,7 +117,7 @@ def get_convergence_diagnostic(kernel: mf.ImputationKernel, imputed_dataset_name
             # Adjust plot display for the X axis
             _ticks = np.arange(iterations_cap)
             _labels = np.arange(1, iterations_cap + 1)
-            plt.xticks(ticks=_ticks, labels=_labels)
+            plt.xticks(ticks=_ticks, labels=_labels) # type: ignore
             plt.grid(True)
             
             feature_save_name = sanitize_filename(feature_name)
@@ -202,7 +213,12 @@ def get_imputed_distributions(kernel: mf.ImputationKernel, df_name: str, root_di
     print(f"{local_dir_name} completed.")
 
 
-def run_mice_pipeline(df_path_or_dir: str, target_columns: list[str], save_datasets_dir: str, save_metrics_dir: str, resulting_datasets: int=1, iterations: int=20, random_state: int=101):
+def run_mice_pipeline(df_path_or_dir: str, target_columns: list[str], 
+                      save_datasets_dir: str, save_metrics_dir: str, 
+                      binary_columns: Optional[list[str]]=None,
+                      resulting_datasets: int=1, 
+                      iterations: int=20, 
+                      random_state: int=101):
     """
     Call functions in sequence for each dataset in the provided path or directory:
         1. Load dataframe
@@ -211,7 +227,7 @@ def run_mice_pipeline(df_path_or_dir: str, target_columns: list[str], save_datas
         4. Save convergence metrics
         5. Save distribution metrics
         
-    Target columns must be skipped from the imputation.
+    Target columns must be skipped from the imputation. Binary columns will be thresholded after imputation.
     """
     # Check paths
     os.makedirs(save_datasets_dir, exist_ok=True)
@@ -229,7 +245,7 @@ def run_mice_pipeline(df_path_or_dir: str, target_columns: list[str], save_datas
         
         df, df_targets = _skip_targets(df, target_columns)
         
-        kernel, imputed_datasets, imputed_dataset_names = apply_mice(df=df, df_name=df_name, resulting_datasets=resulting_datasets, iterations=iterations, random_state=random_state)
+        kernel, imputed_datasets, imputed_dataset_names = apply_mice(df=df, df_name=df_name, binary_columns=binary_columns, resulting_datasets=resulting_datasets, iterations=iterations, random_state=random_state)
         
         save_imputed_datasets(save_dir=save_datasets_dir, imputed_datasets=imputed_datasets, df_targets=df_targets, imputed_dataset_names=imputed_dataset_names)
         

ml_tools/data_exploration.py

@@ -5,9 +5,10 @@ import seaborn as sns
 from IPython import get_ipython
 from IPython.display import clear_output
 import time
-from typing import Union, Literal, Dict, Tuple, Iterator
+from typing import Union, Literal, Dict, Tuple, List
 import os
 from ml_tools.utilities import sanitize_filename, _script_info
+import re
 
 
 # Keep track of all available tools, show using `info()`
@@ -23,7 +24,7 @@ __all__ = [
     "plot_value_distributions", 
     "clip_outliers_single", 
     "clip_outliers_multi",
-    "distribute_datasets_by_target"
+    "match_and_filter_columns_by_regex"
 ]
 
 
@@ -90,18 +91,18 @@ def split_features_targets(df: pd.DataFrame, targets: list[str]):
 
     Returns:
         tuple: A tuple containing:
-            - pd.DataFrame: Targets dataframe.
             - pd.DataFrame: Features dataframe.
+            - pd.DataFrame: Targets dataframe.
 
     Prints:
         - Shape of the original dataframe.
-        - Shape of the targets dataframe.
         - Shape of the features dataframe.
+        - Shape of the targets dataframe.
     """
     df_targets = df[targets]
     df_features = df.drop(columns=targets)
-    print(f"Original shape: {df.shape}\nTargets shape: {df_targets.shape}\nFeatures shape: {df_features.shape}")
-    return df_targets, df_features
+    print(f"Original shape: {df.shape}\nFeatures shape: {df_features.shape}\nTargets shape: {df_targets.shape}")
+    return df_features, df_targets
 
 
 def show_null_columns(df: pd.DataFrame, round_digits: int = 2):
@@ -246,9 +247,6 @@ def plot_correlation_heatmap(df: pd.DataFrame, save_dir: Union[str, None] = None
         cbar_kws={"shrink": 0.8}
     )
     
-    # sanitize the plot title
-    plot_title = sanitize_filename(plot_title)
-
     plt.title(plot_title)
     plt.xticks(rotation=45, ha='right')
     plt.yticks(rotation=0)
@@ -256,6 +254,8 @@ def plot_correlation_heatmap(df: pd.DataFrame, save_dir: Union[str, None] = None
     plt.tight_layout()
     
     if save_dir:
+        # sanitize the plot title to save the file
+        plot_title = sanitize_filename(plot_title)
         os.makedirs(save_dir, exist_ok=True)
         full_path = os.path.join(save_dir, plot_title + ".svg")
         plt.savefig(full_path, bbox_inches="tight", format='svg')
@@ -519,38 +519,34 @@ def clip_outliers_multi(
     return new_df
 
 
-def distribute_datasets_by_target(
+def match_and_filter_columns_by_regex(
     df: pd.DataFrame,
-    target_columns: list[str],
-    verbose: bool = False
-) -> Iterator[Tuple[str, pd.DataFrame]]:
+    pattern: str,
+    case_sensitive: bool = False,
+    escape_pattern: bool = False
+) -> Tuple[pd.DataFrame, List[str]]:
     """
-    Yields cleaned DataFrames for each target column, where rows with missing
-    target values are removed. The target column is placed at the end.
-
-    Parameters
-    ----------
-    df : pd.DataFrame
-        Preprocessed dataframe with all feature and target columns ready to train.
-    target_columns : List[str]
-        List of target column names to generate per-target DataFrames.
-    verbose: bool
-        Whether to print info for each yielded dataset.
-
-    Yields
-    ------
-    Tuple[str, pd.DataFrame]
-        * First element is the target column name.
-        * Second element is the corresponding cleaned DataFrame.
+    Return a tuple of (filtered DataFrame, matched column names) based on a regex pattern.
+
+    Parameters:
+        df (pd.DataFrame): The DataFrame to search.
+        pattern (str): The regex pattern to match column names (use a raw string).
+        case_sensitive (bool): Whether matching is case-sensitive.
+        escape_pattern (bool): If True, the pattern is escaped with `re.escape()` to treat it literally.
+
+    Returns:
+        (Tuple[pd.DataFrame, list[str]]): A DataFrame filtered to matched columns, and a list of matching column names.
     """
-    valid_targets = [col for col in df.columns if col in target_columns]
-    feature_columns = [col for col in df.columns if col not in valid_targets]
+    if escape_pattern:
+        pattern = re.escape(pattern)
 
-    for target in valid_targets:
-        subset = df[feature_columns + [target]].dropna(subset=[target])
-        if verbose:
-            print(f"Target: '{target}' - Dataframe shape: {subset.shape}")
-        yield target, subset
+    mask = df.columns.str.contains(pattern, case=case_sensitive, regex=True)
+    matched_columns = df.columns[mask].to_list()
+    filtered_df = df.loc[:, mask]
+    
+    print(f"{len(matched_columns)} column(s) match the regex pattern '{pattern}'.")
+
+    return filtered_df, matched_columns
 
 
 def _is_notebook():
@@ -559,4 +555,3 @@ def _is_notebook():
 
 def info():
     _script_info(__all__)
-

ml_tools/ensemble_learning.py

@@ -20,7 +20,7 @@ from sklearn.model_selection import train_test_split
 from sklearn.metrics import accuracy_score, classification_report, ConfusionMatrixDisplay, mean_absolute_error, mean_squared_error, r2_score, roc_curve, roc_auc_score
 import shap
 
-from .utilities import yield_dataframes_from_dir, sanitize_filename, _script_info
+from .utilities import yield_dataframes_from_dir, sanitize_filename, _script_info, serialize_object
 
 import warnings # Ignore warnings 
 warnings.filterwarnings('ignore', category=DeprecationWarning)
@@ -485,8 +485,9 @@ def _local_directories(model_name: str, dataset_id: str, save_dir: str):
 def _save_model(trained_model, model_name: str, target_name:str, feature_names: list[str], save_directory: str):
     #Sanitize filenames to save
     sanitized_target_name = sanitize_filename(target_name)
-    full_path = os.path.join(save_directory, f"{model_name}_{sanitized_target_name}.joblib")
-    joblib.dump({'model': trained_model, 'feature_names': feature_names, 'target_name':target_name}, full_path)
+    filename = f"{model_name}_{sanitized_target_name}"
+    to_save = {'model': trained_model, 'feature_names': feature_names, 'target_name':target_name}
+    serialize_object(obj=to_save, save_dir=save_directory, filename=filename, verbose=False, raise_on_error=True)
 
 # function to evaluate the model and save metrics (Classification)
 def evaluate_model_classification(

ml_tools/particle_swarm_optimization.py

@@ -8,11 +8,12 @@ from sklearn.base import ClassifierMixin
 from typing import Literal, Union, Tuple, Dict, Optional
 import polars as pl
 from functools import partial
-from .utilities import sanitize_filename, _script_info, threshold_binary_values
+from .utilities import sanitize_filename, _script_info, threshold_binary_values, deserialize_object, list_files_by_extension
 
 
 __all__ = [
     "ObjectiveFunction",
+    "multiple_objective_functions_from_dir",
     "run_pso"
 ]
 
@@ -29,16 +30,16 @@ class ObjectiveFunction():
         Path to a serialized model (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
-        Number of binary features located at the END of the feature vector. Model should be trained with continuous features first, followed by binary.
-    task : Literal, default 'maximization'
+    task : (Literal["maximization", "minimization"])
         Whether to maximize or minimize the target.
+    binary_features : int
+        Number of binary features located at the END of the feature vector. Model should be trained with continuous features first, followed by binary.
     """
-    def __init__(self, trained_model_path: str, add_noise: bool, task: Literal["maximization", "minimization"], binary_features: int=0) -> None:
+    def __init__(self, trained_model_path: str, add_noise: bool, task: Literal["maximization", "minimization"], binary_features: int) -> None:
         self.binary_features = binary_features
         self.is_hybrid = False if binary_features <= 0 else True
         self.use_noise = add_noise
-        self._artifact = joblib.load(trained_model_path)
+        self._artifact = deserialize_object(trained_model_path, verbose=False, raise_on_error=True)
         self.model = self._get_from_artifact('model')
         self.feature_names: Optional[list[str]] = self._get_from_artifact('feature_names') # type: ignore
         self.target_name: Optional[str] = self._get_from_artifact('target_name') # type: ignore
@@ -49,7 +50,7 @@ class ObjectiveFunction():
         if self.use_noise:
             features_array = self.add_noise(features_array)
         if self.is_hybrid:
-            features_array = threshold_binary_values(input_array=features_array, binary_features=self.binary_features)
+            features_array = threshold_binary_values(input_array=features_array, binary_values=self.binary_features) # type: ignore
         
         if features_array.ndim == 1:
             features_array = features_array.reshape(1, -1)
@@ -83,6 +84,8 @@ class ObjectiveFunction():
             raise ValueError("Loaded model is None")
 
     def _get_from_artifact(self, key: str):
+        if self._artifact is None:
+            raise TypeError("Load model error")
         val = self._artifact.get(key)
         if key == "feature_names":
             result = val if isinstance(val, list) and val else None
@@ -94,6 +97,35 @@ class ObjectiveFunction():
         return (f"<ObjectiveFunction(model={type(self.model).__name__}, use_noise={self.use_noise}, is_hybrid={self.is_hybrid}, task='{self.task}')>")
 
 
+def multiple_objective_functions_from_dir(directory: str, add_noise: bool, task: Literal["maximization", "minimization"], binary_features: int):
+    """
+    Loads multiple objective functions from serialized models in the given directory.
+
+    Each `.joblib` file which is loaded and wrapped as an `ObjectiveFunction` instance. Returns a list of such instances along with their corresponding names.
+
+    Parameters:
+        directory (str) : Path to the directory containing `.joblib` files (serialized models).
+        add_noise (bool) : Whether to apply multiplicative noise to the input features during evaluation.
+        task (Literal["maximization", "minimization"]) : Defines the nature of the optimization task.
+        binary_features (int) : Number of binary features expected by each objective function.
+
+    Returns:
+        (tuple[list[ObjectiveFunction], list[str]]) : A tuple containing:
+            - list of `ObjectiveFunction` instances.
+            - list of corresponding filenames.
+    """
+    objective_functions = list()
+    objective_function_names = list()
+    for file_name, file_path in list_files_by_extension(directory=directory, extension='joblib').items():
+        current_objective = ObjectiveFunction(trained_model_path=file_path,
+                                              add_noise=add_noise,
+                                              task=task,
+                                              binary_features=binary_features)
+        objective_functions.append(current_objective)
+        objective_function_names.append(file_name)
+    return objective_functions, objective_function_names
+
+
 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."
@@ -129,9 +161,9 @@ def run_pso(lower_boundaries: list[float],
             target_name: Union[str, None]=None, 
             feature_names: Union[list[str], None]=None,
             swarm_size: int=200, 
-            max_iterations: int=1500,
+            max_iterations: int=1000,
             inequality_constrain_function=None, 
-            post_hoc_analysis: Optional[int]=5,
+            post_hoc_analysis: Optional[int]=3,
             workers: int=1) -> 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 as a CSV file.

ml_tools/utilities.py

@@ -1,22 +1,29 @@
 import math
 import numpy as np
 import pandas as pd
+import polars as pl
 import os
 from pathlib import Path
 import re
-from typing import Literal, Union, Sequence
+from typing import Literal, Union, Sequence, Optional, Any, Iterator, Tuple
+import joblib
+from joblib.externals.loky.process_executor import TerminatedWorkerError
 
 
 # Keep track of available tools
 __all__ = [
     "list_csv_paths",
+    "list_files_by_extension",
     "load_dataframe",
     "yield_dataframes_from_dir",
     "merge_dataframes",
     "save_dataframe",
     "normalize_mixed_list",
     "sanitize_filename",
-    "threshold_binary_values"
+    "threshold_binary_values",
+    "serialize_object",
+    "deserialize_object",
+    "distribute_datasets_by_target"
 ]
 
 
@@ -28,7 +35,7 @@ def list_csv_paths(directory: str) -> dict[str, str]:
         directory (str): Path to the directory containing `.csv` files.
 
     Returns:
-        (dict[str, str]): Mapping {name, path}.
+        (dict[str, str]): Dictionary mapping {filename: filepath}.
     """
     dir_path = Path(directory).expanduser().resolve()
 
@@ -42,13 +49,47 @@ def list_csv_paths(directory: str) -> dict[str, str]:
     # make a dictionary of paths and names
     name_path_dict = {p.stem: str(p) for p in csv_paths}
     
-    print("🗂️ CSV files found:")
+    print("\n🗂️ CSV files found:")
     for name in name_path_dict.keys():
         print(f"\t{name}")
 
     return name_path_dict
 
 
+def list_files_by_extension(directory: str, extension: str) -> dict[str, str]:
+    """
+    Lists all files with the specified extension in the given directory and returns a mapping: 
+    filenames (without extensions) to their absolute paths.
+
+    Parameters:
+        directory (str): Path to the directory to search in.
+        extension (str): File extension to search for (e.g., 'json', 'txt').
+
+    Returns:
+        (dict[str, str]): Dictionary mapping {filename: filepath}.
+    """
+    dir_path = Path(directory).expanduser().resolve()
+
+    if not dir_path.is_dir():
+        raise FileNotFoundError(f"Directory not found: {dir_path}")
+    
+    # Normalize the extension (remove leading dot if present)
+    normalized_ext = extension.lstrip(".").lower()
+    pattern = f"*.{normalized_ext}"
+    
+    matched_paths = list(dir_path.glob(pattern))
+    if not matched_paths:
+        raise IOError(f"No '.{normalized_ext}' files found in directory: {dir_path}")
+
+    name_path_dict = {p.stem: str(p) for p in matched_paths}
+    
+    print(f"\n📂 '{normalized_ext.upper()}' files found:")
+    for name in name_path_dict:
+        print(f"\t{name}")
+    
+    return name_path_dict
+
+
 def load_dataframe(df_path: str) -> tuple[pd.DataFrame, str]:
     """
     Load a CSV file into a pandas DataFrame and extract the base name (without extension) from the file path.
@@ -194,12 +235,9 @@ def normalize_mixed_list(data: list, threshold: int = 2) -> list[float]:
 
     Returns:
         List[float]: A list of normalized float values summing to 1.0. 
-            Values significantly smaller than the median scale are scaled up 
-            before normalization to correct likely input errors.
     
     Notes:
         - Zeros and None values remain zero.
-        - If all input values are zero or None, the function returns a list of zeros.
         - Input strings are automatically cast to floats if possible.
 
     Example:
@@ -268,35 +306,156 @@ def sanitize_filename(filename: str) -> str:
 
 
 def threshold_binary_values(
-    input_array: Union[Sequence[float], np.ndarray],
-    binary_features: int
-) -> np.ndarray:
+    input_array: Union[Sequence[float], np.ndarray, pd.Series, pl.Series],
+    binary_values: Optional[int] = None
+) -> Union[np.ndarray, pd.Series, pl.Series, list[float], tuple[float]]:
     """
-    Thresholds binary features in a 1D numeric sequence. Binary features must be located at the end of the sequence.
+    Thresholds binary features in a 1D input. The number of binary features are counted starting from the end.
 
-    Converts binary elements to values (0 or 1) using a threshold of 0.5. The rest of the array (assumed to be continuous features) is returned unchanged.
+    Parameters:
+        input_array: 1D sequence, NumPy array, pandas Series, or polars Series.
+        binary_values (Optional[int]) :
+            - If `None`, all values are treated as binary.
+            - If `int`, only this many last `binary_values` are thresholded.
+
+    Returns:
+        Same type as input, with binary elements binarized to 0 or 1 using a 0.5 threshold.
+    """
+    original_type = type(input_array)
+
+    if isinstance(input_array, pl.Series):
+        array = input_array.to_numpy()
+    elif isinstance(input_array, (pd.Series, np.ndarray)):
+        array = np.asarray(input_array)
+    elif isinstance(input_array, (list, tuple)):
+        array = np.array(input_array)
+    else:
+        raise TypeError("Unsupported input type")
+
+    array = array.flatten()
+    total = array.shape[0]
+
+    bin_count = total if binary_values is None else binary_values
+    if not (0 <= bin_count <= total):
+        raise ValueError("binary_values must be between 0 and the total number of elements")
+
+    if bin_count == 0:
+        result = array
+    else:
+        cont_part = array[:-bin_count] if bin_count < total else np.array([])
+        bin_part = (array[-bin_count:] > 0.5).astype(int)
+        result = np.concatenate([cont_part, bin_part])
+
+    if original_type is pd.Series:
+        return pd.Series(result, index=input_array.index if hasattr(input_array, 'index') else None) # type: ignore
+    elif original_type is pl.Series:
+        return pl.Series(input_array.name if hasattr(input_array, 'name') else "binary", result) # type: ignore
+    elif original_type is list:
+        return result.tolist()
+    elif original_type is tuple:
+        return tuple(result)
+    else:
+        return result
+
+
+def serialize_object(obj: Any, save_dir: str, filename: str, verbose: bool=True, raise_on_error: bool=False) -> Optional[str]:
+    """
+    Serializes a Python object using joblib; suitable for Python built-ins, numpy, and pandas.
 
     Parameters:
-        input_array (Union[Sequence[float], np.ndarray]) : A one-dimensional collection of numeric values. The binary features must be located at the end of the array.
+        obj (Any) : The Python object to serialize.
+        save_dir (str) : Directory path where the serialized object will be saved.
+        filename (str) : Name for the output file, extension will be appended if needed.
+
+    Returns:
+        (str | None) : The full file path where the object was saved if successful; otherwise, None.
+    """
+    try:
+        os.makedirs(save_dir, exist_ok=True)
+        sanitized_name = sanitize_filename(filename)
+        if not sanitized_name.endswith('.joblib'):
+            sanitized_name = sanitized_name + ".joblib"
+        full_path = os.path.join(save_dir, sanitized_name)
+        joblib.dump(obj, full_path)
+    except (IOError, OSError, TypeError, TerminatedWorkerError) as e:
+        message = f"❌ Failed to serialize object of type '{type(obj)}': {e}"
+        if raise_on_error:
+            raise Exception(message)
+        else:
+            print(message)
+        return None
+    else:
+        if verbose:
+            print(f"✅ Object of type '{type(obj)}' saved to '{full_path}'")
+        return full_path
 
-        binary_features (int) : Number of binary features to threshold from the end of the array. Must be between 0 and the total number of elements.
+
+def deserialize_object(filepath: str, verbose: bool=True, raise_on_error: bool=True) -> Optional[Any]:
+    """
+    Loads a serialized object from a .joblib file.
+
+    Parameters:
+        filepath (str): Full path to the serialized .joblib file.
 
     Returns:
-        np.ndarray : A 1D NumPy array where the final `binary_features` values have been binarized.
+        (Any | None): The deserialized Python object, or None if loading fails.
     """
-    array = np.asarray(input_array).flatten()
-    total = array.shape[0]
-    
-    if binary_features < 0 or binary_features > total:
-        raise ValueError("Binary features must be between 0 and the total number of features.")
-    
-    if binary_features == 0:
-        return array
+    if not os.path.exists(filepath):
+        print(f"❌ File does not exist: {filepath}")
+        return None
+    try:
+        obj = joblib.load(filepath)
+    except (IOError, OSError, EOFError, TypeError, ValueError) as e:
+        message = f"❌ Failed to deserialize object from '{filepath}': {e}"
+        if raise_on_error:
+            raise Exception(message)
+        else:
+            print(message)
+        return None
+    else:
+        if verbose:
+            print(f"✅ Loaded object of type '{type(obj)}'")
+        return obj
+
 
-    cont_part = array[:-binary_features]
-    bin_part = (array[-binary_features:] > 0.5).astype(int)
+def distribute_datasets_by_target(
+    df_or_path: Union[pd.DataFrame, str],
+    target_columns: list[str],
+    verbose: bool = False
+) -> Iterator[Tuple[str, pd.DataFrame]]:
+    """
+    Yields cleaned DataFrames for each target column, where rows with missing
+    target values are removed. The target column is placed at the end.
+
+    Parameters
+    ----------
+    df_or_path : [pd.DataFrame | str]
+        Dataframe or path to Dataframe with all feature and target columns ready to split and train a model.
+    target_columns : List[str]
+        List of target column names to generate per-target DataFrames.
+    verbose: bool
+        Whether to print info for each yielded dataset.
+
+    Yields
+    ------
+    Tuple[str, pd.DataFrame]
+        * Target name.
+        * Pandas DataFrame.
+    """
+    # Validate path
+    if isinstance(df_or_path, str):
+        df, _ = load_dataframe(df_or_path)
+    else:
+        df = df_or_path
     
-    return np.concatenate([cont_part, bin_part])
+    valid_targets = [col for col in df.columns if col in target_columns]
+    feature_columns = [col for col in df.columns if col not in valid_targets]
+
+    for target in valid_targets:
+        subset = df[feature_columns + [target]].dropna(subset=[target])
+        if verbose:
+            print(f"Target: '{target}' - Dataframe shape: {subset.shape}")
+        yield target, subset
 
 
 def _script_info(all_data: list[str]):

dragon_ml_toolbox-1.4.4.dist-info/RECORD

@@ -1,19 +0,0 @@
-dragon_ml_toolbox-1.4.4.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
-dragon_ml_toolbox-1.4.4.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=jDnniT0tgD0uw1NpjibsPF-qK3wmOKgTykLG2iNQU7E,1840
-ml_tools/MICE_imputation.py,sha256=o1wPu3sYt6AxmUgtyDcfqbwL-82Hyep0upvC4tIWKyw,10136
-ml_tools/VIF_factor.py,sha256=HEBsLJy_qSDaPw1Btha5B7omxN4wjJXg-sqoetCjCJw,10016
-ml_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ml_tools/data_exploration.py,sha256=nBhDuaUCgEVG0Xi8MQ0X_xWQadr-7j_wUqwt-t-w5uE,20172
-ml_tools/datasetmaster.py,sha256=EFUEX-tqq94Ak1rXXYR-XaX85olrxvF2EuytdzUK7y0,29131
-ml_tools/ensemble_learning.py,sha256=q8qOTbSAwdsgKhjojVm7wn_UApGOCsvFa0mvhLYUuyM,37239
-ml_tools/handle_excel.py,sha256=ZJui5__0rc2T8UGHTheqZGhKmdVZ7Q2I54IoYCjAqJw,12612
-ml_tools/logger.py,sha256=ZTtUB9HTkNs5zHTdYRKNbKADjUkuObsF7s8U5pNnVRA,4716
-ml_tools/particle_swarm_optimization.py,sha256=zaDQTKz2fAixgAfZdkRttGpN2vgraT18ZlpllJlQesk,20034
-ml_tools/pytorch_models.py,sha256=bpWZsrSwCvHJQkR6UfoPpElsMv9AvmiNErNHC8NYB_I,10132
-ml_tools/trainer.py,sha256=WAZ4EdrZuTOAnGXRWV3XcLNce4s7EKGf2-qchLC08Ik,15702
-ml_tools/utilities.py,sha256=r7uEmo38Imly56BP3-Jv6dFJvLsbGipeBlkiZx2fcNQ,10189
-ml_tools/vision_helpers.py,sha256=idQ-Ugp1IdsvwXiYyhYa9G3rTRTm37YRpkQDLEpANHM,7701
-dragon_ml_toolbox-1.4.4.dist-info/METADATA,sha256=8hdr2v8UE5uxieOUSRgjTa5OP1C2BzgjawgxT8ynbQ0,2516
-dragon_ml_toolbox-1.4.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dragon_ml_toolbox-1.4.4.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
-dragon_ml_toolbox-1.4.4.dist-info/RECORD,,