Merge pull request #151 from Titanx-exe/master

Fixed issues regarding function prefixes and improved the documentation.

DESCRIPTION

@@ -36,7 +36,7 @@ Depends:
 Imports:
     BBmisc (>= 1.6),
     ggplot2 (>= 2.2.1),
-    Rcpp (>= 0.11.0)
+    Rcpp (>= 0.11.0),
 Suggests:
     testthat,
     MASS,

NAMESPACE

@@ -88,6 +88,7 @@ export(getName)
 export(getNumberOfEvaluations)
 export(getNumberOfObjectives)
 export(getNumberOfParameters)
+export(getOptimaDf)
 export(getRefPoint)
 export(getTags)
 export(getUpperBoxConstraints)
@@ -208,6 +209,7 @@ export(makeMichalewiczFunction)
 export(makeModifiedRastriginFunction)
 export(makeMultiObjectiveFunction)
 export(makeNKFunction)
+export(makeObjectiveFunction)
 export(makeOmniTestFunction)
 export(makePeriodicFunction)
 export(makePowellSumFunction)

R/addCountingWrapper.R

@@ -10,14 +10,15 @@
 #' @param fn [\code{smoof_function}]\cr
 #'   Smoof function which should be wrapped.
 #' @return [\code{smoof_counting_function}]
+#'   The function that includes the counting feature.
 #' @examples
 #' fn = makeBBOBFunction(dimensions = 2L, fid = 1L, iid = 1L)
 #' fn = addCountingWrapper(fn)
 #'
-#' # we get a value of 0 since the function has not been called yet
+#' # We get a value of 0 since the function has not been called yet
 #' print(getNumberOfEvaluations(fn))
 #'
-#' # now call the function 10 times consecutively
+#' # Now call the function 10 times consecutively
 #' for (i in seq(10L)) {
 #'   fn(runif(2))
 #' }
@@ -31,8 +32,8 @@
 #' @seealso \code{\link{getNumberOfEvaluations}}, \code{\link{resetEvaluationCounter}}
 #' @export
 addCountingWrapper = function(fn) {
-  if (!testClass(fn, "smoof_function") && !testClass(fn, "smoof_wrapped_function")) {
-    stopf("The passed function needs to be a (wrapped) smoof function.")
+  if (!checkmate::testClass(fn, "smoof_function") && !checkmate::testClass(fn, "smoof_wrapped_function")) {
+    BBmisc::stopf("The passed function needs to be a (wrapped) smoof function.")
   }
   force(fn)
   n.evals = 0L

R/addLoggingWrapper.R

@@ -20,9 +20,10 @@
 #'   In case of an overflow (i.e., more function evaluations than space reserved)
 #'   the data structures are re-initialized by adding space for another \code{size} evaluations.
 #'   This comes handy if you know the number of function evaluations (or at least
-#'   an upper bound thereof) a-priori and may serve to reduce the time complextity
+#'   an upper bound thereof) a-priori and may serve to reduce the time complexity
 #'   of logging values.
 #' @return [\code{smoof_logging_function}]
+#'   The function with an added logging capability.
 #' @examples
 #' # We first build the smoof function and apply the logging wrapper to it
 #' fn = makeSphereFunction(dimensions = 2L)
@@ -44,20 +45,20 @@
 #'
 #' @export
 addLoggingWrapper = function(fn, logg.x = FALSE, logg.y = TRUE, size = 100L) {
-  if (!testClass(fn, "smoof_function") && !testClass(fn, "smoof_wrapped_function")) {
-    stopf("The passed function needs to be a (wrapped) smoof function.")
+  if (!checkmate::testClass(fn, "smoof_function") && !checkmate::testClass(fn, "smoof_wrapped_function")) {
+    BBmisc::stopf("The passed function needs to be a (wrapped) smoof function.")
   }
-  assertFlag(logg.x)
-  assertFlag(logg.y)
+  checkmate::assertFlag(logg.x)
+  checkmate::assertFlag(logg.y)
 
   size = checkmate::asInt(size, lower = 1L)
 
   if (!logg.x && !logg.y) {
-    stopf("At least x or y values must be logged.")
+    BBmisc::stopf("At least x or y values must be logged.")
   }
 
   par.set = ParamHelpers::getParamSet(fn)
-  par.ids = getParamIds(par.set, with.nr = TRUE, repeated = TRUE)
+  par.ids = ParamHelpers::getParamIds(par.set, with.nr = TRUE, repeated = TRUE)
   n.obj = getNumberOfObjectives(fn)
   n.pars = getNumberOfParameters(fn)
 

R/computeExpectedRunningTime.R

@@ -13,7 +13,7 @@
 #'
 #' @details The Expected Running Time (ERT) is one of the most popular performance
 #' measures in optimization. It is defined as the expected number of function
-#' evaluations needed to reach a given precision level, i. e., to reach a certain
+#' evaluations needed to reach a given precision level, i.e., to reach a certain
 #' objective value for the first time.
 #'
 #' @references A. Auger and N. Hansen. Performance evaluation of an advanced local
@@ -24,7 +24,7 @@
 #'   Vector containing the number of function evaluations.
 #' @param fun.success.runs [\code{logical}]\cr
 #'   Boolean vector indicating which algorithm runs were successful,
-#'   i. e., which runs reached the desired target value. Default is \code{NULL}.
+#'   i.e., which runs reached the desired target value. Default is \code{NULL}.
 #' @param fun.reached.target.values [\code{numeric} | \code{NULL}]\cr
 #'   Numeric vector with the objective values reached in the runs. Default is
 #'   \code{NULL}.
@@ -42,27 +42,27 @@ computeExpectedRunningTime = function(fun.evals,
   fun.target.value = NULL,
   penalty.value = Inf) {
   #FIXME: maybe enable missing values and offer inpute mechanism?
-  assertInteger(fun.evals, lower = 1L, any.missing = FALSE)
-  assertNumber(penalty.value)
+  checkmate::assertInteger(fun.evals, lower = 1L, any.missing = FALSE)
+  checkmate::assertNumber(penalty.value)
   n = length(fun.evals)
 
   # sanity check that one of the options is used (see docs).
   if (!xor(!is.null(fun.success.runs), (!is.null(fun.reached.target.values) || !is.null(fun.target.value)))) {
-    stopf("Either 'fun.success.runs' or 'fun.reached.target.values' and 'fun.target.value' need to be specified,
+    BBmisc::stopf("Either 'fun.success.runs' or 'fun.reached.target.values' and 'fun.target.value' need to be specified,
       but not both or none.")
   }
 
   # compute successful runs
   if (!is.null(fun.reached.target.values)) {
     if (is.null(fun.target.value)) {
-      stopf("You need to pass a 'fun.target.value' in case you passed 'fun.reached.target.values'.")
+      BBmisc::stopf("You need to pass a 'fun.target.value' in case you passed 'fun.reached.target.values'.")
     }
-    assertNumeric(fun.reached.target.values, len = n, any.missing = FALSE)
-    assertNumber(fun.target.value)
+    checkmate::assertNumeric(fun.reached.target.values, len = n, any.missing = FALSE)
+    checkmate::assertNumber(fun.target.value)
     fun.success.runs = (fun.reached.target.values <= fun.target.value)
   }
 
-  assertLogical(fun.success.runs, len = n, any.missing = FALSE)
+  checkmate::assertLogical(fun.success.runs, len = n, any.missing = FALSE)
 
   # Finally compute the ERT
   # compute the success rate (since fun.success.runs is logical, this is correct)

R/conversion.R

@@ -3,18 +3,19 @@
 #'
 #' @description
 #' We can minimize f by maximizing -f. The majority of predefined objective functions
-#' in \pkg{smoof} should be minimized by default. However, there is a handful of
+#' in \pkg{smoof} should be minimized by default. However, there are a handful of
 #' functions, e.g., Keane or Alpine02, which shall be maximized by default.
 #' For benchmarking studies it might be beneficial to inverse the direction.
 #' The functions \code{convertToMaximization} and \code{convertToMinimization}
-#' do exactly that keeping the attributes.
+#' do exactly that, keeping the attributes.
 #'
 #' @note
 #' Both functions will quit with an error if multi-objective functions are passed.
 #'
 #' @param fn [\code{smoof_function}]\cr
 #'  Smoof function.
 #' @return [\code{smoof_function}]
+#'  Converted smoof function
 #' @examples
 #' # create a function which should be minimized by default
 #' fn = makeSphereFunction(1L)
@@ -43,23 +44,23 @@ convertToMinimization = function(fn) {
 }
 
 convertProblemDirection = function(fn, minimize.after = TRUE) {
-  assertFlag(minimize.after)
+  checkmate::assertFlag(minimize.after)
 
   if (isWrappedSmoofFunction(fn)) {
-    stopf("Conversion works only for unwrapped functions! Apply, e.g., counting wrapper
+    BBmisc::stopf("Conversion works only for unwrapped functions! Apply, e.g., counting wrapper
       after conversion.")
   }
 
   if (isMultiobjective(fn)) {
-    stopf("Conversion to maximization only supported for single-objective problems
+    BBmisc::stopf("Conversion to maximization only supported for single-objective problems
       at the moment, but your function '%s' has %i objectives.", getName(fn), getNumberOfObjectives(fn))
   }
 
   # If both are true, we want to convert min to min
   # If both are false, we want to convert max to max
   # Otherwise the conversion is ok
   if ((shouldBeMinimized(fn) && minimize.after) || (!shouldBeMinimized(fn) && !minimize.after)) {
-    stopf("Function should already be %s.", (if (minimize.after) "minimized" else "maximized"))
+    BBmisc::stopf("Function should already be %s.", (if (minimize.after) "minimized" else "maximized"))
   }
 
   # get attributes
@@ -77,12 +78,12 @@ convertProblemDirection = function(fn, minimize.after = TRUE) {
 
   # flip sign(s) of optima
   if (hasGlobalOptimum(fn2))
-    fn2 = setAttribute(fn2, "global.opt.value", -1.0 * attr(fn2, "global.opt.value"))
+    fn2 = BBmisc::setAttribute(fn2, "global.opt.value", -1.0 * attr(fn2, "global.opt.value"))
 
   if (hasLocalOptimum(fn2))
-    fn2 = setAttribute(fn2, "local.opt.value", -1.0 * attr(fn2, "local.opt.value"))
+    fn2 = BBmisc::setAttribute(fn2, "local.opt.value", -1.0 * attr(fn2, "local.opt.value"))
 
   # flip maximization stuff
-  fn2 = setAttribute(fn2, "minimize", !should.minimize)
+  fn2 = BBmisc::setAttribute(fn2, "minimize", !should.minimize)
   return(fn2)
 }

R/doesCountEvaluations.R

@@ -2,13 +2,14 @@
 #' Check whether the function is counting its function evaluations.
 #'
 #' @description
-#' In this case the function is of type \code{smoof_counting_function} or it
+#' In this case, the function is of type \code{smoof_counting_function} or it
 #' is further wrapped by another wrapper. This function then checks recursively,
 #' if there is a counting wrapper.
 #'
 #' @param object [any]\cr
 #'   Arbitrary R object.
 #' @return \code{logical(1)}
+#'  \code{TRUE} if the function counts its evaluations, \code{FALSE} otherwise.
 #' @seealso \code{\link{addCountingWrapper}}
 #' @export
 doesCountEvaluations = function(object) {

R/filterFunctionsByTags.R

@@ -4,7 +4,7 @@
 #' @description
 #' Single objective functions can be tagged, e.g., as unimodal. Searching for all
 #' functions with a specific tag by hand is tedious. The \code{filterFunctionsByTags}
-#' function helps to filter all single objective smoof function.
+#' function helps to filter all single objective smoof functions.
 #'
 #' @param tags [\code{character}]\cr
 #'   Character vector of tags. All available tags can be determined with a call
@@ -24,11 +24,11 @@
 #' filterFunctionsByTags(c("multimodal", "separable"), or = TRUE)
 #' @export
 filterFunctionsByTags = function(tags, or = FALSE) {
-  assertSubset(tags, choices = getAvailableTags(), empty.ok = FALSE)
-  assertFlag(or)
+  checkmate::assertSubset(tags, choices = getAvailableTags(), empty.ok = FALSE)
+  checkmate::assertFlag(or)
 
-  if (isSubset(c("single-objective", "multi-objective"), tags)) {
-    stopf("Trying to search for both single- and multi-objective functions.")
+  if (BBmisc::isSubset(c("single-objective", "multi-objective"), tags)) {
+    BBmisc::stopf("Trying to search for both single- and multi-objective functions.")
   }
 
   fun.generators = getGeneratorFunctions()

R/getAvailableTags.R

@@ -3,12 +3,13 @@
 #'
 #' @description
 #' Test function are frequently distinguished by characteristic high-level properties,
-#' e.g., unimodal or multimodal, continuous or discontinuous, separable or non-separable.
+#' e.g., uni-modal or multi-modal, continuous or discontinuous, separable or non-separable.
 #' The \pkg{smoof} package offers the possibility to associate a set of properties,
 #' termed \dQuote{tags} to a \code{smoof_function}. This helper function returns
 #' a character vector of all possible tags.
 #'
 #' @return [\code{character}]
+#'  Character vector of all the possible tags
 #' @export
 getAvailableTags = function() {
   c("unimodal", "multimodal",

R/getBoxConstraints.R

@@ -1,7 +1,8 @@
-#' Return lower box constaints.
+#' Returns lower box constraints for a Smoof function.
 #'
 #' @template arg_smoof_function
 #' @return [\code{numeric}]
+#'  Numeric vector representing the lower box constraints
 #' @export
 getLowerBoxConstraints = function(fn) {
   UseMethod("getLowerBoxConstraints")

R/getDescription.R

@@ -1,7 +1,8 @@
-#' Return the description of the function.
+#' Returns the description of the function.
 #'
 #' @template arg_smoof_function
 #' @return [\code{character(1)}]
+#'  A character string representing the description of the function.
 #' @export
 getDescription = function(fn) {
   UseMethod("getDescription")

R/getGlobalOptimum.R

@@ -3,9 +3,9 @@
 #' @template arg_smoof_function
 #' @return [\code{list}] List containing the following entries:
 #' \itemize{
-#'   \item{param [\code{list}]}{Named list of parameter value(s).}
-#'   \item{value [\code{numeric(1)}]}{Optimal value.}
-#'   \item{is.minimum [\code{logical(1)}]}{Is the global optimum a minimum or maximum?}
+#'   \item{param [\code{list}]} {Named list of parameter value(s).}
+#'   \item{value [\code{numeric(1)}]} {Optimal value.}
+#'   \item{is.minimum [\code{logical(1)}]} {Is the global optimum a minimum or maximum?}
 #' }
 #' @note Keep in mind, that this method makes sense only for single-objective target function.
 #' @export
@@ -24,7 +24,7 @@ getGlobalOptimum.smoof_single_objective_function = function(fn) {
 
 #' @export
 getGlobalOptimum.smoof_multi_objective_function = function(fn) {
-  stopf("No global optimum available for multi-objective function.")
+  BBmisc::stopf("No global optimum available for multi-objective function.")
 }
 
 #' @export

R/getID.R

@@ -1,7 +1,11 @@
-#' Return the ID / short name of the function or \code{NA} if no ID is set.
+#' @title
+#' Returns the ID / short name of the function.
+#' 
+#' @description
+#' Returns the ID / short name of the function or \code{NA} if no ID is set.
 #'
 #' @template arg_smoof_function
-#' @return [\code{character(1)}] or \code{NA}
+#' @return [\code{character(1)}] ID / short name or \code{NA}
 #' @export
 getID = function(fn) {
   UseMethod("getID")

R/getLocalOptimum.R

@@ -29,7 +29,7 @@ getLocalOptimum.smoof_single_objective_function = function(fn) {
 
 #' @export
 getLocalOptimum.smoof_multi_objective_function = function(fn) {
-  stopf("No local optimum available for multi-objective function.")
+  BBmisc::stopf("No local optimum available for multi-objective function.")
 }
 
 #' @export

R/getLoggedValues.R

@@ -1,4 +1,4 @@
-#' Extract logged values of a function wrapped by a logging wrapper.
+#' Extracts the logged values of a function wrapped by a logging wrapper.
 #'
 #' @param fn [\code{wrapped_smoof_function}]\cr
 #'   Wrapped smoof function.
@@ -10,8 +10,8 @@
 #'   \describe{
 #'     \item{pars}{Data frame of parameter values, i.e., x-values or the empty
 #'     data frame if x-values were not logged.}
-#'     \item{obj.vals}{Numeric vector of objective vals in the single-objective
-#'     case respectively a matrix of objective vals for multi-objective functions.}
+#'     \item{obj.vals}{Numeric vector of objective values in the single-objective
+#'     case respectively a matrix of objective values for multi-objective functions.}
 #'   }
 #' @seealso \code{\link{addLoggingWrapper}}
 #' @export
@@ -21,7 +21,7 @@ getLoggedValues = function(fn, compact = FALSE) {
 
 #' @export
 getLoggedValues.smoof_logging_function = function(fn, compact = FALSE) {
-  assertFlag(compact)
+  checkmate::assertFlag(compact)
 
   env = environment(fn)
   max.idx = env$curr.idx - 1L

R/getMeanFunction.R

@@ -1,7 +1,8 @@
-#' Return the true mean function in the noisy case.
+#' Returns the true mean function in the noisy case.
 #'
 #' @template arg_smoof_function
 #' @return [\code{function}]
+#'  True mean function in the noisy case.
 #' @export
 getMeanFunction = function(fn) {
   UseMethod("getMeanFunction")

R/getName.R

@@ -1,7 +1,8 @@
-#' Return the name of the function.
+#' Returns the name of the function.
 #'
 #' @template arg_smoof_function
 #' @return [\code{character(1)}]
+#'  The name of the function.
 #' @export
 getName = function(fn) {
   UseMethod("getName")

R/getNumberOfEvaluations.R

@@ -1,9 +1,10 @@
-#' Return the number of function evaluations performed by the wrapped
+#' Returns the number of function evaluations performed by the wrapped
 #' \code{smoof_function}.
 #'
 #' @param fn [\code{smoof_counting_function}]\cr
 #'   Wrapped \code{smoof_function}.
 #' @return [\code{integer(1)}]
+#'  The number of function evaluations.
 #' @export
 getNumberOfEvaluations = function(fn) {
   UseMethod("getNumberOfEvaluations")