dragon-ml-toolbox 7.0.0__py3-none-any.whl → 8.1.0__py3-none-any.whl

ml_tools/ML_trainer.py

@@ -7,6 +7,7 @@ import numpy as np
 
 from .ML_callbacks import Callback, History, TqdmProgressBar
 from .ML_evaluation import classification_metrics, regression_metrics, plot_losses, shap_summary_plot, plot_attention_importance
+from .ML_evaluation_multi import multi_target_regression_metrics, multi_label_classification_metrics, multi_target_shap_summary_plot
 from ._script_info import _script_info
 from .keys import PyTorchLogKeys
 from ._logger import _LOGGER
@@ -19,7 +20,7 @@ __all__ = [
 
 class MLTrainer:
     def __init__(self, model: nn.Module, train_dataset: Dataset, test_dataset: Dataset, 
-                 kind: Literal["regression", "classification"],
+                 kind: Literal["regression", "classification", "multi_target_regression", "multi_label_classification"],
                  criterion: nn.Module, optimizer: torch.optim.Optimizer, 
                  device: Union[Literal['cuda', 'mps', 'cpu'],str], dataloader_workers: int = 2, callbacks: Optional[List[Callback]] = None):
         """
@@ -31,20 +32,22 @@ class MLTrainer:
             model (nn.Module): The PyTorch model to train.
             train_dataset (Dataset): The training dataset.
             test_dataset (Dataset): The testing/validation dataset.
-            kind (str): The type of task, 'regression' or 'classification'.
+            kind (str): Can be 'regression', 'classification', 'multi_target_regression', or 'multi_label_classification'.
             criterion (nn.Module): The loss function.
             optimizer (torch.optim.Optimizer): The optimizer.
             device (str): The device to run training on ('cpu', 'cuda', 'mps').
-            dataloader_workers (int): Subprocesses for data loading. Defaults to 2.
+            dataloader_workers (int): Subprocesses for data loading.
             callbacks (List[Callback] | None): A list of callbacks to use during training.
             
         Note:
-            For **regression** tasks, suggested criterions include `nn.MSELoss` or `nn.L1Loss`.
-            
-            For **classification** tasks, `nn.CrossEntropyLoss` (multi-class) or `nn.BCEWithLogitsLoss` (binary) are common choices.
+            - For **regression** and **multi_target_regression** tasks, suggested criterions include `nn.MSELoss` or `nn.L1Loss`.
+    
+            - For **single-label, multi-class classification** tasks, `nn.CrossEntropyLoss` is the standard choice.
+    
+            - For **multi-label, binary classification** tasks (where each label is a 0 or 1), `nn.BCEWithLogitsLoss` is the correct choice as it treats each output as an independent binary problem.
         """
-        if kind not in ["regression", "classification"]:
-            raise TypeError("Kind must be 'regression' or 'classification'.")
+        if kind not in ["regression", "classification", "multi_target_regression", "multi_label_classification"]:
+            raise ValueError(f"'{kind}' is not a valid task type.")
 
         self.model = model
         self.train_dataset = train_dataset
@@ -157,7 +160,6 @@ class MLTrainer:
     def _train_step(self):
         self.model.train()
         running_loss = 0.0
-        # Enumerate to get batch index
         for batch_idx, (features, target) in enumerate(self.train_loader): # type: ignore
             # Create a log dictionary for the batch
             batch_logs = {
@@ -168,22 +170,26 @@ class MLTrainer:
 
             features, target = features.to(self.device), target.to(self.device)
             self.optimizer.zero_grad()
+            
             output = self.model(features)
-            if isinstance(self.criterion, (nn.MSELoss, nn.L1Loss)):
+            
+            # Apply shape correction only for single-target regression
+            if self.kind == "regression":
                 output = output.view_as(target)
+                
             loss = self.criterion(output, target)
+            
             loss.backward()
             self.optimizer.step()
 
             # Calculate batch loss and update running loss for the epoch
             batch_loss = loss.item()
             running_loss += batch_loss * features.size(0)
-
+            
             # Add the batch loss to the logs and call the end-of-batch hook
             batch_logs[PyTorchLogKeys.BATCH_LOSS] = batch_loss
             self.callbacks_hook('on_batch_end', batch_idx, logs=batch_logs)
 
-        # Return the average loss for the entire epoch
         return {PyTorchLogKeys.TRAIN_LOSS: running_loss / len(self.train_loader.dataset)} # type: ignore
 
     def _validation_step(self):
@@ -192,25 +198,27 @@ class MLTrainer:
         with torch.no_grad():
             for features, target in self.test_loader: # type: ignore
                 features, target = features.to(self.device), target.to(self.device)
+                
                 output = self.model(features)
-                if isinstance(self.criterion, (nn.MSELoss, nn.L1Loss)):
+                # Apply shape correction only for single-target regression
+                if self.kind == "regression":
                     output = output.view_as(target)
+                
                 loss = self.criterion(output, target)
+                
                 running_loss += loss.item() * features.size(0)
+        
         logs = {PyTorchLogKeys.VAL_LOSS: running_loss / len(self.test_loader.dataset)} # type: ignore
         return logs
     
-    def _predict_for_eval(self, dataloader: DataLoader):
+    def _predict_for_eval(self, dataloader: DataLoader, classification_threshold: float = 0.5):
         """
         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.
-
+        
         Yields:
             tuple: A tuple containing (y_pred_batch, y_prob_batch, y_true_batch).
-                   y_prob_batch is None for regression tasks.
+                   
+                - y_prob_batch is None for regression tasks.
         """
         self.model.eval()
         self.model.to(self.device)
@@ -220,84 +228,135 @@ class MLTrainer:
                 output = self.model(features).cpu()
                 y_true_batch = target.numpy()
 
-                if self.kind == "classification":
-                    probs = nn.functional.softmax(output, dim=1)
+                y_pred_batch = None
+                y_prob_batch = None
+
+                if self.kind in ["regression", "multi_target_regression"]:
+                    y_pred_batch = output.numpy()
+
+                elif self.kind == "classification":
+                    probs = torch.softmax(output, dim=1)
                     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
-                
+
+                elif self.kind == "multi_label_classification":
+                    probs = torch.sigmoid(output)
+                    preds = (probs >= classification_threshold).int()
+                    y_pred_batch = preds.numpy()
+                    y_prob_batch = probs.numpy()
+
                 yield y_pred_batch, y_prob_batch, y_true_batch
-    
-    def evaluate(self, save_dir: Union[str,Path], data: Optional[Union[DataLoader, Dataset]] = None):
+
+    def evaluate(self, save_dir: Union[str, Path], data: Optional[Union[DataLoader, Dataset]] = None, classification_threshold: float = 0.5):
         """
-        Evaluates the model on the given data.
+        Evaluates the model, routing to the correct evaluation function based on task `kind`.
 
         Args:
-            data (DataLoader | Dataset | None ): The data to evaluate on.
-                Can be a DataLoader or a Dataset. If None, defaults to the trainer's internal test_dataset.
             save_dir (str | Path): Directory to save all reports and plots.
+            data (DataLoader | Dataset | None): The data to evaluate on. If None, defaults to the trainer's internal test_dataset.
+            classification_threshold (float): Probability threshold for multi-label tasks.
         """
+        dataset_for_names = None
         eval_loader = None
+
         if isinstance(data, DataLoader):
             eval_loader = data
-        else:
-            # Determine which dataset to use (the one passed in, or the default test_dataset)
-            dataset_to_use = data if data is not None else self.test_dataset
-            if not isinstance(dataset_to_use, Dataset):
-                raise ValueError("Cannot evaluate. No valid DataLoader or Dataset was provided, "
-                                 "and no test_dataset is available in the trainer.")
-
-            # Create a new DataLoader from the dataset
-            eval_loader = DataLoader(
-                dataset=dataset_to_use,
-                batch_size=32,  # A sensible default for evaluation
-                shuffle=False,
-                num_workers=0 if self.device.type == 'mps' else self.dataloader_workers,
-                pin_memory=(self.device.type == "cuda")
-            )
-            
+            # Try to get the dataset from the loader for fetching target names
+            if hasattr(data, 'dataset'):
+                dataset_for_names = data.dataset
+        elif isinstance(data, Dataset):
+            # Create a new loader from the provided dataset
+            eval_loader = DataLoader(data, 
+                                     batch_size=32, 
+                                     shuffle=False, 
+                                     num_workers=0 if self.device.type == 'mps' else self.dataloader_workers,
+                                     pin_memory=(self.device.type == "cuda"))
+            dataset_for_names = data
+        else: # data is None, use the trainer's default test dataset
+            if self.test_dataset is None:
+                raise ValueError("Cannot evaluate. No data provided and no test_dataset available in the trainer.")
+            # Create a fresh DataLoader from the test_dataset
+            eval_loader = DataLoader(self.test_dataset, 
+                                     batch_size=32, 
+                                     shuffle=False, 
+                                     num_workers=0 if self.device.type == 'mps' else self.dataloader_workers,
+                                     pin_memory=(self.device.type == "cuda"))
+            dataset_for_names = self.test_dataset
+
+        if eval_loader is None:
+            raise ValueError("Cannot evaluate. No valid data was provided or found.")
+
         print("\n--- Model Evaluation ---")
 
-        # 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_for_eval(eval_loader):
-            all_preds.append(y_pred_b)
-            if y_prob_b is not None:
-                all_probs.append(y_prob_b)
-            all_true.append(y_true_b)
+        for y_pred_b, y_prob_b, y_true_b in self._predict_for_eval(eval_loader, classification_threshold):
+            if y_pred_b is not None: all_preds.append(y_pred_b)
+            if y_prob_b is not None: all_probs.append(y_prob_b)
+            if y_true_b is not None: all_true.append(y_true_b)
+
+        if not all_true:
+            _LOGGER.error("❌ Evaluation failed: No data was processed.")
+            return
 
         y_pred = np.concatenate(all_preds)
         y_true = np.concatenate(all_true)
-        y_prob = np.concatenate(all_probs) if self.kind == "classification" else None
+        y_prob = np.concatenate(all_probs) if all_probs else None
 
-        if self.kind == "classification":
-            classification_metrics(save_dir, y_true, y_pred, y_prob)
-        else:
+        # --- Routing Logic ---
+        if self.kind == "regression":
             regression_metrics(y_true.flatten(), y_pred.flatten(), save_dir)
 
+        elif self.kind == "classification":
+            classification_metrics(save_dir, y_true, y_pred, y_prob)
+
+        elif self.kind == "multi_target_regression":
+            try:
+                target_names = dataset_for_names.target_names # type: ignore
+            except AttributeError:
+                num_targets = y_true.shape[1]
+                target_names = [f"target_{i}" for i in range(num_targets)]
+                _LOGGER.warning(f"⚠️ Dataset has no 'target_names' attribute. Using generic names.")
+            multi_target_regression_metrics(y_true, y_pred, target_names, save_dir)
+
+        elif self.kind == "multi_label_classification":
+            try:
+                target_names = dataset_for_names.target_names # type: ignore
+            except AttributeError:
+                num_targets = y_true.shape[1]
+                target_names = [f"label_{i}" for i in range(num_targets)]
+                _LOGGER.warning(f"⚠️ Dataset has no 'target_names' attribute. Using generic names.")
+            
+            if y_prob is None:
+                _LOGGER.error("❌ Evaluation for multi_label_classification requires probabilities (y_prob).")
+                return
+            multi_label_classification_metrics(y_true, y_prob, target_names, save_dir, classification_threshold)
+
         print("\n--- Training History ---")
         plot_losses(self.history, save_dir=save_dir)
     
     def explain(self,
-                feature_names: Optional[List[str]], 
                 save_dir: Union[str,Path], 
                 explain_dataset: Optional[Dataset] = None, 
-                n_samples: int = 1000):
+                n_samples: int = 1000,
+                feature_names: Optional[List[str]] = None,
+                target_names: Optional[List[str]] = None):
         """
         Explains model predictions using SHAP and saves all artifacts.
 
         The background data is automatically sampled from the trainer's training dataset.
+        
+        This method automatically routes to the appropriate SHAP summary plot
+        function based on the task. If `feature_names` or `target_names` (multi-target) are not provided,
+        it will attempt to extract them from the dataset.
 
         Args:
-            explain_dataset (Dataset, optional): A specific dataset to explain. 
+            explain_dataset (Dataset | None): A specific dataset to explain. 
                                                  If None, the trainer's test dataset is used.
             n_samples (int): The number of samples to use for both background and explanation.
-            feature_names (List[str], optional): Names for the features.
-            save_dir (str, optional): Directory to save all SHAP artifacts.
+            feature_names (list[str] | None): Feature names.
+            target_names (list[str] | None): Target names
+            save_dir (str | Path): Directory to save all SHAP artifacts.
         """
         # Internal helper to create a dataloader and get a random sample
         def _get_random_sample(dataset: Dataset, num_samples: int):
@@ -340,16 +399,54 @@ class MLTrainer:
         if instances_to_explain is None:
             _LOGGER.error("❌ Explanation dataset is empty or invalid. Skipping SHAP analysis.")
             return
+        
+        # attempt to get feature names
+        if feature_names is None:
+            # _LOGGER.info("`feature_names` not provided. Attempting to extract from dataset...")
+            if hasattr(target_dataset, "feature_names"):
+                feature_names = target_dataset.feature_names # type: ignore
+            else:
+                try:
+                # Handle PyTorch Subset 
+                    feature_names = target_dataset.dataset.feature_names # type: ignore
+                except AttributeError:
+                    _LOGGER.error("❌ Could not extract `feature_names` from the dataset.")
+                    raise ValueError("`feature_names` must be provided if the dataset object does not have a `feature_names` attribute.")
 
         # 3. Call the plotting function
-        shap_summary_plot(
-            model=self.model,
-            background_data=background_data,
-            instances_to_explain=instances_to_explain,
-            feature_names=feature_names,
-            save_dir=save_dir
-        )
-    
+        if self.kind in ["regression", "classification"]:
+            shap_summary_plot(
+                model=self.model,
+                background_data=background_data,
+                instances_to_explain=instances_to_explain,
+                feature_names=feature_names,
+                save_dir=save_dir
+            )
+        elif self.kind in ["multi_target_regression", "multi_label_classification"]:
+            # try to get target names
+            if target_names is None:
+                target_names = []
+                if hasattr(target_dataset, 'target_names'):
+                    target_names = target_dataset.target_names # type: ignore
+                else:
+                    # Infer number of targets from the model's output layer
+                    try:
+                        num_targets = self.model.output_layer.out_features # type: ignore
+                        target_names = [f"target_{i}" for i in range(num_targets)] # type: ignore
+                        _LOGGER.warning("Dataset has no 'target_names' attribute. Using generic names.")
+                    except AttributeError:
+                        _LOGGER.error("Cannot determine target names for multi-target SHAP plot. Skipping.")
+                        return
+
+            multi_target_shap_summary_plot(
+                model=self.model,
+                background_data=background_data,
+                instances_to_explain=instances_to_explain,
+                feature_names=feature_names, # type: ignore
+                target_names=target_names, # type: ignore
+                save_dir=save_dir
+            )
+
     def _attention_helper(self, dataloader: DataLoader):
         """
         Private method to yield model attention weights batch by batch for evaluation.

ml_tools/_ML_optimization_multi.py

@@ -0,0 +1,231 @@
+import pandas as pd
+import torch
+import numpy as np
+import evotorch
+from evotorch.algorithms import NSGA2
+from evotorch.logging import PandasLogger
+from typing import Literal, Union, Tuple, List, Optional, Any, Callable
+from pathlib import Path
+from tqdm.auto import trange
+from functools import partial
+from contextlib import nullcontext
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+from .path_manager import make_fullpath, sanitize_filename
+from ._logger import _LOGGER
+from ._script_info import _script_info
+from .ML_inference import PyTorchInferenceHandlerMulti # Using the multi-target handler
+from .keys import PyTorchInferenceKeys
+from .utilities import threshold_binary_values, save_dataframe
+from .SQL import DatabaseManager # Added for SQL saving
+
+__all__ = [
+    "create_multi_objective_problem",
+    "run_multi_objective_optimization",
+    "plot_pareto_front"
+]
+
+
+def create_multi_objective_problem(
+    inference_handler: PyTorchInferenceHandlerMulti,
+    bounds: Tuple[List[float], List[float]],
+    binary_features: int,
+    objective_senses: Tuple[Literal["min", "max"], ...],
+    algorithm: Literal["NSGA2"] = "NSGA2",
+    population_size: int = 200,
+    **searcher_kwargs
+) -> Tuple[evotorch.Problem, Callable[[], Any]]:
+    """
+    Creates and configures an EvoTorch Problem and a Searcher for multi-objective optimization.
+
+    This function sets up a problem where the goal is to optimize multiple conflicting
+    objectives simultaneously, using an algorithm like NSGA2 to find the Pareto front.
+
+    Args:
+        inference_handler (PyTorchInferenceHandlerMulti): An initialized handler for the multi-target model.
+        bounds (tuple[list[float], list[float]]): Lower and upper bounds for the solution features.
+        binary_features (int): Number of binary features at the end of the feature vector.
+        objective_senses (Tuple[Literal["min", "max"], ...]): A tuple specifying the optimization
+            goal for each target (e.g., ("max", "min", "max")). The length of this tuple
+            must match the number of outputs from the model.
+        algorithm (str): The multi-objective search algorithm to use. Currently supports "NSGA2".
+        population_size (int): The number of solutions in each generation.
+        **searcher_kwargs: Additional keyword arguments for the search algorithm's constructor.
+
+    Returns:
+        A tuple containing the configured multi-objective Problem and the Searcher factory.
+    """
+    lower_bounds, upper_bounds = list(bounds[0]), list(bounds[1])
+
+    if binary_features > 0:
+        lower_bounds.extend([0.45] * binary_features)
+        upper_bounds.extend([0.55] * binary_features)
+
+    solution_length = len(lower_bounds)
+    device = inference_handler.device
+
+    def fitness_func(solution_tensor: torch.Tensor) -> torch.Tensor:
+        """
+        The fitness function for a multi-objective problem.
+        It returns the entire output tensor from the model. EvoTorch handles the rest.
+        """
+        # The handler returns a tensor of shape [batch_size, num_targets]
+        predictions = inference_handler.predict_batch(solution_tensor)[PyTorchInferenceKeys.PREDICTIONS]
+        return predictions
+
+    if algorithm == "NSGA2":
+        problem = evotorch.Problem(
+            objective_sense=objective_senses,
+            objective_func=fitness_func,
+            solution_length=solution_length,
+            bounds=(lower_bounds, upper_bounds),
+            device=device,
+            vectorized=True,
+            num_actors='max' # Use available CPU cores
+        )
+        SearcherClass = NSGA2
+        if 'popsize' not in searcher_kwargs:
+            searcher_kwargs['popsize'] = population_size
+    else:
+        raise ValueError(f"Unknown multi-objective algorithm '{algorithm}'.")
+
+    searcher_factory = partial(SearcherClass, problem, **searcher_kwargs)
+    return problem, searcher_factory
+
+
+def run_multi_objective_optimization(
+    problem: evotorch.Problem,
+    searcher_factory: Callable[[], Any],
+    num_generations: int,
+    run_name: str,
+    binary_features: int,
+    save_dir: Union[str, Path],
+    feature_names: List[str],
+    target_names: List[str],
+    save_format: Literal['csv', 'sqlite', 'both'] = 'csv',
+    verbose: bool = True
+):
+    """
+    Runs the multi-objective evolutionary optimization process to find the Pareto front.
+
+    This function executes a multi-objective algorithm (like NSGA2) and saves the
+    entire set of non-dominated solutions (the Pareto front) to the specified format(s).
+    It also generates and saves a plot of the Pareto front.
+
+    Args:
+        problem (evotorch.Problem): The configured multi-objective problem.
+        searcher_factory (Callable): A factory function to generate a fresh searcher instance.
+        num_generations (int): The number of generations to run the algorithm.
+        run_name (str): A name for this optimization run, used for filenames/table names.
+        binary_features (int): Number of binary features in the solution vector.
+        save_dir (str | Path): The directory where the result files will be saved.
+        feature_names (List[str]): Names of the solution features for labeling columns.
+        target_names (List[str]): Names of the target objectives for labeling columns.
+        save_format (str): The format to save results in ('csv', 'sqlite', or 'both').
+        verbose (bool): If True, attaches a logger and saves the evolution history.
+    """
+    save_path = make_fullpath(save_dir, make=True, enforce="directory")
+    sanitized_run_name = sanitize_filename(run_name)
+    
+    if len(target_names) != problem.num_objectives:
+        raise ValueError("The number of `target_names` must match the number of objectives in the problem.")
+
+    searcher = searcher_factory()
+    _LOGGER.info(f"🤖 Starting multi-objective optimization with {searcher.__class__.__name__} for {num_generations} generations...")
+
+    logger = PandasLogger(searcher) if verbose else None
+    searcher.run(num_generations)
+
+    pareto_front = searcher.status["pareto_front"]
+    _LOGGER.info(f"✅ Optimization complete. Found {len(pareto_front)} non-dominated solutions.")
+
+    solutions_np = pareto_front.values.cpu().numpy()
+    objectives_np = pareto_front.evals.cpu().numpy()
+
+    if binary_features > 0:
+        solutions_np = threshold_binary_values(input_array=solutions_np, binary_values=binary_features)
+
+    results_df = pd.DataFrame(solutions_np, columns=feature_names)
+    objective_cols = []
+    for i, name in enumerate(target_names):
+        col_name = f"predicted_{name}"
+        results_df[col_name] = objectives_np[:, i]
+        objective_cols.append(col_name)
+
+    # --- Saving Logic ---
+    if save_format in ['csv', 'both']:
+        csv_path = save_path / f"pareto_front_{sanitized_run_name}.csv"
+        results_df.to_csv(csv_path, index=False)
+        _LOGGER.info(f"📄 Pareto front data saved to '{csv_path.name}'")
+
+    if save_format in ['sqlite', 'both']:
+        db_path = save_path / "Optimization_Multi.db"
+        with DatabaseManager(db_path) as db:
+            db.insert_from_dataframe(
+                table_name=sanitized_run_name,
+                df=results_df,
+                if_exists='replace'
+            )
+        _LOGGER.info(f"🗃️ Pareto front data saved to table '{sanitized_run_name}' in '{db_path.name}'")
+
+    # --- Plotting Logic ---
+    plot_pareto_front(
+        results_df,
+        objective_cols=objective_cols,
+        save_path=save_path / f"pareto_plot_{sanitized_run_name}.svg"
+    )
+
+    if logger:
+        log_df = logger.to_dataframe()
+        save_dataframe(df=log_df, save_dir=save_path / "EvolutionLogs", filename=f"log_{sanitized_run_name}")
+
+
+def plot_pareto_front(results_df: pd.DataFrame, objective_cols: List[str], save_path: Path):
+    """
+    Generates and saves a plot of the Pareto front.
+
+    - For 2 objectives, it creates a 2D scatter plot.
+    - For 3 objectives, it creates a 3D scatter plot.
+    - For >3 objectives, it creates a scatter plot matrix (pairs plot).
+
+    Args:
+        results_df (pd.DataFrame): DataFrame containing the optimization results.
+        objective_cols (List[str]): The names of the columns that hold the objective values.
+        save_path (Path): The full path (including filename) to save the SVG plot.
+    """
+    num_objectives = len(objective_cols)
+    _LOGGER.info(f"🎨 Generating Pareto front plot for {num_objectives} objectives...")
+
+    plt.style.use('seaborn-v0_8-whitegrid')
+
+    if num_objectives == 2:
+        fig, ax = plt.subplots(figsize=(8, 6), dpi=120)
+        ax.scatter(results_df[objective_cols[0]], results_df[objective_cols[1]], alpha=0.7, edgecolors='k')
+        ax.set_xlabel(objective_cols[0])
+        ax.set_ylabel(objective_cols[1])
+        ax.set_title("Pareto Front (2D)")
+    
+    elif num_objectives == 3:
+        fig = plt.figure(figsize=(9, 7), dpi=120)
+        ax = fig.add_subplot(111, projection='3d')
+        ax.scatter(results_df[objective_cols[0]], results_df[objective_cols[1]], results_df[objective_cols[2]], alpha=0.7, depthshade=True)
+        ax.set_xlabel(objective_cols[0])
+        ax.set_ylabel(objective_cols[1])
+        ax.set_zlabel(objective_cols[2])
+        ax.set_title("Pareto Front (3D)")
+
+    else: # > 3 objectives
+        _LOGGER.info("  -> More than 3 objectives found, generating a scatter plot matrix.")
+        g = sns.pairplot(results_df[objective_cols], diag_kind="kde", plot_kws={'alpha': 0.6})
+        g.fig.suptitle("Pareto Front (Pairs Plot)", y=1.02)
+        plt.savefig(save_path, bbox_inches='tight')
+        plt.close()
+        _LOGGER.info(f"📊 Pareto plot saved to '{save_path.name}'")
+        return
+
+    plt.tight_layout()
+    plt.savefig(save_path)
+    plt.close()
+    _LOGGER.info(f"📊 Pareto plot saved to '{save_path.name}'")
+