docs: remove vignette, point to book, update README (#158)

* docs: remove vignette, point to book, update README
* fix: drop timestamp and batch_nr from candidate points

Author: sumny

DESCRIPTION

@@ -55,14 +55,12 @@ Suggests:
     DiceKriging,
     emoa,
     fastGHQuad,
-    knitr,
     lhs,
     mlr3learners (>= 0.5.4),
     mlr3pipelines (>= 0.4.2),
     nloptr,
     ranger,
     rgenoud,
-    rmarkdown,
     rpart,
     stringi,
     testthat (>= 3.0.0)
@@ -111,4 +109,3 @@ Collate:
     'mbo_defaults.R'
     'sugar.R'
     'zzz.R'
-VignetteBuilder: knitr

R/AcqOptimizer.R

@@ -214,7 +214,7 @@ AcqOptimizer = R6Class("AcqOptimizer",
       #  }
       #  setcolorder(xdt, c(instance$archive$cols_x, "x_domain", instance$objective$id))
       #}
-      xdt
+      xdt[, -c("timestamp", "batch_nr")]  # drop timestamp and batch_nr information from the candidates
     }
   ),
 

README.Rmd

@@ -22,7 +22,7 @@ A new R6 and much more modular implementation for single- and multi-objective Ba
 
 ## Get Started
 
-An overview and gentle introduction is given in [this vignette](https://mlr3mbo.mlr-org.com/dev/articles/mlr3mbo.html).
+The best entry point to get familiar with `mlr3mbo` is provided via the [Bayesian Optimization](https://mlr3book.mlr-org.com/chapters/chapter5/advanced_tuning_methods_and_black_box_optimization.html#sec-bayesian-optimization) chapter in the `mlr3book`.
 
 ## Design
 
@@ -32,7 +32,7 @@ An overview and gentle introduction is given in [this vignette](https://mlr3mbo.
 * `AcqFunction`: Acquisition Function
 * `AcqOptimizer`: Acquisition Function Optimizer
 
-Based on these, Bayesian Optimization loops can be written, see, e.g., `bayesopt_ego` for sequential single-objective BO.
+Based on these, Bayesian Optimization (BO) loops can be written, see, e.g., `bayesopt_ego` for sequential single-objective BO.
 
 `mlr3mbo` also provides an `OptimizerMbo` class behaving like any other `Optimizer` from the [bbotk](https://cran.r-project.org/package=bbotk) package as well as
 a `TunerMbo` class behaving like any other `Tuner` from the [mlr3tuning](https://cran.r-project.org/package=mlr3tuning) package.
@@ -42,66 +42,75 @@ See `?mbo_defaults` for more details.
 
 ## Simple Optimization Example
 
-Minimize `f(x) = x^2` via sequential single-objective BO using a GP as surrogate and EI optimized via random search as acquisition function:
+Minimize the two-dimensional Branin function via sequential BO using a GP as surrogate and EI as acquisition function optimized via a local serch:
 
 ```{r, message = FALSE}
 library(bbotk)
 library(mlr3mbo)
 library(mlr3learners)
 set.seed(1)
 
-obfun = ObjectiveRFun$new(
-  fun = function(xs) list(y1 = xs$x ^ 2),
-  domain = ps(x = p_dbl(lower = -10, upper = 10)),
-  codomain = ps(y1 = p_dbl(tags = "minimize")))
+fun = function(xdt) {
+  y = branin(xdt[["x1"]], xdt[["x2"]])
+  data.table(y = y)
+}
+
+domain = ps(
+  x1 = p_dbl(-5, 10),
+  x2 = p_dbl(0, 15)
+)
+
+codomain = ps(
+  y = p_dbl(tags = "minimize")
+)
+
+objective = ObjectiveRFunDt$new(
+  fun = fun,
+  domain = domain,
+  codomain = codomain
+)
 
 instance = oi(
-  objective = obfun,
-  terminator = trm("evals", n_evals = 10))
+  objective = objective,
+  terminator = trm("evals", n_evals = 25)
+)
 
 surrogate = srlrn(lrn("regr.km", control = list(trace = FALSE)))
-acqfun = acqf("ei")
-acqopt = acqo(opt("random_search", batch_size = 100),
-  terminator = trm("evals", n_evals = 100))
+
+acq_function = acqf("ei")
+
+acq_optimizer = acqo(
+  opt("local_search", n_initial_points = 10, initial_random_sample_size = 1000, neighbors_per_point = 10),
+  terminator = trm("evals", n_evals = 3000)
+)
 
 optimizer = opt("mbo",
   loop_function = bayesopt_ego,
   surrogate = surrogate,
-  acq_function = acqfun,
-  acq_optimizer = acqopt)
+  acq_function = acq_function,
+  acq_optimizer = acq_optimizer
+)
 
 optimizer$optimize(instance)
 ```
 
-Note that you can also use `bb_optimize` as a shorthand:
+We can quickly visualize the contours of the objective function (on log scale) as well as the sampling behavior of our BO run (lighter blue colours indicating points that were evaluated in later stages of the optimization process; the first batch is given by the initial design).
 
-```{r, message = FALSE}
-library(bbotk)
-library(mlr3mbo)
-library(mlr3learners)
-set.seed(1)
-
-fun = function(xs) list(y1 = xs$x ^ 2)
-
-surrogate = srlrn(lrn("regr.km", control = list(trace = FALSE)))
-acqfun = acqf("ei")
-acqopt = acqo(opt("random_search", batch_size = 100),
-  terminator = trm("evals", n_evals = 100))
+```{r, eval = FALSE}
+library(ggplot2)
+grid = generate_design_grid(instance$search_space, resolution = 1000L)$data
+grid[, y := branin(x1 = x1, x2 = x2)]
 
-optimizer = opt("mbo",
-  loop_function = bayesopt_ego,
-  surrogate = surrogate,
-  acq_function = acqfun,
-  acq_optimizer = acqopt)
-
-result = bb_optimize(
-  fun,
-  method = optimizer,
-  lower = c(x = -10),
-  upper = c(x = 10),
-  max_evals = 10)
+ggplot(aes(x = x1, y = x2, z = log(y)), data = grid) +
+  geom_contour(colour = "black") +
+  geom_point(aes(x = x1, y = x2, colour = batch_nr), data = instance$archive$data) +
+  labs(x =  expression(x[1]), y = expression(x[2])) +
+  theme_minimal() +
+  theme(legend.position = "bottom")
 ```
 
+Note that you can also use `bb_optimize` as a shorthand instead of constructing an optimization instance.
+
 ## Simple Tuning Example
 
 ```{r, message = FALSE}

README.md

@@ -17,20 +17,22 @@ multi-objective Bayesian Optimization.
 
 ## Get Started
 
-An overview and gentle introduction is given in [this
-vignette](https://mlr3mbo.mlr-org.com/dev/articles/mlr3mbo.html).
+The best entry point to get familiar with `mlr3mbo` is provided via the
+[Bayesian
+Optimization](https://mlr3book.mlr-org.com/chapters/chapter5/advanced_tuning_methods_and_black_box_optimization.html#sec-bayesian-optimization)
+chapter in the `mlr3book`.
 
 ## Design
 
 `mlr3mbo` is built modular relying on the following
 [R6](https://cran.r-project.org/package=R6) classes:
 
--   `Surrogate`: Surrogate Model
--   `AcqFunction`: Acquisition Function
--   `AcqOptimizer`: Acquisition Function Optimizer
+- `Surrogate`: Surrogate Model
+- `AcqFunction`: Acquisition Function
+- `AcqOptimizer`: Acquisition Function Optimizer
 
-Based on these, Bayesian Optimization loops can be written, see, e.g.,
-`bayesopt_ego` for sequential single-objective BO.
+Based on these, Bayesian Optimization (BO) loops can be written, see,
+e.g., `bayesopt_ego` for sequential single-objective BO.
 
 `mlr3mbo` also provides an `OptimizerMbo` class behaving like any other
 `Optimizer` from the [bbotk](https://cran.r-project.org/package=bbotk)
@@ -44,71 +46,85 @@ more details.
 
 ## Simple Optimization Example
 
-Minimize `f(x) = x^2` via sequential single-objective BO using a GP as
-surrogate and EI optimized via random search as acquisition function:
+Minimize the two-dimensional Branin function via sequential BO using a
+GP as surrogate and EI as acquisition function optimized via a local
+serch:
 
 ``` r
 library(bbotk)
 library(mlr3mbo)
 library(mlr3learners)
 set.seed(1)
 
-obfun = ObjectiveRFun$new(
-  fun = function(xs) list(y1 = xs$x ^ 2),
-  domain = ps(x = p_dbl(lower = -10, upper = 10)),
-  codomain = ps(y1 = p_dbl(tags = "minimize")))
+fun = function(xdt) {
+  y = branin(xdt[["x1"]], xdt[["x2"]])
+  data.table(y = y)
+}
+
+domain = ps(
+  x1 = p_dbl(-5, 10),
+  x2 = p_dbl(0, 15)
+)
+
+codomain = ps(
+  y = p_dbl(tags = "minimize")
+)
+
+objective = ObjectiveRFunDt$new(
+  fun = fun,
+  domain = domain,
+  codomain = codomain
+)
 
 instance = oi(
-  objective = obfun,
-  terminator = trm("evals", n_evals = 10))
+  objective = objective,
+  terminator = trm("evals", n_evals = 25)
+)
 
 surrogate = srlrn(lrn("regr.km", control = list(trace = FALSE)))
-acqfun = acqf("ei")
-acqopt = acqo(opt("random_search", batch_size = 100),
-  terminator = trm("evals", n_evals = 100))
+
+acq_function = acqf("ei")
+
+acq_optimizer = acqo(
+  opt("local_search", n_initial_points = 10, initial_random_sample_size = 1000, neighbors_per_point = 10),
+  terminator = trm("evals", n_evals = 3000)
+)
 
 optimizer = opt("mbo",
   loop_function = bayesopt_ego,
   surrogate = surrogate,
-  acq_function = acqfun,
-  acq_optimizer = acqopt)
+  acq_function = acq_function,
+  acq_optimizer = acq_optimizer
+)
 
 optimizer$optimize(instance)
 ```
 
-    ##             x  x_domain          y1
-    ##         <num>    <list>       <num>
-    ## 1: 0.03897209 <list[1]> 0.001518824
+    ##          x1       x2  x_domain         y
+    ##       <num>    <num>    <list>     <num>
+    ## 1: 3.090821 2.299709 <list[2]> 0.4104925
 
-Note that you can also use `bb_optimize` as a shorthand:
+We can quickly visualize the contours of the objective function (on log
+scale) as well as the sampling behavior of our BO run (lighter blue
+colours indicating points that were evaluated in later stages of the
+optimization process; the first batch is given by the initial design).
 
 ``` r
-library(bbotk)
-library(mlr3mbo)
-library(mlr3learners)
-set.seed(1)
-
-fun = function(xs) list(y1 = xs$x ^ 2)
-
-surrogate = srlrn(lrn("regr.km", control = list(trace = FALSE)))
-acqfun = acqf("ei")
-acqopt = acqo(opt("random_search", batch_size = 100),
-  terminator = trm("evals", n_evals = 100))
-
-optimizer = opt("mbo",
-  loop_function = bayesopt_ego,
-  surrogate = surrogate,
-  acq_function = acqfun,
-  acq_optimizer = acqopt)
-
-result = bb_optimize(
-  fun,
-  method = optimizer,
-  lower = c(x = -10),
-  upper = c(x = 10),
-  max_evals = 10)
+library(ggplot2)
+grid = generate_design_grid(instance$search_space, resolution = 1000L)$data
+grid[, y := branin(x1 = x1, x2 = x2)]
+
+ggplot(aes(x = x1, y = x2, z = log(y)), data = grid) +
+  geom_contour(colour = "black") +
+  geom_point(aes(x = x1, y = x2, colour = batch_nr), data = instance$archive$data) +
+  labs(x =  expression(x[1]), y = expression(x[2])) +
+  theme_minimal() +
+  theme(legend.position = "bottom")
 ```
 
+Note that you can also use `bb_optimize` as a shorthand instead of
+constructing an optimization instance.
+
 ## Simple Tuning Example
 
 ``` r
@@ -135,4 +151,4 @@ instance$result
 
     ##           cp learner_param_vals  x_domain classif.ce
     ##        <num>             <list>    <list>      <num>
-    ## 1: -4.381681          <list[2]> <list[1]>  0.2070312
+    ## 1: -6.188733          <list[2]> <list[1]>  0.2382812