Improved value fields and examples of exported functions

Author: AnotherSamWilson

R/addIterations.R

@@ -15,21 +15,39 @@
 #'   at each Epoch (optimization step). If running in parallel, good practice
 #'   is to set \code{iters.k} to some multiple of the number of cores you have designated
 #'   for this process. Must belower than, and preferrably some multiple of \code{iters.n}.
-#' @param otherHalting Same as bayesOpt()
-#' @param bounds Same as bayesOpt()
-#' @param acq Same as bayesOpt()
-#' @param kappa Same as bayesOpt()
-#' @param eps Same as bayesOpt()
-#' @param gsPoints Same as bayesOpt()
-#' @param convThresh Same as bayesOpt()
-#' @param acqThresh Same as bayesOpt()
-#' @param errorHandling Same as bayesOpt()
-#' @param saveFile Same as bayesOpt()
-#' @param parallel Same as bayesOpt()
-#' @param plotProgress Same as bayesOpt()
-#' @param verbose Same as bayesOpt()
-#' @param ... Same as bayesOpt()
-#' @return A \code{bayesOpt} object.
+#' @param otherHalting Same as \code{bayesOpt()}
+#' @param bounds Same as \code{bayesOpt()}
+#' @param acq Same as \code{bayesOpt()}
+#' @param kappa Same as \code{bayesOpt()}
+#' @param eps Same as \code{bayesOpt()}
+#' @param gsPoints Same as \code{bayesOpt()}
+#' @param convThresh Same as \code{bayesOpt()}
+#' @param acqThresh Same as \code{bayesOpt()}
+#' @param errorHandling Same as \code{bayesOpt()}
+#' @param saveFile Same as \code{bayesOpt()}
+#' @param parallel Same as \code{bayesOpt()}
+#' @param plotProgress Same as \code{bayesOpt()}
+#' @param verbose Same as \code{bayesOpt()}
+#' @param ... Same as \code{bayesOpt()}
+#' @return An object of class \code{bayesOpt} having run additional iterations.
+#' @examples
+#' scoringFunction <- function(x) {
+#'   a <- exp(-(2-x)^2)*1.5
+#'   b <- exp(-(4-x)^2)*2
+#'   c <- exp(-(6-x)^2)*1
+#'   return(list(Score = a+b+c))
+#' }
+#'
+#' bounds <- list(x = c(0,8))
+#'
+#' Results <- bayesOpt(
+#'     FUN = scoringFunction
+#'   , bounds = bounds
+#'   , initPoints = 3
+#'   , iters.n = 1
+#'   , gsPoints = 10
+#' )
+#' Results <- addIterations(Results,iters.n=1)
 #' @export
 addIterations <- function(
       optObj

R/bayesOpt.R

@@ -85,7 +85,22 @@
 #' @param ... Other parameters passed to \code{DiceKriging::km()}. All FUN inputs and scores
 #' are scaled from 0-1 before being passed to km. FUN inputs are scaled within \code{bounds},
 #' and scores are scaled by 0 = min(scores), 1 = max(scores).
-#' @return A \code{bayesOpt} object, containing information about the process.
+#' @return An object of class \code{bayesOpt} containing information about the process.
+#' \itemize{
+#'   \item \code{FUN}          The scoring function.
+#'   \item \code{bounds}       The bounds originally supplied.
+#'   \item \code{iters}        The total iterations that have been run.
+#'   \item \code{initPars}     The initialization parameters.
+#'   \item \code{optPars}      The optimization parameters.
+#'   \item \code{GauProList}   A list containing information on the Gaussian Processes used in optimization.
+#'   \item \code{scoreSummary} A \code{data.table} with results from the execution of \code{FUN}
+#'   at different inputs. Includes information on the epoch, iteration, function inputs, score, and any other
+#'   information returned by \code{FUN}.
+#'   \item \code{stopStatus}   Information on what caused the function to stop running. Possible explenations are
+#'   time limit, minimum utility not met, errors in \code{FUN}, iters.n was reached, or the Gaussian Process encountered
+#'   an error.
+#'   \item \code{elapsedTime} The total time in seconds the function was executing.
+#' }
 #' @references Jasper Snoek, Hugo Larochelle, Ryan P. Adams (2012) \emph{Practical Bayesian Optimization of Machine Learning Algorithms}
 #'
 #' @section Vignettes:

R/calcAcq.R

@@ -1,17 +1,4 @@
-#' @title Calculate Acquisition Function
-#'
-#' @description
-#' Function to be Maximized
-#'
-#' @param par Parameter set to predict
-#' @param GPs an object of class gp
-#' @param GPe an object of class gp
-#' @param acq Acquisition function type to be used
-#' @param y_max The current maximum known value of the target utility function
-#' @param kappa tunable parameter kappa to balance exploitation against exploration
-#' @param eps tunable parameter epsilon to balance exploitation against exploration
 #' @importFrom stats dnorm pnorm predict
-#' @return The acquisition function value.
 #' @keywords internal
 calcAcq <- function(par, scoreGP, timeGP, acq, y_max, kappa, eps) {
 

R/changeSaveFile.R

@@ -4,7 +4,28 @@
 #' @param optObj An object of class bayesOpt
 #' @param saveFile A filepath stored as a character. Must include the
 #' filename and extension as a .RDS.
-#' @return The same optObj with the updated saveFile.
+#' @return The same \code{optObj} with the updated saveFile.
+#' @examples
+#' \dontrun{
+#' scoringFunction <- function(x) {
+#'   a <- exp(-(2-x)^2)*1.5
+#'   b <- exp(-(4-x)^2)*2
+#'   c <- exp(-(6-x)^2)*1
+#'   return(list(Score = a+b+c))
+#' }
+#'
+#' bounds <- list(x = c(0,8))
+#'
+#' Results <- bayesOpt(
+#'     FUN = scoringFunction
+#'   , bounds = bounds
+#'   , initPoints = 3
+#'   , iters.n = 2
+#'   , gsPoints = 10
+#'   , saveFile = "filepath.RDS"
+#' )
+#' Results <- changeSaveFile(Results,saveFile = "DifferentFile.RDS")
+#' }
 #' @export
 changeSaveFile <- function(optObj,saveFile = NULL) {
 

R/getBestPars.R

@@ -1,12 +1,30 @@
 #' Get the Best Parameter Set
 #'
-#' Returns the parameter set which resulted in the maximum score from \code{FUN}.
+#' Returns the N parameter sets which resulted in the maximum scores from \code{FUN}.
 #'
-#' If N > 1, a data.table with N rows is returned, order by score decreasing.
-#' If N = 1, a list of parameters is returned.
-#'
-#' @param optObj An object of class bayesOpt
+#' @param optObj An object of class \code{bayesOpt}
 #' @param N The number of parameter sets to return
+#' @return A list containing the \code{FUN} inputs which resulted in the highest returned Score.
+#' If N > 1, a \code{data.table} is returned. Each row is a result from \code{FUN}, with results ordered by
+#' descending Score.
+#' @examples
+#' scoringFunction <- function(x) {
+#'   a <- exp(-(2-x)^2)*1.5
+#'   b <- exp(-(4-x)^2)*2
+#'   c <- exp(-(6-x)^2)*1
+#'   return(list(Score = a+b+c))
+#' }
+#'
+#' bounds <- list(x = c(0,8))
+#'
+#' Results <- bayesOpt(
+#'     FUN = scoringFunction
+#'   , bounds = bounds
+#'   , initPoints = 3
+#'   , iters.n = 2
+#'   , gsPoints = 10
+#' )
+#' print(getBestPars(Results))
 #' @export
 getBestPars <- function(
     optObj

R/getLocalOptimums.R

@@ -7,7 +7,7 @@
 #' dbscan is then used to cluster points together which converged to the same
 #' optimum - only unique optimums are returned.
 #'
-#' @param optObj an object of class bayesOpt. The following parameters are all defaulted to
+#' @param optObj an object of class \code{bayesOpt}. The following parameters are all defaulted to
 #' the options provided in this object, but can be manually specified.
 #' @param bounds Same as in \code{bayesOpt()}
 #' @param acq Same as in \code{bayesOpt()}
@@ -20,6 +20,24 @@
 #' @return A data table of local optimums, including the utility (gpUtility), the
 #' utility relative to the max utility (relUtility), and the steps taken in the
 #' L-BFGS-B method (gradCount).
+#' @examples
+#' scoringFunction <- function(x) {
+#'   a <- exp(-(2-x)^2)*1.5
+#'   b <- exp(-(4-x)^2)*2
+#'   c <- exp(-(6-x)^2)*1
+#'   return(list(Score = a+b+c))
+#' }
+#'
+#' bounds <- list(x = c(0,8))
+#'
+#' Results <- bayesOpt(
+#'     FUN = scoringFunction
+#'   , bounds = bounds
+#'   , initPoints = 3
+#'   , iters.n = 2
+#'   , gsPoints = 10
+#' )
+#' print(getLocalOptimums(Results))
 #' @importFrom stats optim
 #' @importFrom data.table as.data.table
 #' @import foreach

R/plot.R

@@ -8,7 +8,26 @@
 #' @importFrom ggplot2 ggplot aes_string xlab scale_color_discrete geom_point theme guides guide_legend margin element_text unit xlim ylab
 #' @importFrom ggpubr ggarrange annotate_figure text_grob
 #' @importFrom graphics plot
-#' @return an object of class ggarrange
+#' @return an object of class \code{ggarrange} from the \code{ggpubr} package.
+#' @examples
+#' scoringFunction <- function(x) {
+#'   a <- exp(-(2-x)^2)*1.5
+#'   b <- exp(-(4-x)^2)*2
+#'   c <- exp(-(6-x)^2)*1
+#'   return(list(Score = a+b+c))
+#' }
+#'
+#' bounds <- list(x = c(0,8))
+#'
+#' Results <- bayesOpt(
+#'     FUN = scoringFunction
+#'   , bounds = bounds
+#'   , initPoints = 3
+#'   , iters.n = 2
+#'   , gsPoints = 10
+#' )
+#' # This plot will also show in real time with parameter plotProgress = TRUE in bayesOpt()
+#' plot(Results)
 #' @export
 plot.bayesOpt <- function(x,...) {
 

R/updateGP.R

@@ -2,13 +2,35 @@
 #'
 #' To save time, Gaussian processes are not updated after the last iteration
 #' in \code{addIterations()}. The user can do this manually, using this function
-#' if they wish.
+#' if they wish. This is not necessary to continue optimization using \code{addIterations}.
 #' @param optObj an object of class bayesOpt
 #' @param bounds The bounds to scale the parameters within.
 #' @param verbose Should the user be warned if the GP is already up to date?
 #' @param ... passed to \code{DiceKriging::km()}
 #' @importFrom DiceKriging km
-#' @return a \code{bayesOpt} object with updated Gaussian Processes.
+#' @return An object of class \code{bayesOpt} with updated Gaussian processes.
+#' @examples
+#' # Create initial object
+#' scoringFunction <- function(x) {
+#'   a <- exp(-(2-x)^2)*1.5
+#'   b <- exp(-(4-x)^2)*2
+#'   c <- exp(-(6-x)^2)*1
+#'   return(list(Score = a+b+c))
+#' }
+#'
+#' bounds <- list(x = c(0,8))
+#'
+#' Results <- bayesOpt(
+#'     FUN = scoringFunction
+#'   , bounds = bounds
+#'   , initPoints = 3
+#'   , iters.n = 2
+#'   , gsPoints = 10
+#' )
+#'
+#' # At this point, the Gaussian Process has not been updated
+#' # with the most recent results. We can update it manually:
+#' Results <- updateGP(Results)
 #' @export
 updateGP <- function(optObj,bounds = optObj$bounds,verbose = 1, ...) {
 

cran-comments.md

@@ -14,4 +14,10 @@ There were no errors or notes. Only warnings explained that I am the maintainer
 There are no downstream dependencies.
 
 ## Changes
-Removed Plotly from dependencies. Some suggested packages are now used conditionally in vignettes, reade, tests and examples since they might not be available on all checking machines.
+#### Meta
+Package was removed because suggested package was not available on checking machine, which threw a warning when vignettes were built. Made vignettes and examples execution conditional on availability of suggested package. This doesn't affect the readability or educational value of the vignettes or examples.
+
+#### Documentation
+* Added missing value fields to .Rd files of exported functions, and improved the documentation of existing value fields. 
+* Added testable examples to all exported functions that were missing any. 
+* Reset any options that were changed by vignettes.