% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/TunerBatchSuccessiveHalving.R
\name{mlr_tuners_successive_halving}
\alias{mlr_tuners_successive_halving}
\alias{TunerBatchSuccessiveHalving}
\title{Hyperparameter Tuning with Successive Halving}
\source{
Jamieson K, Talwalkar A (2016).
\dQuote{Non-stochastic Best Arm Identification and Hyperparameter Optimization.}
In Gretton A, Robert CC (eds.), \emph{Proceedings of the 19th International Conference on Artificial Intelligence and Statistics}, volume 51 series Proceedings of Machine Learning Research, 240-248.
\url{http://proceedings.mlr.press/v51/jamieson16.html}.
}
\description{
Optimizer using the Successive Halving Algorithm (SHA).
SHA is initialized with the number of starting configurations \code{n}, the proportion of configurations discarded in each stage \code{eta}, and the minimum \code{r_min} and maximum \verb{_max} budget of a single evaluation.
The algorithm starts by sampling \code{n} random configurations and allocating the minimum budget \code{r_min} to them.
The configurations are evaluated and \code{1 / eta} of the worst-performing configurations are discarded.
The remaining configurations are promoted to the next stage and evaluated on a larger budget.
The following table is the stage layout for \code{eta = 2}, \code{r_min = 1} and \code{r_max = 8}.\tabular{rrr}{
   \code{i} \tab \code{n_i} \tab \code{r_i} \cr
   0 \tab 8 \tab 1 \cr
   1 \tab 4 \tab 2 \cr
   2 \tab 2 \tab 4 \cr
   3 \tab 1 \tab 8 \cr
}


\code{i} is the stage number, \code{n_i} is the number of configurations and \code{r_i} is the budget allocated to a single configuration.

The number of stages is calculated so that each stage consumes approximately the same budget.
This sometimes results in the minimum budget having to be slightly adjusted by the algorithm.
}
\section{Dictionary}{

This \link[mlr3tuning:Tuner]{mlr3tuning::Tuner} can be instantiated via the \link[mlr3misc:Dictionary]{dictionary}
\link[mlr3tuning:mlr_tuners]{mlr3tuning::mlr_tuners} or with the associated sugar function \code{\link[mlr3tuning:tnr]{mlr3tuning::tnr()}}:

\if{html}{\out{<div class="sourceCode">}}\preformatted{TunerBatchSuccessiveHalving$new()
mlr_tuners$get("successive_halving")
tnr("successive_halving")
}\if{html}{\out{</div>}}
}

\section{Subsample Budget}{

If the learner lacks a natural budget parameter,
\link[mlr3pipelines:mlr_pipeops_subsample]{mlr3pipelines::PipeOpSubsample} can be applied to use the subsampling rate
as budget parameter. The resulting \link[mlr3pipelines:mlr_learners_graph]{mlr3pipelines::GraphLearner} is fitted on
small proportions of the \link[mlr3:Task]{mlr3::Task} in the first stage, and on the complete
task in last stage.
}

\section{Custom Sampler}{

Hyperband supports custom \link[paradox:Sampler]{paradox::Sampler} object for initial
configurations in each bracket.
A custom sampler may look like this (the full example is given in the
\emph{examples} section):

\if{html}{\out{<div class="sourceCode">}}\preformatted{# - beta distribution with alpha = 2 and beta = 5
# - categorical distribution with custom probabilities
sampler = SamplerJointIndep$new(list(
  Sampler1DRfun$new(params[[2]], function(n) rbeta(n, 2, 5)),
  Sampler1DCateg$new(params[[3]], prob = c(0.2, 0.3, 0.5))
))
}\if{html}{\out{</div>}}
}

\section{Progress Bars}{

\verb{$optimize()} supports progress bars via the package \CRANpkg{progressr}
combined with a \link[bbotk:Terminator]{bbotk::Terminator}. Simply wrap the function in
\code{progressr::with_progress()} to enable them. We recommend to use package
\CRANpkg{progress} as backend; enable with \code{progressr::handlers("progress")}.
}

\section{Parallelization}{

The hyperparameter configurations of one stage are evaluated in parallel with the \CRANpkg{future} package.
To select a parallel backend, use the \code{plan()} function of the \CRANpkg{future} package.
}

\section{Logging}{

Hyperband uses a logger (as implemented in \CRANpkg{lgr}) from package
\CRANpkg{bbotk}.
Use \code{lgr::get_logger("bbotk")} to access and control the logger.
}

\section{Resources}{

The \href{https://mlr-org.com/gallery-all-optimization.html}{gallery} features a collection of case studies and demos about optimization.
\itemize{
\item \href{https://mlr-org.com/gallery/series/2023-01-15-hyperband-xgboost/}{Tune} the hyperparameters of XGBoost with Hyperband (Hyperband can be easily swapped with SHA).
\item Use data \href{https://mlr-org.com/gallery/series/2023-01-16-hyperband-subsampling/}{subsampling} and Hyperband to optimize a support vector machine.
}
}

\section{Parameters}{

\describe{
\item{\code{n}}{\code{integer(1)}\cr
Number of configurations in the base stage.}
\item{\code{eta}}{\code{numeric(1)}\cr
With every stage, the budget is increased by a factor of \code{eta} and only the best \code{1 / eta} configurations are promoted to the next stage.
Non-integer values are supported, but \code{eta} is not allowed to be less or equal to 1.}
\item{\code{sampler}}{\link[paradox:Sampler]{paradox::Sampler}\cr
Object defining how the samples of the parameter space should be drawn.
The default is uniform sampling.}
\item{\code{repetitions}}{\code{integer(1)}\cr
If \code{1} (default), optimization is stopped once all stages are evaluated.
Otherwise, optimization is stopped after \code{repetitions} runs of SHA.
The \link[bbotk:Terminator]{bbotk::Terminator} might stop the optimization before all repetitions are executed.}
\item{\code{adjust_minimum_budget}}{\code{logical(1)}\cr
If \code{TRUE}, the minimum budget is increased so that the last stage uses the maximum budget defined in the search space.}
}
}

\section{Archive}{

The \link[bbotk:Archive]{bbotk::Archive} holds the following additional columns that are specific to SHA:
\itemize{
\item \code{stage} (\verb{integer(1))}\cr
Stage index. Starts counting at 0.
\item \code{repetition} (\verb{integer(1))}\cr
Repetition index. Start counting at 1.
}
}

\examples{
if(requireNamespace("xgboost")) {
  library(mlr3learners)

  # define hyperparameter and budget parameter
  search_space = ps(
    nrounds = p_int(lower = 1, upper = 16, tags = "budget"),
    eta = p_dbl(lower = 0, upper = 1),
    booster = p_fct(levels = c("gbtree", "gblinear", "dart"))
  )

  \donttest{
  # hyperparameter tuning on the pima indians diabetes data set
  instance = tune(
    tnr("successive_halving"),
    task = tsk("pima"),
    learner = lrn("classif.xgboost", eval_metric = "logloss"),
    resampling = rsmp("cv", folds = 3),
    measures = msr("classif.ce"),
    search_space = search_space,
    term_evals = 100
  )

  # best performing hyperparameter configuration
  instance$result
  }
}
}
\section{Super classes}{
\code{\link[mlr3tuning:Tuner]{mlr3tuning::Tuner}} -> \code{\link[mlr3tuning:TunerBatch]{mlr3tuning::TunerBatch}} -> \code{\link[mlr3tuning:TunerBatchFromOptimizerBatch]{mlr3tuning::TunerBatchFromOptimizerBatch}} -> \code{TunerBatchSuccessiveHalving}
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-TunerBatchSuccessiveHalving-new}{\code{TunerBatchSuccessiveHalving$new()}}
\item \href{#method-TunerBatchSuccessiveHalving-clone}{\code{TunerBatchSuccessiveHalving$clone()}}
}
}
\if{html}{\out{
<details open><summary>Inherited methods</summary>
<ul>
<li><span class="pkg-link" data-pkg="mlr3tuning" data-topic="Tuner" data-id="format"><a href='../../mlr3tuning/html/Tuner.html#method-Tuner-format'><code>mlr3tuning::Tuner$format()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3tuning" data-topic="Tuner" data-id="help"><a href='../../mlr3tuning/html/Tuner.html#method-Tuner-help'><code>mlr3tuning::Tuner$help()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3tuning" data-topic="Tuner" data-id="print"><a href='../../mlr3tuning/html/Tuner.html#method-Tuner-print'><code>mlr3tuning::Tuner$print()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3tuning" data-topic="TunerBatchFromOptimizerBatch" data-id="optimize"><a href='../../mlr3tuning/html/TunerBatchFromOptimizerBatch.html#method-TunerBatchFromOptimizerBatch-optimize'><code>mlr3tuning::TunerBatchFromOptimizerBatch$optimize()</code></a></span></li>
</ul>
</details>
}}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-TunerBatchSuccessiveHalving-new"></a>}}
\if{latex}{\out{\hypertarget{method-TunerBatchSuccessiveHalving-new}{}}}
\subsection{Method \code{new()}}{
Creates a new instance of this \link[R6:R6Class]{R6} class.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{TunerBatchSuccessiveHalving$new()}\if{html}{\out{</div>}}
}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-TunerBatchSuccessiveHalving-clone"></a>}}
\if{latex}{\out{\hypertarget{method-TunerBatchSuccessiveHalving-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{TunerBatchSuccessiveHalving$clone(deep = FALSE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{deep}}{Whether to make a deep clone.}
}
\if{html}{\out{</div>}}
}
}
}
