0.27.10 doc

Author: bartzbeielstein

pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spotpython"
-version = "0.27.8"
+version = "0.27.10"
 authors = [
   { name="T. Bartz-Beielstein", email="tbb@bartzundbartz.de" }
 ]

src/spotpython/design/utils.py

@@ -0,0 +1,152 @@
+import numpy as np
+import pandas as pd
+from typing import Union
+
+
+def get_boundaries(data: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Calculates the minimum and maximum values for each column in a NumPy array.
+
+    Args:
+        data (np.ndarray): A NumPy array of shape (n, k), where n is the number of rows
+            and k is the number of columns.
+
+    Returns:
+        tuple[np.ndarray, np.ndarray]: A tuple containing two NumPy arrays:
+            - The first array contains the minimum values for each column, with shape (k,).
+            - The second array contains the maximum values for each column, with shape (k,).
+
+    Raises:
+        ValueError: If the input array has shape (1, 0) (empty array).
+
+    Examples:
+        >>> from spotpython.design.utils import get_boundaries
+        >>> import numpy as np
+        >>> data = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+        >>> min_values, max_values = get_boundaries(data)
+        >>> print("Minimum values:", min_values)
+        Minimum values: [1 2 3]
+        >>> print("Maximum values:", max_values)
+        Maximum values: [7 8 9]
+    """
+    if data.size == 0:
+        raise ValueError("Input array cannot be empty.")
+    min_values = np.min(data, axis=0)
+    max_values = np.max(data, axis=0)
+    return min_values, max_values
+
+
+def generate_search_grid(x_min: np.ndarray, x_max: np.ndarray, n_points: int = 5, col_names: list = None) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Generates a search grid based on the minimum and maximum values of each feature.
+
+    Args:
+        x_min (np.ndarray): A NumPy array containing the minimum values for each feature.
+        x_max (np.ndarray): A NumPy array containing the maximum values for each feature.
+        n_points (int, optional): The number of points to generate for each feature. Defaults to 5.
+        col_names (list, optional): A list of column names for the DataFrame. If None, a NumPy array is returned. Defaults to None.
+
+    Returns:
+        Union[pd.DataFrame, np.ndarray]: A Pandas DataFrame representing the search grid if col_names is provided,
+            otherwise a NumPy array.
+
+    Raises:
+        ValueError: If the length of x_min and x_max are different.
+
+    Examples:
+        >>> from spotpython.design.utils import generate_search_grid
+        >>> import numpy as np
+        >>> x_min = np.array([0, 0, 0])
+        >>> x_max = np.array([1, 1, 1])
+        >>> search_grid = generate_search_grid(x_min, x_max, num_points=3)
+        >>> print(search_grid)
+        [[0.  0.  0. ]
+         [0.  0.  0.5]
+         [0.  0.  1. ]
+         ...
+         [1.  1.  0.5]
+         [1.  1.  1. ]]
+
+        >>> search_grid = generate_search_grid(x_min, x_max, num_points=3, col_names=['feature_0', 'feature_1', 'feature_2'])
+        >>> print(search_grid)
+           feature_0  feature_1  feature_2
+        0        0.0      0.00      0.00
+        1        0.0      0.00      0.50
+        2        0.0      0.00      1.00
+        3        0.0      0.50      0.00
+        4        0.0      0.50      0.50
+        ..       ...      ...      ...
+        22       1.0      1.00      0.50
+        23       1.0      1.00      1.00
+
+        [27 rows x 3 columns]
+    """
+    if len(x_min) != len(x_max):
+        raise ValueError("x_min and x_max must have the same length.")
+
+    num_features = len(x_min)
+    # Create linspace for each dimension
+    ranges = [np.linspace(x_min[i], x_max[i], n_points) for i in range(num_features)]
+
+    # Use meshgrid to create all combinations
+    # The maximum number of inputs for np.broadcast is 32
+    if num_features > 30:
+        raise ValueError("Too many features for meshgrid. Maximum 30 features are supported.")
+    mesh = np.meshgrid(*ranges, indexing="ij")
+
+    # Reshape the meshgrid output to a list of points
+    points = np.array([m.ravel() for m in mesh]).T
+
+    if col_names:
+        # Create a Pandas DataFrame from the points
+        if len(col_names) != num_features:
+            raise ValueError("The number of column names must match the number of features.")
+        search_grid = pd.DataFrame(points, columns=col_names)
+        return search_grid
+    else:
+        return points
+
+
+def map_to_original_scale(X_search: Union[pd.DataFrame, np.ndarray], x_min: np.ndarray, x_max: np.ndarray) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Maps the values in X_search from the range [0, 1] to the original scale defined by x_min and x_max.
+
+    Args:
+        X_search (Union[pd.DataFrame, np.ndarray]): A Pandas DataFrame or NumPy array containing the search points in the range [0, 1].
+        x_min (np.ndarray): A NumPy array containing the minimum values for each feature in the original scale.
+        x_max (np.ndarray): A NumPy array containing the maximum values for each feature in the original scale.
+
+    Returns:
+        Union[pd.DataFrame, np.ndarray]: A Pandas DataFrame or NumPy array with the values mapped to the original scale.
+
+    Examples:
+        >>> from spotpython.design.utils import map_to_original_scale
+        >>> import numpy as np
+        >>> import pandas as pd
+        >>> X_search = pd.DataFrame([[0.5, 0.5], [0.25, 0.75]], columns=['x', 'y'])
+        >>> x_min = np.array([0, 0])
+        >>> x_max = np.array([10, 20])
+        >>> X_search_scaled = map_to_original_scale(X_search, x_min, x_max)
+        >>> print(X_search_scaled)
+              x     y
+        0   5.0  10.0
+        1   2.5  15.0
+    """
+    if not isinstance(X_search, (pd.DataFrame, np.ndarray)):
+        raise TypeError("X_search must be a Pandas DataFrame or a NumPy array.")
+
+    if len(x_min) != X_search.shape[1]:
+        raise IndexError(f"x_min and X_search must have the same number of columns. x_min has {len(x_min)} columns and X_search has {X_search.shape[1]} columns.")
+    if len(x_max) != X_search.shape[1]:
+        raise IndexError(f"x_max and X_search must have the same number of columns. x_max has {len(x_max)} columns and X_search has {X_search.shape[1]} columns.")
+
+    if isinstance(X_search, pd.DataFrame):
+        X_search_scaled = X_search.copy()  # Create a copy to avoid modifying the original DataFrame
+        for i, col in enumerate(X_search.columns):
+            X_search_scaled.loc[:, col] = X_search[col] * (x_max[i] - x_min[i]) + x_min[i]
+        return X_search_scaled
+    elif isinstance(X_search, np.ndarray):
+        X_search_scaled = X_search.copy()  # Create a copy to avoid modifying the original array
+        for i in range(X_search.shape[1]):
+            X_search_scaled[:, i] = X_search[:, i] * (x_max[i] - x_min[i]) + x_min[i]
+        return X_search_scaled

src/spotpython/utils/desirability.py

@@ -7,9 +7,6 @@ class DesirabilityBase:
 
     Provides a method to print class attributes and extend the range of values.
 
-    Attributes:
-        None
-
     Methods:
         print_class_attributes(indent=0):
             Prints the attributes of the class object in a generic and recursive manner.
@@ -382,21 +379,22 @@ def __init__(self, *d_objs):
         Combines multiple desirability objects into an overall desirability function.
 
         Args:
-            *d_objs: Instances of desirability classes (e.g., DMax, DTarget, etc.).
+            *d_objs (obj):
+                Instances of desirability classes (e.g., DMax, DTarget, etc.).
         """
         valid_classes = (DMax, DMin, DTarget, DArb, DBox, DCategorical)
         # print the instanaces of desirability classes
-        print(f"d_objs: {d_objs}")
-        for obj in d_objs:
-            print(f"obj: {obj}")
-            print(f"isinstance(obj, valid_classes): {isinstance(obj, valid_classes)}")
+        # print(f"d_objs: {d_objs}")
+        # for obj in d_objs:
+        #     print(f"obj: {obj}")
+        #     print(f"isinstance(obj, valid_classes): {isinstance(obj, valid_classes)}")
 
         if not all(isinstance(obj, valid_classes) for obj in d_objs):
             raise ValueError("All objects must be instances of valid desirability classes.")
 
         self.d_objs = d_objs  # Store the desirability objects
 
-    def predict(self, newdata, all=False):
+    def predict(self, newdata, all=False) -> float:
         """
         Predicts the overall desirability based on the individual desirability objects.
 
@@ -405,7 +403,8 @@ def predict(self, newdata, all=False):
             all (bool): Whether to return individual desirabilities along with the overall desirability.
 
         Returns:
-            float or tuple: The overall desirability score, or a tuple of individual and overall desirabilities if `all=True`.
+            float or tuple:
+                The overall desirability score, or a tuple of individual and overall desirabilities if `all=True`.
         """
 
         # # Compute individual desirabilities
@@ -501,7 +500,7 @@ def print_dOverall(self, digits=3, print_call=True):
             DesirabilityPrinter.print_dBox(d_obj, digits=digits, print_call=False)
 
 
-def conversion_pred(x):
+def conversion_pred(x) -> float:
     """
     Predicts the percent conversion based on the input vector x.
 
@@ -514,7 +513,7 @@ def conversion_pred(x):
     return 81.09 + 1.0284 * x[0] + 4.043 * x[1] + 6.2037 * x[2] - 1.8366 * x[0] ** 2 + 2.9382 * x[1] ** 2 - 5.1915 * x[2] ** 2 + 2.2150 * x[0] * x[1] + 11.375 * x[0] * x[2] - 3.875 * x[1] * x[2]
 
 
-def activity_pred(x):
+def activity_pred(x) -> float:
     """
     Predicts the thermal activity based on the input vector x.
 

test/test_design_utils.py

@@ -0,0 +1,86 @@
+import numpy as np
+import pandas as pd
+import pytest
+from spotpython.design.utils import get_boundaries, generate_search_grid
+
+
+def test_get_boundaries_with_positive_numbers():
+    data = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    min_values, max_values = get_boundaries(data)
+    assert np.array_equal(min_values, np.array([1, 2, 3]))
+    assert np.array_equal(max_values, np.array([7, 8, 9]))
+
+
+def test_get_boundaries_with_negative_numbers():
+    data = np.array([[-1, -2, -3], [-4, -5, -6], [-7, -8, -9]])
+    min_values, max_values = get_boundaries(data)
+    assert np.array_equal(min_values, np.array([-7, -8, -9]))
+    assert np.array_equal(max_values, np.array([-1, -2, -3]))
+
+
+def test_get_boundaries_with_mixed_numbers():
+    data = np.array([[1, -2, 3], [-4, 5, -6], [7, -8, 9]])
+    min_values, max_values = get_boundaries(data)
+    assert np.array_equal(min_values, np.array([-4, -8, -6]))
+    assert np.array_equal(max_values, np.array([7, 5, 9]))
+
+
+def test_get_boundaries_with_single_row():
+    data = np.array([[1, 2, 3]])
+    min_values, max_values = get_boundaries(data)
+    assert np.array_equal(min_values, np.array([1, 2, 3]))
+    assert np.array_equal(max_values, np.array([1, 2, 3]))
+
+
+def test_get_boundaries_with_single_column():
+    data = np.array([[1], [4], [7]])
+    min_values, max_values = get_boundaries(data)
+    assert np.array_equal(min_values, np.array([1]))
+    assert np.array_equal(max_values, np.array([7]))
+
+
+def test_get_boundaries_with_empty_array():
+    data = np.array([[]])
+    with pytest.raises(ValueError):
+        get_boundaries(data)
+
+
+def test_generate_search_grid_numpy():
+    x_min = np.array([0, 0])
+    x_max = np.array([1, 1])
+    grid = generate_search_grid(x_min, x_max, n_points=3)
+    assert isinstance(grid, np.ndarray)
+    assert grid.shape == (9, 2)
+
+
+def test_generate_search_grid_pandas():
+    x_min = np.array([0, 0])
+    x_max = np.array([1, 1])
+    col_names = ["x", "y"]
+    grid = generate_search_grid(x_min, x_max, n_points=3, col_names=col_names)
+    assert isinstance(grid, pd.DataFrame)
+    assert grid.shape == (9, 2)
+    assert list(grid.columns) == col_names
+
+
+def test_generate_search_grid_different_n_points():
+    x_min = np.array([0, 0])
+    x_max = np.array([1, 1])
+    grid = generate_search_grid(x_min, x_max, n_points=5)
+    assert grid.shape == (25, 2)
+
+
+def test_generate_search_grid_different_ranges():
+    x_min = np.array([1, 2])
+    x_max = np.array([4, 5])
+    grid = generate_search_grid(x_min, x_max, n_points=3)
+    assert np.allclose(grid[0], np.array([1.0, 2.0]))
+    assert np.allclose(grid[-1], np.array([4.0, 5.0]))
+
+
+def test_generate_search_grid_col_names_mismatch():
+    x_min = np.array([0, 0])
+    x_max = np.array([1, 1])
+    col_names = ["x"]
+    with pytest.raises(ValueError):
+        generate_search_grid(x_min, x_max, col_names=col_names)

test/test_utils_mapt_to_original_scale.py

@@ -0,0 +1,40 @@
+import pytest
+import numpy as np
+import pandas as pd
+from spotpython.design.utils import map_to_original_scale
+
+def test_map_to_original_scale_with_dataframe():
+    X_search = pd.DataFrame([[0.5, 0.5], [0.25, 0.75]], columns=['x', 'y'])
+    x_min = np.array([0, 0])
+    x_max = np.array([10, 20])
+    expected = pd.DataFrame([[5.0, 10.0], [2.5, 15.0]], columns=['x', 'y'])
+
+    result = map_to_original_scale(X_search, x_min, x_max)
+
+    pd.testing.assert_frame_equal(result, expected)
+
+def test_map_to_original_scale_with_numpy_array():
+    X_search = np.array([[0.5, 0.5], [0.25, 0.75]])
+    x_min = np.array([0, 0])
+    x_max = np.array([10, 20])
+    expected = np.array([[5.0, 10.0], [2.5, 15.0]])
+
+    result = map_to_original_scale(X_search, x_min, x_max)
+
+    np.testing.assert_array_almost_equal(result, expected)
+
+def test_map_to_original_scale_invalid_input_type():
+    X_search = [[0.5, 0.5], [0.25, 0.75]]  # Not a DataFrame or NumPy array
+    x_min = np.array([0, 0])
+    x_max = np.array([10, 20])
+
+    with pytest.raises(TypeError, match="X_search must be a Pandas DataFrame or a NumPy array."):
+        map_to_original_scale(X_search, x_min, x_max)
+
+def test_map_to_original_scale_mismatched_dimensions():
+    X_search = np.array([[0.5, 0.5], [0.25, 0.75]])
+    x_min = np.array([0])
+    x_max = np.array([10])
+
+    with pytest.raises(IndexError, match="x_min and X_search must have the same number of columns."):
+        map_to_original_scale(X_search, x_min, x_max)