man-roxygen/return_irace.R

In MLopez-Ibanez/irace: Iterated Racing for Automatic Algorithm Configuration

#' @return <%=ifelse(exists("return_invisible") && return_invisible, "(`invisible(data.frame)`)", "(`data.frame`)") %>
#'
#' A data frame with the set of best algorithm configurations found by \pkg{irace}. 
#'  The data frame has the following columns:
#'
#'  *  `.ID.` : Internal id of the candidate configuration.
#'
#'  * `Parameter names` : One column per parameter name in `parameters`.
#'
#'  * `.PARENT.` : Internal id of the parent candidate configuration.
#' 
#'  Additionally, this function saves an R data file containing an object called
#'  `iraceResults`. The path of the file is indicated in `scenario$logFile`. 
#'  The `iraceResults` object is a list with the following structure:
#'
#' 
#' \describe{
#'
#' \item{`scenario`}{The scenario R object containing the \pkg{irace}
#' options used for the execution. See [`defaultScenario`] 
#' for more information. The element `scenario$parameters` contains the parameters R object that describes the target algorithm parameters. See
#' [`readParameters`].}
#' 
#' \item{`allConfigurations`}{The target algorithm configurations
#' generated by \pkg{irace}. This object is a data frame, each row is a
#' candidate configuration, the first column (`.ID.`) indicates the
#' internal identifier of the configuration, the following columns
#' correspond to the parameter values, each column named as the parameter
#' name specified in the parameter object. The final column
#' (`.PARENT.`)  is the identifier of the configuration from which
#' model the actual configuration was sampled.}
#' 
#' \item{`allElites`}{A list that contains one element per iteration,
#' each element contains the internal identifier of the elite candidate
#' configurations of the corresponding iteration (identifiers correspond to
#' `allConfigurations$.ID.`).}
#' 
#' \item{`iterationElites`}{A vector containing the best candidate
#' configuration internal identifier of each iteration. The best
#' configuration found corresponds to the last one of this vector.}
#' 
#' \item{`experiments`}{A matrix with configurations as columns and
#' instances as rows. Column names correspond to the internal identifier of
#' the configuration (`allConfigurations$.ID.`).}
#' 
#' \item{`experimen_log`}{A `data.table` with columns `iteration`,
#' `instance`, `configuration`, `time`.  This matrix contains the log of all the
#' experiments that \pkg{irace} performs during its execution.  The
#' instance column refers to the index of the `race_state$instances_log`
#' data frame. Time is saved ONLY when reported by the `targetRunner`.}
#'
#' \item{`softRestart`}{A logical vector that indicates if a soft
#' restart was performed on each iteration. If `FALSE`, then no soft
#' restart was performed.}
#'
#' \item{`state`}{An environment that contains the state of \pkg{irace}, the
#' recovery is done using the information contained in this object.}
#' 
#' \item{`testing`}{A list that contains the testing results. The
#' elements of this list are: `experiments` a matrix with the testing
#' experiments of the selected configurations in the same format as the
#' explained above and `seeds` a vector with the seeds used to execute
#' each experiment.}
#'
#' }