diff --git a/bask/acquisition.py b/bask/acquisition.py index d993acc..f2f7fa4 100644 --- a/bask/acquisition.py +++ b/bask/acquisition.py @@ -132,6 +132,15 @@ def _ei_f(x): class ExpectedImprovement(UncertaintyAcquisition): + """Select the point maximizing the expected improvement over the current + optimum. + + Parameters + ---------- + y_opt : float, default=None + The value of the current optimum. If it is None, it will use the + minimum y value of the evaluated points. + """ def __call__(self, mu, std, *args, y_opt=None, **kwargs): if y_opt is None: y_opt = mu.min() @@ -143,6 +152,15 @@ def __call__(self, mu, std, *args, y_opt=None, **kwargs): class TopTwoEI(ExpectedImprovement): + """Select the point with the highest expected improvement over the + point with the maximum expected improvement overall. + + Parameters + ---------- + y_opt : float, default=None + The value of the current optimum. If it is None, it will use the + minimum y value of the evaluated points. + """ def __call__(self, mu, std, *args, y_opt=None, **kwargs): ei = super().__call__(mu, std, *args, y_opt=y_opt, **kwargs) values = np.zeros_like(mu) @@ -155,18 +173,39 @@ def __call__(self, mu, std, *args, y_opt=None, **kwargs): class Expectation(UncertaintyAcquisition): + """Select the point with the lowest estimated mean.""" def __call__(self, mu, std, *args, **kwargs): return -mu class LCB(UncertaintyAcquisition): - def __call__(self, mu, std, *args, alpha=1.86, **kwargs): + """Select the point with the lowest lower confidence bound. + + Parameters + ---------- + alpha : positive float, alpha=1.96 + Number of standard errors to substract from the mean estimate. + """ + def __call__(self, mu, std, *args, alpha=1.96, **kwargs): if alpha == "inf": return std return alpha * std - mu class MaxValueSearch(UncertaintyAcquisition): + """Select points based on their mutual information with the optimum value. + + Parameters + ---------- + n_min_samples : int, default=1000 + Number of samples for the optimum distribution + + References + ---------- + [1] Wang, Z. & Jegelka, S.. (2017). Max-value Entropy Search for Efficient + Bayesian Optimization. Proceedings of the 34th International Conference + on Machine Learning, in PMLR 70:3627-3635 + """ def __call__(self, mu, std, *args, n_min_samples=1000, **kwargs): def probf(x): return np.exp(np.sum(st.norm.logcdf(-(x - mu) / std), axis=0)) @@ -201,12 +240,18 @@ def probf(x): class ThompsonSampling(SampleAcquisition): + """Sample a random function from the GP and select its optimum.""" def __call__(self, gp_sample, *args, **kwargs): return -gp_sample class VarianceReduction(FullGPAcquisition): - """ A criterion which tries to find the region where it can reduce the variance the most.""" + """A criterion which tries to find the region where it can reduce the + global variance the most. + + This criterion is suitable for active learning, where the goal is to + uniformly estimate the target function and not only its optimum. + """ def __call__(self, X, gp, *args, **kwargs): n = len(X)