From 79cba5a0b0a5fc7d5f21e545c57fa37337b0faec Mon Sep 17 00:00:00 2001
From: Jakob Richter <code@jakob-r.de>
Date: Wed, 17 Feb 2016 16:21:08 +0100
Subject: [PATCH] add ego entry point (Issue #138)

---
 NAMESPACE     |  1 +
 R/mboEgo.R    | 47 +++++++++++++++++++++++++++++++++++++
 man/mboEgo.Rd | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 113 insertions(+)
 create mode 100644 R/mboEgo.R
 create mode 100644 man/mboEgo.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 93506182a..55f6934b1 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -26,6 +26,7 @@ export(makeMBOControl)
 export(makeMBOTrafoFunction)
 export(mbo)
 export(mboContinue)
+export(mboEgo)
 export(mboFinalize)
 export(plotEAF)
 export(plotExampleRun)
diff --git a/R/mboEgo.R b/R/mboEgo.R
new file mode 100644
index 000000000..5416563d4
--- /dev/null
+++ b/R/mboEgo.R
@@ -0,0 +1,47 @@
+#' @title Uses efficient global optimization to optimize a function.
+#'
+#' @description
+#' See \link{mbo_parallel} for all parallelization options.
+#'
+#' @inheritParams mbo
+#' @param init.design.points [\code{integer}]\cr
+#'   Number of points to generate for initial design via \code{\link[ParamHelpers]{generateDesign}}.
+#'   Only used if no design is given in \code{mbo} function.
+#'   If for any reason not enough points could be generated, the missing ones are generated randomly.
+#'   Default is 4 times the number of all parameters.
+#' @param iters [\code{integer}]\cr
+#'   Number of sequential optimization steps.
+#'   Default is 10.
+#'   If a \code{control} object is given, the termination criterion will be overwritten unless \code{iters} is set to \code{NULL}.
+#' @examples
+#' obj.fun = makeSingleObjectiveFunction(
+#'  fn = function(x) x[1]^2 + sin(x[2]), 
+#'  par.set = makeNumericParamSet(id = "x", lower = -1, upper = 1, len = 2))
+#' res = mboEgo(obj.fun)
+#' print(res)
+#' plot(res)
+#' @export
+mboEgo = function(fun, init.design.points = NULL, iters = 10L, design = NULL, learner = NULL, control = NULL, show.info = getOption("mlrMBO.show.info", TRUE), more.args = list()) {
+  
+  if (is.null(init.design.points)) {
+    init.design.points = sum(getParamLengths(par.set))
+  } else {
+    assertInt(init.design.points, lower = 1L)
+  }
+
+  if (is.null(control)) {
+    control = makeMBOControl()
+  }
+
+  if (!is.null(iters)) {
+    assertInt(iters, lower = 1L)  
+    control = setMBOControlTermination(iters = iters)
+  }
+
+  if (is.null(design)) {
+    design = generateDesign(n = init.design.points, getParamSet(obj.fun), fun = lhs::maximinLHS)
+  }
+
+  mbo(fun, design = design, learner = learner, control = control,
+  show.info = show.info, more.args = more.args)
+}
\ No newline at end of file
diff --git a/man/mboEgo.Rd b/man/mboEgo.Rd
new file mode 100644
index 000000000..8e7f27973
--- /dev/null
+++ b/man/mboEgo.Rd
@@ -0,0 +1,65 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/mboEgo.R
+\name{mboEgo}
+\alias{mboEgo}
+\title{Uses efficient global optimization to optimize a function.}
+\usage{
+mboEgo(fun, init.design.points = NULL, iters = 10L, design = NULL,
+  learner = NULL, control = NULL,
+  show.info = getOption("mlrMBO.show.info", TRUE), more.args = list())
+}
+\arguments{
+\item{fun}{[\code{function(x, ...)}]\cr
+Fitness function to minimize. The first argument has to be a list of values.
+The function has to return a single numerical value.
+In fact it is possible to return even more information which will be stored
+in the optimization path. To achieve this, simply append the attribute \dQuote{extras}
+to the return value of the target function. This has to be a named list of scalar values.
+Each of these values will be stored additionally in the optimization path.}
+
+\item{init.design.points}{[\code{integer}]\cr
+Number of points to generate for initial design via \code{\link[ParamHelpers]{generateDesign}}.
+Only used if no design is given in \code{mbo} function.
+If for any reason not enough points could be generated, the missing ones are generated randomly.
+Default is 4 times the number of all parameters.}
+
+\item{iters}{[\code{integer}]\cr
+Number of sequential optimization steps.
+Default is 10.
+If a \code{control} object is given, the termination criterion will be overwritten unless \code{iters} is set to \code{NULL}.}
+
+\item{design}{[\code{data.frame}]\cr
+Initial design as data frame. If the y-values are not already present in design,
+mbo will evaluate the points.
+If the parameters have corresponding trafo functions,
+the design must not be transformed before it is passed!
+Functions to generate designs are available in \code{ParamHelpers}: \code{\link[ParamHelpers]{generateDesign}}, \code{\link[ParamHelpers]{generateGridDesign}}, \code{\link[ParamHelpers]{generateRandomDesign}}.
+Default is \code{NULL}, which means \code{\link[ParamHelpers]{generateDesign}} is called and a design
+of size 4 times number of all parameters is created.}
+
+\item{learner}{[\code{\link[mlr]{Learner}}]\cr
+Regression learner from mlr, which is used as a surrogate to model our fitness function.
+If \code{NULL} (default), the default learner is determined as described here: \link{mbo_default_learner}.}
+
+\item{control}{[\code{\link{MBOControl}}]\cr
+Control object for mbo.}
+
+\item{show.info}{[\code{logical(1)}]\cr
+Verbose output on console?
+Default is \code{TRUE}.}
+
+\item{more.args}{[list]\cr
+Further arguments passed to fitness function.}
+}
+\description{
+See \link{mbo_parallel} for all parallelization options.
+}
+\examples{
+obj.fun = makeSingleObjectiveFunction(
+ fn = function(x) x[1]^2 + sin(x[2]), 
+ par.set = makeNumericParamSet(id = "x", lower = -1, upper = 1, len = 2))
+res = mboEgo(obj.fun)
+print(res)
+plot(res)
+}
+