dragon-ml-toolbox 12.0.1__py3-none-any.whl → 12.1.0__py3-none-any.whl

ml_tools/ML_simple_optimization.py

@@ -0,0 +1,413 @@
+import pandas # logger
+import torch
+import numpy    #handling torch to numpy
+import evotorch
+from evotorch.algorithms import SNES, CEM, GeneticAlgorithm
+from evotorch.logging import PandasLogger
+from evotorch.operators import SimulatedBinaryCrossOver, GaussianMutation
+from typing import Literal, Union, Tuple, List, Optional, Any, Callable
+from pathlib import Path
+from tqdm.auto import trange
+from contextlib import nullcontext
+from functools import partial
+
+from .path_manager import make_fullpath, sanitize_filename
+from ._logger import _LOGGER
+from ._script_info import _script_info
+from .ML_inference import PyTorchInferenceHandler
+from .keys import PyTorchInferenceKeys
+from .SQL import DatabaseManager
+from .optimization_tools import _save_result
+from .utilities import save_dataframe
+from .math_utilities import threshold_binary_values
+
+"""
+DEPRECATED
+"""
+
+__all__ = [
+    "s_MLOptimizer",
+    "s_create_pytorch_problem",
+    "s_run_optimization"
+]
+
+
+class s_MLOptimizer:
+    """
+    A wrapper class for setting up and running EvoTorch optimization tasks.
+
+    This class combines the functionality of `create_pytorch_problem` and
+    `run_optimization` functions into a single, streamlined workflow. 
+    
+    SNES and CEM algorithms do not accept bounds, the given bounds will be used as an initial starting point.
+
+    Example:
+        >>> # 1. Initialize the optimizer with model and search parameters
+        >>> optimizer = MLOptimizer(
+        ...     inference_handler=my_handler,
+        ...     bounds=(lower_bounds, upper_bounds),
+        ...     number_binary_features=2,
+        ...     task="max",
+        ...     algorithm="Genetic"
+        ... )
+        >>> # 2. Run the optimization and save the results
+        >>> best_result = optimizer.run(
+        ...     num_generations=100,
+        ...     target_name="my_target",
+        ...     feature_names=my_feature_names,
+        ...     save_dir="/path/to/results",
+        ...     save_format="csv"
+        ... )
+    """
+    def __init__(self,
+                 inference_handler: PyTorchInferenceHandler,
+                 bounds: Tuple[List[float], List[float]],
+                 number_binary_features: int,
+                 task: Literal["min", "max"],
+                 algorithm: Literal["SNES", "CEM", "Genetic"] = "Genetic",
+                 population_size: int = 200,
+                 **searcher_kwargs):
+        """
+        Initializes the optimizer by creating the EvoTorch problem and searcher.
+
+        Args:
+            inference_handler (PyTorchInferenceHandler): An initialized inference handler containing the model and weights.
+            bounds (tuple[list[float], list[float]]): A tuple containing the lower and upper bounds for the solution features.
+            number_binary_features (int): Number of binary features located at the END of the feature vector.
+            task (str): The optimization goal, either "min" or "max".
+            algorithm (str): The search algorithm to use ("SNES", "CEM", "Genetic").
+            population_size (int): Population size for CEM and GeneticAlgorithm.
+            **searcher_kwargs: Additional keyword arguments for the selected search algorithm's constructor.
+        """
+        # Call the existing factory function to get the problem and searcher factory
+        self.problem, self.searcher_factory = s_create_pytorch_problem(
+            inference_handler=inference_handler,
+            bounds=bounds,
+            binary_features=number_binary_features,
+            task=task,
+            algorithm=algorithm,
+            population_size=population_size,
+            **searcher_kwargs
+        )
+        # Store binary_features count to pass it to the run function later
+        self._binary_features = number_binary_features
+
+    def run(self,
+            num_generations: int,
+            target_name: str,
+            save_dir: Union[str, Path],
+            feature_names: Optional[List[str]],
+            save_format: Literal['csv', 'sqlite', 'both'],
+            repetitions: int = 1,
+            verbose: bool = True) -> Optional[dict]:
+        """
+        Runs the evolutionary optimization process using the pre-configured settings.
+
+        Args:
+            num_generations (int): The total number of generations for each repetition.
+            target_name (str): Target name used for the CSV filename and/or SQL table.
+            save_dir (str | Path): The directory where result files will be saved.
+            feature_names (List[str] | None): Names of the solution features for labeling output. If None, generic names like 'feature_0', 'feature_1', ... , will be created.
+            save_format (Literal['csv', 'sqlite', 'both']): The format for saving results.
+            repetitions (int): The number of independent times to run the optimization.
+            verbose (bool): If True, enables detailed logging.
+
+        Returns:
+            Optional[dict]: A dictionary with the best result if repetitions is 1, otherwise None.
+        """
+        # Call the existing run function with the stored problem, searcher, and binary feature count
+        return s_run_optimization(
+            problem=self.problem,
+            searcher_factory=self.searcher_factory,
+            num_generations=num_generations,
+            target_name=target_name,
+            binary_features=self._binary_features,
+            save_dir=save_dir,
+            save_format=save_format,
+            feature_names=feature_names,
+            repetitions=repetitions,
+            verbose=verbose
+        )
+
+
+def s_create_pytorch_problem(
+    inference_handler: PyTorchInferenceHandler,
+    bounds: Tuple[List[float], List[float]],
+    binary_features: int,
+    task: Literal["min", "max"],
+    algorithm: Literal["SNES", "CEM", "Genetic"] = "Genetic",
+    population_size: int = 200,
+    **searcher_kwargs
+) -> Tuple[evotorch.Problem, Callable[[], Any]]:
+    """
+    Creates and configures an EvoTorch Problem and a Searcher factory class for a PyTorch model.
+    
+    SNES and CEM do not accept bounds, the given bounds will be used as an initial starting point.
+    
+    The Genetic Algorithm works directly with the bounds, and operators such as SimulatedBinaryCrossOver and GaussianMutation.
+    
+    Args:
+        inference_handler (PyTorchInferenceHandler): An initialized inference handler containing the model and weights.
+        bounds (tuple[list[float], list[float]]): A tuple containing the lower and upper bounds for the solution features.
+        binary_features (int): Number of binary features located at the END of the feature vector. Will be automatically added to the bounds.
+        task (str): The optimization goal, either "minimize" or "maximize".
+        algorithm (str): The search algorithm to use.
+        population_size (int): Used for CEM and GeneticAlgorithm.
+        **searcher_kwargs: Additional keyword arguments to pass to the
+            selected search algorithm's constructor (e.g., stdev_init=0.5 for CMAES).
+
+    Returns:
+        Tuple:
+        A tuple containing the configured Problem and Searcher.
+    """
+    # Create copies to avoid modifying the original lists passed in the `bounds` tuple
+    lower_bounds = list(bounds[0])
+    upper_bounds = list(bounds[1])
+    
+    # add binary bounds
+    if binary_features > 0:
+        lower_bounds.extend([0.48] * binary_features)
+        upper_bounds.extend([0.52] * binary_features)
+    
+    solution_length = len(lower_bounds)
+    device = inference_handler.device
+
+    # Define the fitness function that EvoTorch will call.
+    def fitness_func(solution_tensor: torch.Tensor) -> torch.Tensor:
+        # Directly use the continuous-valued tensor from the optimizer for prediction
+        predictions = inference_handler.predict_batch(solution_tensor)[PyTorchInferenceKeys.PREDICTIONS]
+        return predictions.flatten()
+    
+    
+    # Create the Problem instance.
+    if algorithm == "CEM" or algorithm == "SNES":
+        problem = evotorch.Problem(
+            objective_sense=task,
+            objective_func=fitness_func,
+            solution_length=solution_length,
+            initial_bounds=(lower_bounds, upper_bounds),
+            device=device,
+            vectorized=True #Use batches
+        )
+        
+        # If stdev_init is not provided, calculate it based on the bounds (used for SNES and CEM)
+        if 'stdev_init' not in searcher_kwargs:
+            # Calculate stdev for each parameter as 25% of its search range
+            stdevs = [abs(up - low) * 0.25 for low, up in zip(lower_bounds, upper_bounds)]
+            searcher_kwargs['stdev_init'] = torch.tensor(stdevs, dtype=torch.float32, requires_grad=False)
+        
+        if algorithm == "SNES":
+            SearcherClass = SNES
+        elif algorithm == "CEM":
+            SearcherClass = CEM
+            # Set a defaults for CEM if not provided
+            if 'popsize' not in searcher_kwargs:
+                searcher_kwargs['popsize'] = population_size
+            if 'parenthood_ratio' not in searcher_kwargs:
+                searcher_kwargs['parenthood_ratio'] = 0.2   #float 0.0 - 1.0
+        
+    elif algorithm == "Genetic":
+        problem = evotorch.Problem(
+            objective_sense=task,
+            objective_func=fitness_func,
+            solution_length=solution_length,
+            bounds=(lower_bounds, upper_bounds),
+            device=device,
+            vectorized=True #Use batches
+        )
+
+        operators = [
+            SimulatedBinaryCrossOver(problem,
+                                    tournament_size=3,
+                                    eta=0.6),
+            GaussianMutation(problem,
+                            stdev=0.4)
+        ]
+        
+        searcher_kwargs["operators"] = operators
+        if 'popsize' not in searcher_kwargs:
+            searcher_kwargs['popsize'] = population_size
+        
+        SearcherClass = GeneticAlgorithm
+        
+    else:
+        _LOGGER.error(f"Unknown algorithm '{algorithm}'.")
+        raise ValueError()
+    
+    # Create a factory function with all arguments pre-filled
+    searcher_factory = partial(SearcherClass, problem, **searcher_kwargs)
+
+    return problem, searcher_factory
+
+
+def s_run_optimization(
+    problem: evotorch.Problem,
+    searcher_factory: Callable[[],Any],
+    num_generations: int,
+    target_name: str,
+    binary_features: int,
+    save_dir: Union[str, Path],
+    save_format: Literal['csv', 'sqlite', 'both'],
+    feature_names: Optional[List[str]],
+    repetitions: int = 1,
+    verbose: bool = True
+) -> Optional[dict]:
+    """
+    Runs the evolutionary optimization process, with support for multiple repetitions.
+
+    This function serves as the main engine for the optimization task. It takes a
+    configured Problem and a Searcher from EvoTorch and executes the optimization
+    for a specified number of generations.
+
+    It has two modes of operation:
+    1.  **Single Run (repetitions=1):** Executes the optimization once, saves the
+        single best result to a CSV file, and returns it as a dictionary.
+    2.  **Iterative Analysis (repetitions > 1):** Executes the optimization
+        multiple times. Results from each run are streamed incrementally to the
+        specified file formats (CSV and/or SQLite database). In this mode,
+        the function returns None.
+
+    Args:
+        problem (evotorch.Problem): The configured problem instance, which defines
+            the objective function, solution space, and optimization sense.
+        searcher_factory (Callable): The searcher factory to generate fresh evolutionary algorithms.
+        num_generations (int): The total number of generations to run the search algorithm for in each repetition.
+        target_name (str): Target name that will also be used for the CSV filename and SQL table.
+        binary_features (int): Number of binary features located at the END of the feature vector.
+        save_dir (str | Path): The directory where the result file(s) will be saved.
+        save_format (Literal['csv', 'sqlite', 'both'], optional): The format for
+            saving results during iterative analysis.
+        feature_names (List[str], optional): Names of the solution features for
+            labeling the output files. If None, generic names like 'feature_0',
+            'feature_1', etc., will be created.
+        repetitions (int, optional): The number of independent times to run the
+            entire optimization process.
+        verbose (bool): Add an Evotorch Pandas logger saved as a csv. Only for the first repetition.
+
+    Returns:
+        Optional[dict]: A dictionary containing the best feature values and the
+        fitness score if `repetitions` is 1. Returns `None` if `repetitions`
+        is greater than 1, as results are streamed to files instead.
+    """
+    # preprocess paths
+    save_path = make_fullpath(save_dir, make=True, enforce="directory")
+    
+    sanitized_target_name = sanitize_filename(target_name)
+    if not sanitized_target_name.endswith(".csv"):
+        sanitized_target_name = sanitized_target_name + ".csv"
+    
+    csv_path = save_path / sanitized_target_name
+    
+    db_path = save_path / "Optimization.db"
+    db_table_name = target_name
+    
+    # preprocess feature names
+    if feature_names is None:
+        feature_names = [f"feature_{i}" for i in range(problem.solution_length)] # type: ignore
+    
+    # --- SINGLE RUN LOGIC ---
+    if repetitions <= 1:
+        searcher = searcher_factory()
+        _LOGGER.info(f"🤖 Starting optimization with {searcher.__class__.__name__} Algorithm for {num_generations} generations...")
+        # for _ in trange(num_generations, desc="Optimizing"):
+        #     searcher.step()
+        
+        # Attach logger if requested
+        if verbose:
+            pandas_logger = PandasLogger(searcher)
+            
+        searcher.run(num_generations) # Use the built-in run method for simplicity
+            
+        # # DEBUG new searcher objects
+        # for status_key in searcher.iter_status_keys():
+        #     print("===", status_key, "===")
+        #     print(searcher.status[status_key])
+        #     print()
+        
+        # Get results from the .status dictionary 
+        # SNES and CEM use the key 'center' to get mean values if needed    best_solution_tensor = searcher.status["center"]
+        best_solution_container = searcher.status["pop_best"]
+        best_solution_tensor = best_solution_container.values
+        best_fitness = best_solution_container.evals
+
+        best_solution_np = best_solution_tensor.cpu().numpy()
+        
+        # threshold binary features
+        if binary_features > 0:
+            best_solution_thresholded = threshold_binary_values(input_array=best_solution_np, binary_values=binary_features)
+        else:
+            best_solution_thresholded = best_solution_np
+
+        result_dict = {name: value for name, value in zip(feature_names, best_solution_thresholded)}
+        result_dict[target_name] = best_fitness.item()
+        
+        _save_result(result_dict, 'csv', csv_path) # Single run defaults to CSV
+        
+        # Process logger
+        if verbose:
+            _handle_pandas_log(pandas_logger, save_path=save_path, target_name=target_name)
+        
+        _LOGGER.info(f"Optimization complete. Best solution saved to '{csv_path.name}'")
+        return result_dict
+
+    # --- MULTIPLE REPETITIONS LOGIC ---
+    else:
+        _LOGGER.info(f"🏁 Starting optimal solution space analysis with {repetitions} repetitions...")
+
+        db_context = DatabaseManager(db_path) if save_format in ['sqlite', 'both'] else nullcontext()
+        
+        with db_context as db_manager:
+            if db_manager:
+                schema = {name: "REAL" for name in feature_names}
+                schema[target_name] = "REAL"
+                db_manager.create_table(db_table_name, schema)
+            
+            print("")
+            # Repetitions loop
+            pandas_logger = None
+            for i in trange(repetitions, desc="Repetitions"):
+                # CRITICAL: Create a fresh searcher for each run using the factory
+                searcher = searcher_factory()
+                
+                # Attach logger if requested
+                if verbose and i==0:
+                    pandas_logger = PandasLogger(searcher)
+                
+                searcher.run(num_generations) # Use the built-in run method for simplicity
+                
+                # Get results from the .status dictionary 
+                # SNES and CEM use the key 'center' to get mean values if needed    best_solution_tensor = searcher.status["center"]
+                best_solution_container = searcher.status["pop_best"]
+                best_solution_tensor = best_solution_container.values
+                best_fitness = best_solution_container.evals
+             
+                best_solution_np = best_solution_tensor.cpu().numpy()
+                
+                # threshold binary features
+                if binary_features > 0:
+                    best_solution_thresholded = threshold_binary_values(input_array=best_solution_np, binary_values=binary_features)
+                else:
+                    best_solution_thresholded = best_solution_np
+                
+                # make results dictionary
+                result_dict = {name: value for name, value in zip(feature_names, best_solution_thresholded)}
+                result_dict[target_name] = best_fitness.item()
+                
+                # Save each result incrementally
+                _save_result(result_dict, save_format, csv_path, db_manager, db_table_name)
+            
+        # Process logger
+        if pandas_logger is not None:
+            _handle_pandas_log(pandas_logger, save_path=save_path, target_name=target_name)      
+        
+        _LOGGER.info(f"Optimal solution space complete. Results saved to '{save_path}'")
+        return None
+
+
+def _handle_pandas_log(logger: PandasLogger, save_path: Path, target_name: str):
+    log_dataframe = logger.to_dataframe()
+    save_dataframe(df=log_dataframe, save_dir=save_path / "EvolutionLogs", filename=target_name)
+
+
+def info():
+    _script_info(__all__)

ml_tools/data_exploration.py

@@ -29,6 +29,7 @@ __all__ = [
     "plot_value_distributions", 
     "clip_outliers_single", 
     "clip_outliers_multi",
+    "drop_outlier_samples",
     "match_and_filter_columns_by_regex",
     "standardize_percentages",
     "create_transformer_categorical_map",
@@ -358,8 +359,8 @@ def encode_categorical_features(
         df (pd.DataFrame): The input DataFrame.
         columns_to_encode (List[str]): A list of column names to be encoded.
         encode_nulls (bool): If True, encodes Null values as a distinct category
-            "Other" with a value of 0. Other categories start from 1.
-            If False, Nulls are ignored.
+            "Other" with a value of 0. Other categories start from 1. 
+            If False, Nulls are ignored and categories start from 0.
         split_resulting_dataset (bool): If True, returns two separate DataFrames:
             one with non-categorical columns and one with the encoded columns.
             If False, returns a single DataFrame with all columns.
@@ -758,7 +759,99 @@ def clip_outliers_multi(
     if skipped_columns:
         _LOGGER.warning("Skipped columns:")
         for col, msg in skipped_columns:
-            print(f" - {col}: {msg}")
+            print(f" - {col}")
+
+    return new_df
+
+
+def drop_outlier_samples(
+    df: pd.DataFrame,
+    bounds_dict: Dict[str, Tuple[Union[int, float], Union[int, float]]],
+    drop_on_nulls: bool = False,
+    verbose: bool = True
+) -> pd.DataFrame:
+    """
+    Drops entire rows where values in specified numeric columns fall outside
+    a given [min, max] range.
+
+    This function processes a copy of the DataFrame, ensuring the original is
+    not modified. It skips columns with invalid specifications.
+
+    Args:
+        df (pd.DataFrame): The input DataFrame.
+        bounds_dict (dict): A dictionary where keys are column names and values
+                            are (min_val, max_val) tuples defining the valid range.
+        drop_on_nulls (bool): If True, rows with NaN/None in a checked column
+                           will also be dropped. If False, NaN/None are ignored.
+        verbose (bool): If True, prints the number of rows dropped for each column.
+
+    Returns:
+        pd.DataFrame: A new DataFrame with the outlier rows removed.
+
+    Notes:
+        - Invalid specifications (e.g., missing column, non-numeric type,
+          incorrectly formatted bounds) will be reported and skipped.
+    """
+    new_df = df.copy()
+    skipped_columns: List[Tuple[str, str]] = []
+    initial_rows = len(new_df)
+
+    for col, bounds in bounds_dict.items():
+        try:
+            # --- Validation Checks ---
+            if col not in df.columns:
+                _LOGGER.error(f"Column '{col}' not found in DataFrame.")
+                raise ValueError()
+
+            if not pd.api.types.is_numeric_dtype(df[col]):
+                _LOGGER.error(f"Column '{col}' is not of a numeric data type.")
+                raise TypeError()
+
+            if not (isinstance(bounds, tuple) and len(bounds) == 2):
+                _LOGGER.error(f"Bounds for '{col}' must be a tuple of (min, max).")
+                raise ValueError()
+
+            # --- Filtering Logic ---
+            min_val, max_val = bounds
+            rows_before_drop = len(new_df)
+            
+            # Create the base mask for values within the specified range
+            # .between() is inclusive and evaluates to False for NaN
+            mask_in_bounds = new_df[col].between(min_val, max_val)
+
+            if drop_on_nulls:
+                # Keep only rows that are within bounds.
+                # Since mask_in_bounds is False for NaN, nulls are dropped.
+                final_mask = mask_in_bounds
+            else:
+                # Keep rows that are within bounds OR are null.
+                mask_is_null = new_df[col].isnull()
+                final_mask = mask_in_bounds | mask_is_null
+            
+            # Apply the final mask
+            new_df = new_df[final_mask]
+            
+            rows_after_drop = len(new_df)
+
+            if verbose:
+                dropped_count = rows_before_drop - rows_after_drop
+                if dropped_count > 0:
+                    print(
+                        f"  - Column '{col}': Dropped {dropped_count} rows with values outside range [{min_val}, {max_val}]."
+                    )
+
+        except (ValueError, TypeError) as e:
+            skipped_columns.append((col, str(e)))
+            continue
+
+    total_dropped = initial_rows - len(new_df)
+    _LOGGER.info(f"Finished processing. Total rows dropped: {total_dropped}.")
+
+    if skipped_columns:
+        _LOGGER.warning("Skipped the following columns due to errors:")
+        for col, msg in skipped_columns:
+            # Only print the column name for cleaner output as the error was already logged
+            print(f" - {col}")
 
     return new_df
 

ml_tools/math_utilities.py

@@ -174,16 +174,18 @@ def threshold_binary_values_batch(
 def discretize_categorical_values(
     input_array: np.ndarray,
     categorical_info: dict[int, int],
-    start_at_zero: bool = False
+    start_at_zero: bool = True
 ) -> np.ndarray:
     """
     Rounds specified columns of a 2D NumPy array to the nearest integer and
     clamps the result to a valid categorical range.
+    
+    If a 1D array is provided, it is treated as a single batch.
 
     Parameters
     ----------
     input_array : np.ndarray
-        2D array with shape (batch_size, n_features) containing continuous values.
+        1D array (n_features,) or 2D array with shape (batch_size, n_features) containing continuous values.
     categorical_info : dict[int, int]
         A dictionary mapping column indices to their cardinality (number of categories).
         Example: {3: 4} means column 3 will be clamped to its 4 valid categories.
@@ -195,10 +197,22 @@ def discretize_categorical_values(
     -------
     np.ndarray
         A new array with the specified columns converted to integer categories.
+        Shape matches the input array's original shape.
     """
     # --- Input Validation ---
-    if input_array.ndim != 2:
-        _LOGGER.error(f"Expected 2D array, got {input_array.ndim}D array.")
+    if not isinstance(input_array, np.ndarray):
+         _LOGGER.error(f"Expected np.ndarray, got {type(input_array)}.")
+         raise ValueError()
+    
+    if input_array.ndim == 1:
+        # Reshape 1D array (n_features,) to 2D (1, n_features)
+        working_array = input_array.reshape(1, -1)
+        original_was_1d = True
+    elif input_array.ndim == 2:
+        working_array = input_array
+        original_was_1d = False
+    else:
+        _LOGGER.error(f"Expected 1D or 2D array, got {input_array.ndim}D array.")
         raise ValueError()
 
     if not isinstance(categorical_info, dict) or not categorical_info:
@@ -207,6 +221,9 @@ def discretize_categorical_values(
 
     _, total_features = input_array.shape
     for col_idx, cardinality in categorical_info.items():
+        if not isinstance(col_idx, int):
+             _LOGGER.error(f"Column index key {col_idx} is not an integer.")
+             raise TypeError()
         if not (0 <= col_idx < total_features):
             _LOGGER.error(f"Column index {col_idx} is out of bounds for an array with {total_features} features.")
             raise ValueError()
@@ -215,7 +232,7 @@ def discretize_categorical_values(
             raise ValueError()
 
     # --- Core Logic ---
-    output_array = input_array.copy()
+    output_array = working_array.copy()
 
     for col_idx, cardinality in categorical_info.items():
         # 1. Round the column values using "round half up"
@@ -228,7 +245,14 @@ def discretize_categorical_values(
         # 3. Clamp the values and update the output array
         output_array[:, col_idx] = np.clip(rounded_col, min_bound, max_bound)
     
-    return output_array.astype(np.int32)
+    final_output = output_array.astype(np.int32)
+    
+    # --- Output Shape Handling ---
+    if original_was_1d:
+        # Squeeze the batch dimension to return a 1D array
+        return final_output.squeeze(axis=0)
+    else:
+        return final_output
 
 
 def info():