% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/select_best.R
\name{show_best}
\alias{show_best}
\alias{show_best.default}
\alias{show_best.tune_results}
\alias{select_best}
\alias{select_best.default}
\alias{select_best.tune_results}
\alias{select_by_pct_loss}
\alias{select_by_pct_loss.default}
\alias{select_by_pct_loss.tune_results}
\alias{select_by_one_std_err}
\alias{select_by_one_std_err.default}
\alias{select_by_one_std_err.tune_results}
\title{Investigate best tuning parameters}
\usage{
show_best(x, ...)

\method{show_best}{default}(x, ...)

\method{show_best}{tune_results}(
  x,
  ...,
  metric = NULL,
  eval_time = NULL,
  n = 5,
  call = rlang::current_env()
)

select_best(x, ...)

\method{select_best}{default}(x, ...)

\method{select_best}{tune_results}(x, ..., metric = NULL, eval_time = NULL)

select_by_pct_loss(x, ...)

\method{select_by_pct_loss}{default}(x, ...)

\method{select_by_pct_loss}{tune_results}(x, ..., metric = NULL, eval_time = NULL, limit = 2)

select_by_one_std_err(x, ...)

\method{select_by_one_std_err}{default}(x, ...)

\method{select_by_one_std_err}{tune_results}(x, ..., metric = NULL, eval_time = NULL)
}
\arguments{
\item{x}{The results of \code{\link[=tune_grid]{tune_grid()}} or \code{\link[=tune_bayes]{tune_bayes()}}.}

\item{...}{For \code{\link[=select_by_one_std_err]{select_by_one_std_err()}} and \code{\link[=select_by_pct_loss]{select_by_pct_loss()}}, this
argument is passed directly to \code{\link[dplyr:arrange]{dplyr::arrange()}} so that the user can sort
the models from \emph{most simple to most complex}. That is, for a parameter \code{p},
pass the unquoted expression \code{p} if smaller values of \code{p} indicate a simpler
model, or \code{desc(p)} if larger values indicate a simpler model. At
least one term is required for these two functions. See the examples below.}

\item{metric}{A character value for the metric that will be used to sort
the models. (See
\url{https://yardstick.tidymodels.org/articles/metric-types.html} for
more details). Not required if a single metric exists in \code{x}. If there are
multiple metric and none are given, the first in the metric set is used (and
a warning is issued).}

\item{eval_time}{A single numeric time point where dynamic event time
metrics should be chosen (e.g., the time-dependent ROC curve, etc). The
values should be consistent with the values used to create \code{x}. The \code{NULL}
default will automatically use the first evaluation time used by \code{x}.}

\item{n}{An integer for the number of top results/rows to return.}

\item{call}{The call to be shown in errors and warnings.}

\item{limit}{The limit of loss of performance that is acceptable (in percent
units). See details below.}
}
\value{
A tibble with columns for the parameters. \code{\link[=show_best]{show_best()}} also
includes columns for performance metrics.
}
\description{
\code{\link[=show_best]{show_best()}} displays the top sub-models and their performance estimates.

\code{\link[=select_best]{select_best()}} finds the tuning parameter combination with the best
performance values.

\code{\link[=select_by_one_std_err]{select_by_one_std_err()}} uses the "one-standard error rule" (Breiman _el
at, 1984) that selects the most simple model that is within one standard
error of the numerically optimal results.

\code{\link[=select_by_pct_loss]{select_by_pct_loss()}} selects the most simple model whose loss of
performance is within some acceptable limit.
}
\details{
For percent loss, suppose the best model has an RMSE of 0.75 and a simpler
model has an RMSE of 1. The percent loss would be \code{(1.00 - 0.75)/1.00 * 100},
or 25 percent. Note that loss will always be non-negative.
}
\examples{
\dontshow{if (tune:::should_run_examples()) withAutoprint(\{ # examplesIf}
data("example_ames_knn")

show_best(ames_iter_search, metric = "rmse")

select_best(ames_iter_search, metric = "rsq")

# To find the least complex model within one std error of the numerically
# optimal model, the number of nearest neighbors are sorted from the largest
# number of neighbors (the least complex class boundary) to the smallest
# (corresponding to the most complex model).

select_by_one_std_err(ames_grid_search, metric = "rmse", desc(K))

# Now find the least complex model that has no more than a 5\% loss of RMSE:
select_by_pct_loss(
  ames_grid_search,
  metric = "rmse",
  limit = 5, desc(K)
)
\dontshow{\}) # examplesIf}
}
\references{
Breiman, Leo; Friedman, J. H.; Olshen, R. A.; Stone, C. J. (1984).
\emph{Classification and Regression Trees.} Monterey, CA: Wadsworth.
}
