0.26.16

gp_sep documentation cleanup type info
sampling a la Forrester/Sobester

Author: bartzbeielstein

notebooks/00_spotPython_tests.ipynb

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

pyproject.toml

@@ -17,7 +17,7 @@
 from sklearn.base import BaseEstimator, RegressorMixin
 
 
-def crude_reset(theta, tmin, tmax, m):
+def crude_reset(theta, tmin, tmax, m) -> dict:
     """
     Check whether any elements of the parameter vector ``theta`` lie below the
     corresponding elements of the lower bound ``tmin``. If so, reset ``theta``
@@ -31,12 +31,12 @@ def crude_reset(theta, tmin, tmax, m):
         m (int): The dimensionality or number of parameters (used to adjust negative ``tmax`` entries).
 
     Returns:
-        dict or None: A dictionary containing:
+        (dict) or None: A dictionary containing:
             - "theta" (np.ndarray): The reset parameter values.
             - "its" (int): Number of iterations (0, indicating immediate reset).
             - "msg" (str): Reason for the reset.
             - "conv" (int): Reset code (102).
-        Returns None if no reset is needed.
+            Returns None if no reset is needed.
     """
     if np.any(theta < tmin):
         print("resetting due to init on lower boundary")
@@ -201,7 +201,7 @@ def garg(g, y: np.ndarray = None) -> dict:
     and priors for the nugget parameter.
 
     Args:
-        g: Could be a dictionary, numeric, or None. If numeric, turn it into {"start": g}.
+        g (dict}: Could be a dictionary, numeric, or None. If numeric, turn it into {"start": g}.
         y (np.ndarray): The response vector.
 
     Returns:
@@ -393,13 +393,13 @@ def __init__(
         }
 
     # Add these two methods required by scikit-learn
-    def get_params(self, deep=True):
+    def get_params(self, deep=True) -> dict:
         """Get parameters for this estimator.
 
         This method is required for scikit-learn compatibility.
 
         Args:
-            deep: If True, will return the parameters for this estimator and
+            deep (bool): If True, will return the parameters for this estimator and
                 contained subobjects that are estimators. Defaults to True.
 
         Returns:
@@ -419,16 +419,16 @@ def get_params(self, deep=True):
             "seed": self.seed,
         }
 
-    def set_params(self, **parameters):
+    def set_params(self, **parameters: dict) -> "GPsep":
         """Set the parameters of this estimator.
 
         This method is required for scikit-learn compatibility.
 
         Args:
-            **parameters: Estimator parameters as keyword arguments.
+            **parameters (dict): Estimator parameters as keyword arguments.
 
         Returns:
-            self: Estimator instance.
+            self (GPsep): Estimator instance.
         """
         for parameter, value in parameters.items():
             setattr(self, parameter, value)
@@ -442,18 +442,24 @@ def fit(self, X: np.ndarray, y: np.ndarray, d=None, g=None, dK: bool = True, aut
         """Fit the GP model with training data and optionally auto-optimize hyperparameters.
 
         Args:
-            X: array-like of shape (n_samples, n_features)
-            y: array-like of shape (n_samples,)
-            d: The length-scale parameters. If None, will be determined
+            X (np.ndarray):
+                Array-like of shape (n_samples, n_features).
+            y (np.ndarray):
+                Array-like of shape (n_samples,).
+            d (Optional[Union[np.ndarray, float]]):
+                The length-scale parameters. If None, will be determined
                 automatically. Defaults to None.
-            g: The nugget parameter. If None, will be determined automatically.
-                Defaults to None.
-            dK: Flag to indicate whether to calculate derivatives.
+            g (Optional[float]):
+                The nugget parameter. If None, will be determined automatically. Defaults to None.
+            dK (bool):
+                Flag to indicate whether to calculate derivatives.
                 Defaults to True.
-            auto_optimize: Whether to automatically optimize hyperparameters
+            auto_optimize (Optional[bool]):
+                Whether to automatically optimize hyperparameters
                 using MLE. If None, uses the default value from the object.
                 Defaults to None.
-            verbosity: Verbosity level for optimization output. Defaults to 0.
+            verbosity (int):
+                Verbosity level for optimization output. Defaults to 0.
 
         Returns:
             GPsep: The fitted GPsep object.
@@ -685,22 +691,30 @@ def _build(self) -> None:
         #     #     raise RuntimeError("dK calculations have already been initialized.")
         #     self.DK = diff_covar_sep_symm(self.m, self.X, self.n, self.d, self.K)
 
-    def _check_is_fitted(self):
+    def _check_is_fitted(self) -> None:
+        """
+        Check if the GPsep instance is fitted.
+        """
         if not self._is_fitted:
             raise ValueError("This GPsep instance is not fitted yet. Call 'fit' with " "appropriate arguments before using 'predict'.")
 
     def predict(self, X: np.ndarray, lite: bool = False, nonug: bool = False, return_full=False, return_std=False) -> float:
         """Predict the Gaussian Process output at new input points.
 
         Args:
-            X: The predictive locations.
-            lite: Flag to indicate whether to compute only the diagonal
+            X (np.ndarray):
+                The predictive locations.
+            lite (bool):
+                Flag to indicate whether to compute only the diagonal
                 of Sigma. Defaults to False.
-            nonug: Flag to indicate whether to exclude nugget.
+            nonug (bool):
+                Flag to indicate whether to exclude nugget.
                 Defaults to False.
-            return_full: Flag to indicate whether to return the full dictionary,
+            return_full (bool):
+                Flag to indicate whether to return the full dictionary,
                 which includes the mean, Sigma, df, and llik. Defaults to False.
-            return_std: Flag to indicate whether to return the standard deviation.
+            return_std (bool):
+                Flag to indicate whether to return the standard deviation.
                 Only applicable when return_full is False. Defaults to False.
 
         Returns:
@@ -710,34 +724,34 @@ def predict(self, X: np.ndarray, lite: bool = False, nonug: bool = False, return
             - Otherwise: Mean predictions
 
         Examples:
-                import numpy as np
-                from spotpython.gp.gp_sep import newGPsep
-                import matplotlib.pyplot as plt
-                # Simple sine data
-                X = np.linspace(0, 2 * np.pi, 7).reshape(-1, 1)
-                y = np.sin(X)
-                # New GP fit
-                gpsep = newGPsep(X, y, d=2, g=0.000001)
-                # Make predictions
-                XX = np.linspace(-1, 2 * np.pi + 1, 499).reshape(-1, 1)
-                p = gpsep.predict(XX, lite=False)
-                # Sample from the predictive distribution
-                N = 100
-                mean = p["mean"]
-                Sigma = p["Sigma"]
-                df = p["df"]
-                # Generate samples from the multivariate t-distribution
-                yy = np.random.multivariate_normal(mean, Sigma, N)
-                yy = yy.T
-                # Plot the results
-                plt.figure(figsize=(10, 6))
-                for i in range(N):
-                    plt.plot(XX, yy[:, i], color="gray", linewidth=0.5)
-                plt.scatter(X, y, color="black", s=50, zorder=5)
-                plt.xlabel("x")
-                plt.ylabel("f-hat(x)")
-                plt.title("Predictive Distribution")
-                plt.show()
+            import numpy as np
+            from spotpython.gp.gp_sep import newGPsep
+            import matplotlib.pyplot as plt
+            # Simple sine data
+            X = np.linspace(0, 2 * np.pi, 7).reshape(-1, 1)
+            y = np.sin(X)
+            # New GP fit
+            gpsep = newGPsep(X, y, d=2, g=0.000001)
+            # Make predictions
+            XX = np.linspace(-1, 2 * np.pi + 1, 499).reshape(-1, 1)
+            p = gpsep.predict(XX, lite=False)
+            # Sample from the predictive distribution
+            N = 100
+            mean = p["mean"]
+            Sigma = p["Sigma"]
+            df = p["df"]
+            # Generate samples from the multivariate t-distribution
+            yy = np.random.multivariate_normal(mean, Sigma, N)
+            yy = yy.T
+            # Plot the results
+            plt.figure(figsize=(10, 6))
+            for i in range(N):
+                plt.plot(XX, yy[:, i], color="gray", linewidth=0.5)
+            plt.scatter(X, y, color="black", s=50, zorder=5)
+            plt.xlabel("x")
+            plt.ylabel("f-hat(x)")
+            plt.title("Predictive Distribution")
+            plt.show()
         """
         self._check_is_fitted()
         # if X is a pandas dataframe, convert it to a numpy array

src/spotpython/gp/gp_sep.py

@@ -13,7 +13,7 @@ def simple_contour(
     max_z=None,
     n_samples=100,
     n_levels=30,
-):
+) -> None:
     """
     Simple contour plot
 
@@ -28,6 +28,9 @@ def simple_contour(
         n_samples (int, optional): _description_. Defaults to 100.
         n_levels (int, optional): _description_. Defaults to 5.
 
+    Returns:
+        None
+
     Examples:
         >>> import matplotlib.pyplot as plt
             import numpy as np
@@ -86,7 +89,7 @@ def plotModel(
     point_color_below="blue",
     point_color_above="red",
     atol=1e-6,
-):
+) -> None:
     """
     Generate 2D contour and 3D surface plots for a model's predictions.
 
@@ -379,39 +382,39 @@ def plotCombinations(
     point_color_below="blue",
     point_color_above="red",
     atol=1e-6,
-):
+) -> None:
     """Plot model surfaces for multiple combinations of input variables.
 
     This function generates contour and 3D surface plots for all specified
     combinations of input variables, avoiding redundancies and meaningless combinations.
 
     Args:
-        model: A fitted model with a predict method.
-        X: Array of training points (optional). If provided, used to derive bounds and dimension count.
-        lower: Array-like lower bounds for each dimension. If None, derived from X.
-        upper: Array-like upper bounds for each dimension. If None, derived from X.
-        x_vars: List of indices for x-axis variables. Defaults to all if None or empty.
-        y_vars: List of indices for y-axis variables. Defaults to all if None or empty.
-        min_z: Min value for color scale. If None, auto-calculated.
-        max_z: Max value for color scale. If None, auto-calculated.
-        var_type: List of variable types. If None, assumed numeric.
-        var_name: List of variable names. If None, named x0, x1, ...
-        show: Whether to display the plots. Defaults to True.
-        save_dir: Directory for saving plots. If None, not saved.
-        n_grid: Number of grid points along each axis. Defaults to 50.
-        contour_levels: Number of contour levels. Defaults to 10.
-        dpi: DPI for saving figures. Defaults to 200.
-        title_prefix: Prefix string for plot titles.
-        figsize: Figure size (width, height). Defaults to (12, 6).
-        use_min: Use lower bounds for non-plotted dimensions. Defaults to False.
-        use_max: Use upper bounds for non-plotted dimensions. Defaults to False.
-        margin: Fraction of range added as margin to bounds when derived from X. Defaults to 0.1.
-        aspect_equal: Whether to set equal aspect ratio. Defaults to False.
-        legend_fontsize: Font size for labels and legends. Defaults to 12.
+        model (object): A fitted model with a predict method.
+        X (Optional[np.ndarray]): Array of training points. If provided, used to derive bounds and dimension count.
+        lower (Optional[Union[np.ndarray, List[float]]]): Array-like lower bounds for each dimension. If None, derived from X.
+        upper (Optional[Union[np.ndarray, List[float]]]): Array-like upper bounds for each dimension. If None, derived from X.
+        x_vars (Optional[List[int]]): List of indices for x-axis variables. Defaults to all if None or empty.
+        y_vars (Optional[List[int]]): List of indices for y-axis variables. Defaults to all if None or empty.
+        min_z (Optional[float]): Min value for color scale. If None, auto-calculated.
+        max_z (Optional[float]): Max value for color scale. If None, auto-calculated.
+        var_type (Optional[List[str]]): List of variable types. If None, assumed numeric.
+        var_name (Optional[List[str]]): List of variable names. If None, named x0, x1, ...
+        show (bool): Whether to display the plots. Defaults to True.
+        save_dir (Optional[str]): Directory for saving plots. If None, not saved.
+        n_grid (int): Number of grid points along each axis. Defaults to 50.
+        contour_levels (int): Number of contour levels. Defaults to 10.
+        dpi (int): DPI for saving figures. Defaults to 200.
+        title_prefix (str): Prefix string for plot titles.
+        figsize (Tuple[float, float]): Figure size (width, height). Defaults to (12, 6).
+        use_min (bool): Use lower bounds for non-plotted dimensions. Defaults to False.
+        use_max (bool): Use upper bounds for non-plotted dimensions. Defaults to False.
+        margin (float): Fraction of range added as margin to bounds when derived from X. Defaults to 0.1.
+        aspect_equal (bool): Whether to set equal aspect ratio. Defaults to False.
+        legend_fontsize (int): Font size for labels and legends. Defaults to 12.
         cmap (str): Colormap for the plots. Defaults to "viridis".
-        X_points: Original data points to plot.
-        y_points: Original target values to plot.
-        plot_points (bool): Whether to plot X_points.
+        X_points (Optional[np.ndarray]): Original data points to plot.
+        y_points (Optional[np.ndarray]): Original target values to plot.
+        plot_points (bool): Whether to plot X_points. Defaults to True.
         points_color (str): Color for data points. Defaults to "white".
         points_size (int): Marker size for data points. Defaults to 30.
         point_color_below (str): Color if actual z < predicted z. Defaults to "lightgrey".

src/spotpython/plot/contour.py

@@ -59,7 +59,7 @@ def screening(X, fun, xi, p, labels, range=None, print=False) -> pd.DataFrame:
     Args:
         X (np.ndarray): The screening plan matrix, typically structured
             within a [0,1]^k box.
-        fun: The objective function to evaluate at each
+        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.

src/spotpython/utils/effects.py

@@ -2,7 +2,7 @@
 from scipy.optimize import minimize
 
 
-def run_minimize_with_restarts(objective, gradient, x0, bounds, n_restarts_optimizer=5, method="L-BFGS-B", maxit=100, verb=0, random_state=None):
+def run_minimize_with_restarts(objective, gradient, x0, bounds, n_restarts_optimizer=5, method="L-BFGS-B", maxit=100, verb=0, random_state=None) -> "minimize":
     """
     Runs multiple restarts of the minimize() function and returns the best found result.
 
@@ -18,7 +18,10 @@ def run_minimize_with_restarts(objective, gradient, x0, bounds, n_restarts_optim
         random_state (int, optional): Seed for the random-number generator to ensure reproducibility.
 
     Returns:
-        OptimizeResult: The best optimization result among all restarts.
+        OptimizeResult (object): The best optimization result among all restarts,
+        represented as a ``OptimizeResult`` object. Important attributes are:
+        ``x`` the solution array, ``success`` a Boolean flag indicating if the optimizer
+        exited successfully and ``message`` which describes the cause of the termination.
     """
     if random_state is not None:
         np.random.seed(random_state)