0.29.5

randorient fixed

Author: bartzbeielstein

notebooks/00_spotPython_tests.ipynb

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

pyproject.toml

@@ -6,30 +6,64 @@
 from sklearn.model_selection import train_test_split
 
 
-def randorient(k, p, xi):
+def randorient(k, p, xi, seed=None) -> np.ndarray:
+    """Generates a random orientation of a sampling matrix.
+    This function creates a random sampling matrix for a given number of
+    dimensions (k), number of levels (p), and step length (xi). The
+    resulting matrix is used for screening designs in the context of
+    experimental design.
+
+    Args:
+        k (int): Number of dimensions.
+        p (int): Number of levels.
+        xi (float): Step length.
+        seed (int, optional): Seed for the random number generator.
+            Defaults to None.
+
+    Returns:
+        np.ndarray: A random sampling matrix of shape (k+1, k).
+
+    Example:
+        >>> randorient(k=2, p=3, xi=0.5)
+        array([[0. , 0. ],
+               [0.5, 0.5],
+               [1. , 1. ]])
+    """
+    # Initialize random number generator with the provided seed
+    if seed is not None:
+        rng = np.random.default_rng(seed)
+    else:
+        rng = np.random.default_rng()
+
     # Step length
     Delta = xi / (p - 1)
 
     m = k + 1
 
     # A truncated p-level grid in one dimension
-    xs = np.arange(0, 1, Delta)
+    xs = np.arange(0, 1 - Delta, 1 / (p - 1))
     xsl = len(xs)
+    if xsl < 1:
+        print(f"xi = {xi}.")
+        print(f"p = {p}.")
+        print(f"Delta = {Delta}.")
+        print(f"p - 1 = {p - 1}.")
+        raise ValueError(f"The number of levels xsl is {xsl}, but it must be greater than 0.")
 
     # Basic sampling matrix
     B = np.vstack((np.zeros((1, k)), np.tril(np.ones((k, k)))))
 
     # Randomization
 
     # Matrix with +1s and -1s on the diagonal with equal probability
-    Dstar = np.diag(2 * np.round(np.random.rand(k)) - 1)
+    Dstar = np.diag(2 * rng.integers(0, 2, size=k) - 1)
 
     # Random base value
-    xstar = xs[(np.random.rand(k) * xsl).astype(int)]
+    xstar = xs[rng.integers(0, xsl, size=k)]
 
     # Permutation matrix
     Pstar = np.zeros((k, k))
-    rp = np.random.permutation(k)
+    rp = rng.permutation(k)
     for i in range(k):
         Pstar[i, rp[i]] = 1
 
@@ -52,12 +86,8 @@ def screeningplan(k, p, xi, r):
     return X
 
 
-def screening(X, fun, xi, p, labels, bounds=None, print=False) -> pd.DataFrame:
-    """Generates a DataFrame with elementary effect screening metrics.
-
-    This function calculates the mean and standard deviation of the
-    elementary effects for a given set of design variables and returns
-    the results as a Pandas DataFrame.
+def _screening(X, fun, xi, p, labels, bounds=None) -> tuple:
+    """Helper function to calculate elementary effects for a screening design.
 
     Args:
         X (np.ndarray): The screening plan matrix, typically structured
@@ -73,13 +103,10 @@ def screening(X, fun, xi, p, labels, bounds=None, print=False) -> pd.DataFrame:
             each variable.
 
     Returns:
-        pd.DataFrame: A DataFrame containing three columns:
-            - 'varname': The name of each variable.
-            - 'mean': The mean of the elementary effects for each variable.
-            - 'sd': The standard deviation of the elementary effects for
+        tuple: A tuple containing two arrays:
+            - sm: The mean of the elementary effects for each variable.
+            - ssd: The standard deviation of the elementary effects for
             each variable.
-        or None: If print is set to False, a plot of the results is
-            generated instead of returning a DataFrame.
 
     Examples:
         >>> import numpy as np
@@ -131,23 +158,148 @@ def screening(X, fun, xi, p, labels, bounds=None, print=False) -> pd.DataFrame:
     # Statistical measures (divide by n)
     ssd = np.std(F, axis=1, ddof=0)
     sm = np.mean(F, axis=1)
+    return sm, ssd
 
-    if print:
-        idx = np.argsort(-np.abs(sm))
-        sorted_labels = [labels[i] for i in idx]
-        sm = sm[idx]
-        ssd = ssd[idx]
-        df = pd.DataFrame({"varname": sorted_labels, "mean": sm, "sd": ssd})
-        return df
-    else:
-        plt.figure()
-        for i in range(k):
-            plt.text(sm[i], ssd[i], labels[i], fontsize=10)
-        plt.axis([min(sm), 1.1 * max(sm), min(ssd), 1.1 * max(ssd)])
-        plt.xlabel("Sample means")
-        plt.ylabel("Sample standard deviations")
-        plt.gca().tick_params(labelsize=10)
-        plt.grid(True)
+
+def screening_print(X, fun, xi, p, labels, bounds=None) -> pd.DataFrame:
+    """Generates a DataFrame with elementary effect screening metrics.
+
+    This function calculates the mean and standard deviation of the
+    elementary effects for a given set of design variables and returns
+    the results as a Pandas DataFrame.
+
+    Args:
+        X (np.ndarray): The screening plan matrix, typically structured
+            within a [0,1]^k box.
+        fun (object): The objective function to evaluate at each
+            design point in the screening plan.
+        xi (float): The elementary effect step length factor.
+        p (int): Number of discrete levels along each dimension.
+        labels (list of str): A list of variable names corresponding to
+            the design variables.
+        bounds (np.ndarray): A 2xk matrix where the first row contains
+            lower bounds and the second row contains upper bounds for
+            each variable.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing three columns:
+            - 'varname': The name of each variable.
+            - 'mean': The mean of the elementary effects for each variable.
+            - 'sd': The standard deviation of the elementary effects for
+            each variable.
+        or None: If print is set to False, a plot of the results is
+            generated instead of returning a DataFrame.
+
+    Examples:
+        >>> import numpy as np
+            from spotpython.utils.effects import screening, screeningplan
+            from spotpython.fun.objectivefunctions import Analytical
+            fun = Analytical()
+            k = 10
+            p = 10
+            xi = 1
+            r = 25
+            X = screeningplan(k=k, p=p, xi=xi, r=r)  # shape (r x (k+1), k)
+            # Provide real-world bounds from the wing weight docs (2 x 10).
+            value_range = np.array([
+                [150, 220,   6, -10, 16, 0.5, 0.08, 2.5, 1700, 0.025],
+                [200, 300,  10,  10, 45, 1.0, 0.18, 6.0, 2500, 0.08 ],
+            ])
+            labels = [
+                "S_W", "W_fw", "A", "Lambda",
+                "q",   "lambda", "tc", "N_z",
+                "W_dg", "W_p"
+            ]
+            screening(
+                X=X,
+                fun=fun.fun_wingwt,
+                bounds=value_range,
+                xi=xi,
+                p=p,
+                labels=labels,
+                print=False,
+            )
+    """
+    sm, ssd = _screening(X=X, fun=fun, xi=xi, p=p, labels=labels, bounds=bounds)
+    idx = np.argsort(-np.abs(sm))
+    sorted_labels = [labels[i] for i in idx]
+    sm = sm[idx]
+    ssd = ssd[idx]
+    df = pd.DataFrame({"varname": sorted_labels, "mean": sm, "sd": ssd})
+    return df
+
+
+def screening_plot(X, fun, xi, p, labels, bounds=None, show=True):
+    """Generates a plot with elementary effect screening metrics.
+
+    This function calculates the mean and standard deviation of the
+    elementary effects for a given set of design variables and plots
+    the results.
+
+    Args:
+        X (np.ndarray): The screening plan matrix, typically structured
+            within a [0,1]^k box.
+        fun (object): The objective function to evaluate at each
+            design point in the screening plan.
+        xi (float): The elementary effect step length factor.
+        p (int): Number of discrete levels along each dimension.
+        labels (list of str): A list of variable names corresponding to
+            the design variables.
+        bounds (np.ndarray): A 2xk matrix where the first row contains
+            lower bounds and the second row contains upper bounds for
+            each variable.
+        show: (bool): If True, the plot is displayed. Defaults to True.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing three columns:
+            - 'varname': The name of each variable.
+            - 'mean': The mean of the elementary effects for each variable.
+            - 'sd': The standard deviation of the elementary effects for
+            each variable.
+        or None: If print is set to False, a plot of the results is
+            generated instead of returning a DataFrame.
+
+    Examples:
+        >>> import numpy as np
+            from spotpython.utils.effects import screening, screeningplan
+            from spotpython.fun.objectivefunctions import Analytical
+            fun = Analytical()
+            k = 10
+            p = 10
+            xi = 1
+            r = 25
+            X = screeningplan(k=k, p=p, xi=xi, r=r)  # shape (r x (k+1), k)
+            # Provide real-world bounds from the wing weight docs (2 x 10).
+            value_range = np.array([
+                [150, 220,   6, -10, 16, 0.5, 0.08, 2.5, 1700, 0.025],
+                [200, 300,  10,  10, 45, 1.0, 0.18, 6.0, 2500, 0.08 ],
+            ])
+            labels = [
+                "S_W", "W_fw", "A", "Lambda",
+                "q",   "lambda", "tc", "N_z",
+                "W_dg", "W_p"
+            ]
+            screening(
+                X=X,
+                fun=fun.fun_wingwt,
+                bounds=value_range,
+                xi=xi,
+                p=p,
+                labels=labels,
+                print=False,
+            )
+    """
+    k = X.shape[1]
+    sm, ssd = _screening(X=X, fun=fun, xi=xi, p=p, labels=labels, bounds=bounds)
+    plt.figure()
+    for i in range(k):
+        plt.text(sm[i], ssd[i], labels[i], fontsize=10)
+    plt.axis([min(sm), 1.1 * max(sm), min(ssd), 1.1 * max(ssd)])
+    plt.xlabel("Sample means")
+    plt.ylabel("Sample standard deviations")
+    plt.gca().tick_params(labelsize=10)
+    plt.grid(True)
+    if show:
         plt.show()