% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/LearnerRegrXgboost.R
\name{mlr_learners_regr.xgboost}
\alias{mlr_learners_regr.xgboost}
\alias{LearnerRegrXgboost}
\title{Extreme Gradient Boosting Regression Learner}
\description{
eXtreme Gradient Boosting regression.
Calls \code{\link[xgboost:xgb.train]{xgboost::xgb.train()}} from package \CRANpkg{xgboost}.

To compute on GPUs, you first need to compile \CRANpkg{xgboost} yourself and link
against CUDA. See \url{https://xgboost.readthedocs.io/en/stable/build.html#building-with-gpu-support}.

Note that using the \code{watchlist} parameter directly will lead to problems when wrapping this \link[mlr3:Learner]{mlr3::Learner} in a
\code{mlr3pipelines} \code{GraphLearner} as the preprocessing steps will not be applied to the data in the watchlist.
See the section \emph{Early Stopping and Validation} on how to do this.
}
\note{
To compute on GPUs, you first need to compile \CRANpkg{xgboost} yourself and link
against CUDA.
See \url{https://xgboost.readthedocs.io/en/stable/build.html#building-with-gpu-support}.
}
\section{Dictionary}{

This \link[mlr3:Learner]{mlr3::Learner} can be instantiated via the \link[mlr3misc:Dictionary]{dictionary} \link[mlr3:mlr_learners]{mlr3::mlr_learners} or with the associated sugar function \code{\link[mlr3:mlr_sugar]{mlr3::lrn()}}:

\if{html}{\out{<div class="sourceCode">}}\preformatted{mlr_learners$get("regr.xgboost")
lrn("regr.xgboost")
}\if{html}{\out{</div>}}
}

\section{Meta Information}{

\itemize{
\item Task type: \dQuote{regr}
\item Predict Types: \dQuote{response}
\item Feature Types: \dQuote{logical}, \dQuote{integer}, \dQuote{numeric}
\item Required Packages: \CRANpkg{mlr3}, \CRANpkg{mlr3learners}, \CRANpkg{xgboost}
}
}

\section{Parameters}{
\tabular{lllll}{
   Id \tab Type \tab Default \tab Levels \tab Range \cr
   alpha \tab numeric \tab 0 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   approxcontrib \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   base_score \tab numeric \tab 0.5 \tab  \tab \eqn{(-\infty, \infty)}{(-Inf, Inf)} \cr
   booster \tab character \tab gbtree \tab gbtree, gblinear, dart \tab - \cr
   callbacks \tab untyped \tab list() \tab  \tab - \cr
   colsample_bylevel \tab numeric \tab 1 \tab  \tab \eqn{[0, 1]}{[0, 1]} \cr
   colsample_bynode \tab numeric \tab 1 \tab  \tab \eqn{[0, 1]}{[0, 1]} \cr
   colsample_bytree \tab numeric \tab 1 \tab  \tab \eqn{[0, 1]}{[0, 1]} \cr
   device \tab untyped \tab "cpu" \tab  \tab - \cr
   disable_default_eval_metric \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   early_stopping_rounds \tab integer \tab NULL \tab  \tab \eqn{[1, \infty)}{[1, Inf)} \cr
   eta \tab numeric \tab 0.3 \tab  \tab \eqn{[0, 1]}{[0, 1]} \cr
   eval_metric \tab untyped \tab "rmse" \tab  \tab - \cr
   feature_selector \tab character \tab cyclic \tab cyclic, shuffle, random, greedy, thrifty \tab - \cr
   gamma \tab numeric \tab 0 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   grow_policy \tab character \tab depthwise \tab depthwise, lossguide \tab - \cr
   interaction_constraints \tab untyped \tab - \tab  \tab - \cr
   iterationrange \tab untyped \tab - \tab  \tab - \cr
   lambda \tab numeric \tab 1 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   lambda_bias \tab numeric \tab 0 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   max_bin \tab integer \tab 256 \tab  \tab \eqn{[2, \infty)}{[2, Inf)} \cr
   max_delta_step \tab numeric \tab 0 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   max_depth \tab integer \tab 6 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   max_leaves \tab integer \tab 0 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   maximize \tab logical \tab NULL \tab TRUE, FALSE \tab - \cr
   min_child_weight \tab numeric \tab 1 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   missing \tab numeric \tab NA \tab  \tab \eqn{(-\infty, \infty)}{(-Inf, Inf)} \cr
   monotone_constraints \tab untyped \tab 0 \tab  \tab - \cr
   normalize_type \tab character \tab tree \tab tree, forest \tab - \cr
   nrounds \tab integer \tab - \tab  \tab \eqn{[1, \infty)}{[1, Inf)} \cr
   nthread \tab integer \tab 1 \tab  \tab \eqn{[1, \infty)}{[1, Inf)} \cr
   ntreelimit \tab integer \tab NULL \tab  \tab \eqn{[1, \infty)}{[1, Inf)} \cr
   num_parallel_tree \tab integer \tab 1 \tab  \tab \eqn{[1, \infty)}{[1, Inf)} \cr
   objective \tab untyped \tab "reg:squarederror" \tab  \tab - \cr
   one_drop \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   outputmargin \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   predcontrib \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   predinteraction \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   predleaf \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   print_every_n \tab integer \tab 1 \tab  \tab \eqn{[1, \infty)}{[1, Inf)} \cr
   process_type \tab character \tab default \tab default, update \tab - \cr
   rate_drop \tab numeric \tab 0 \tab  \tab \eqn{[0, 1]}{[0, 1]} \cr
   refresh_leaf \tab logical \tab TRUE \tab TRUE, FALSE \tab - \cr
   reshape \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   sampling_method \tab character \tab uniform \tab uniform, gradient_based \tab - \cr
   sample_type \tab character \tab uniform \tab uniform, weighted \tab - \cr
   save_name \tab untyped \tab NULL \tab  \tab - \cr
   save_period \tab integer \tab NULL \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   scale_pos_weight \tab numeric \tab 1 \tab  \tab \eqn{(-\infty, \infty)}{(-Inf, Inf)} \cr
   seed_per_iteration \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   skip_drop \tab numeric \tab 0 \tab  \tab \eqn{[0, 1]}{[0, 1]} \cr
   strict_shape \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   subsample \tab numeric \tab 1 \tab  \tab \eqn{[0, 1]}{[0, 1]} \cr
   top_k \tab integer \tab 0 \tab  \tab \eqn{[0, \infty)}{[0, Inf)} \cr
   training \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   tree_method \tab character \tab auto \tab auto, exact, approx, hist, gpu_hist \tab - \cr
   tweedie_variance_power \tab numeric \tab 1.5 \tab  \tab \eqn{[1, 2]}{[1, 2]} \cr
   updater \tab untyped \tab - \tab  \tab - \cr
   verbose \tab integer \tab 1 \tab  \tab \eqn{[0, 2]}{[0, 2]} \cr
   watchlist \tab untyped \tab NULL \tab  \tab - \cr
   xgb_model \tab untyped \tab NULL \tab  \tab - \cr
}
}

\section{Early Stopping and Validation}{

In order to monitor the validation performance during the training, you can set the \verb{$validate} field of the Learner.
For information on how to configure the valdiation set, see the \emph{Validation} section of \link[mlr3:Learner]{mlr3::Learner}.
This validation data can also be used for early stopping, which can be enabled by setting the \code{early_stopping_rounds} parameter.
The final (or in the case of early stopping best) validation scores can be accessed via \verb{$internal_valid_scores}, and the optimal \code{nrounds} via \verb{$internal_tuned_values}.
The internal validation measure can be set via the \code{eval_metric} parameter that can be a \link[mlr3:Measure]{mlr3::Measure}, a function, or a character string for the internal xgboost measures.
Using an \link[mlr3:Measure]{mlr3::Measure} is slower than the internal xgboost measures, but allows to use the same measure for tuning and validation.
}

\section{Initial parameter values}{

\itemize{
\item \code{nrounds}:
\itemize{
\item Actual default: no default.
\item Adjusted default: 1000.
\item Reason for change: Without a default construction of the learner would error.
The lightgbm learner has a default of 1000, so we use the same here.
}
\item \code{nthread}:
\itemize{
\item Actual value: Undefined, triggering auto-detection of the number of CPUs.
\item Adjusted value: 1.
\item Reason for change: Conflicting with parallelization via \CRANpkg{future}.
}
\item \code{verbose}:
\itemize{
\item Actual default: 1.
\item Adjusted default: 0.
\item Reason for change: Reduce verbosity.
}
}
}

\examples{
\dontrun{
if (requireNamespace("xgboost", quietly = TRUE)) {
# Define the Learner and set parameter values
learner = lrn("regr.xgboost")
print(learner)

# Define a Task
task = tsk("mtcars")

# Create train and test set
ids = partition(task)

# Train the learner on the training ids
learner$train(task, row_ids = ids$train)

# print the model
print(learner$model)

# importance method
if("importance" \%in\% learner$properties) print(learner$importance)

# Make predictions for the test rows
predictions = learner$predict(task, row_ids = ids$test)

# Score the predictions
predictions$score()
}
}

\dontrun{
# Train learner with early stopping on spam data set
task = tsk("mtcars")

# use 30 percent for validation
# Set early stopping parameter
learner = lrn("regr.xgboost",
  nrounds = 100,
  early_stopping_rounds = 10,
  validate = 0.3
)

# Train learner with early stopping
learner$train(task)

# Inspect optimal nrounds and validation performance
learner$internal_tuned_values
learner$internal_valid_scores
}
}
\references{
Chen, Tianqi, Guestrin, Carlos (2016).
\dQuote{Xgboost: A scalable tree boosting system.}
In \emph{Proceedings of the 22nd ACM SIGKDD Conference on Knowledge Discovery and Data Mining}, 785--794.
ACM.
\doi{10.1145/2939672.2939785}.
}
\seealso{
\itemize{
\item Chapter in the \href{https://mlr3book.mlr-org.com/}{mlr3book}:
\url{https://mlr3book.mlr-org.com/chapters/chapter2/data_and_basic_modeling.html#sec-learners}
\item Package \href{https://github.com/mlr-org/mlr3extralearners}{mlr3extralearners} for more learners.
\item \link[mlr3misc:Dictionary]{Dictionary} of \link[mlr3:Learner]{Learners}: \link[mlr3:mlr_learners]{mlr3::mlr_learners}
\item \code{as.data.table(mlr_learners)} for a table of available \link[mlr3:Learner]{Learners} in the running session (depending on the loaded packages).
\item \CRANpkg{mlr3pipelines} to combine learners with pre- and postprocessing steps.
\item Extension packages for additional task types:
\itemize{
\item \CRANpkg{mlr3proba} for probabilistic supervised regression and survival analysis.
\item \CRANpkg{mlr3cluster} for unsupervised clustering.
}
\item \CRANpkg{mlr3tuning} for tuning of hyperparameters, \CRANpkg{mlr3tuningspaces}
for established default tuning spaces.
}

Other Learner: 
\code{\link{mlr_learners_classif.cv_glmnet}},
\code{\link{mlr_learners_classif.glmnet}},
\code{\link{mlr_learners_classif.kknn}},
\code{\link{mlr_learners_classif.lda}},
\code{\link{mlr_learners_classif.log_reg}},
\code{\link{mlr_learners_classif.multinom}},
\code{\link{mlr_learners_classif.naive_bayes}},
\code{\link{mlr_learners_classif.nnet}},
\code{\link{mlr_learners_classif.qda}},
\code{\link{mlr_learners_classif.ranger}},
\code{\link{mlr_learners_classif.svm}},
\code{\link{mlr_learners_classif.xgboost}},
\code{\link{mlr_learners_regr.cv_glmnet}},
\code{\link{mlr_learners_regr.glmnet}},
\code{\link{mlr_learners_regr.kknn}},
\code{\link{mlr_learners_regr.km}},
\code{\link{mlr_learners_regr.lm}},
\code{\link{mlr_learners_regr.nnet}},
\code{\link{mlr_learners_regr.ranger}},
\code{\link{mlr_learners_regr.svm}}
}
\concept{Learner}
\section{Super classes}{
\code{\link[mlr3:Learner]{mlr3::Learner}} -> \code{\link[mlr3:LearnerRegr]{mlr3::LearnerRegr}} -> \code{LearnerRegrXgboost}
}
\section{Active bindings}{
\if{html}{\out{<div class="r6-active-bindings">}}
\describe{
\item{\code{internal_valid_scores}}{(named \code{list()} or \code{NULL})
The validation scores extracted from \code{model$evaluation_log}.
If early stopping is activated, this contains the validation scores of the model for the optimal \code{nrounds},
otherwise the \code{nrounds} for the final model.}

\item{\code{internal_tuned_values}}{(named \code{list()} or \code{NULL})
If early stopping is activated, this returns a list with \code{nrounds},
which is extracted from \verb{$best_iteration} of the model and otherwise \code{NULL}.}

\item{\code{validate}}{(\code{numeric(1)} or \code{character(1)} or \code{NULL})
How to construct the internal validation data. This parameter can be either \code{NULL},
a ratio, \code{"test"}, or \code{"predefined"}.
Returns the \verb{$best_iteration} when early stopping is activated.}
}
\if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-LearnerRegrXgboost-new}{\code{LearnerRegrXgboost$new()}}
\item \href{#method-LearnerRegrXgboost-importance}{\code{LearnerRegrXgboost$importance()}}
\item \href{#method-LearnerRegrXgboost-clone}{\code{LearnerRegrXgboost$clone()}}
}
}
\if{html}{\out{
<details><summary>Inherited methods</summary>
<ul>
<li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="base_learner"><a href='../../mlr3/html/Learner.html#method-Learner-base_learner'><code>mlr3::Learner$base_learner()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="format"><a href='../../mlr3/html/Learner.html#method-Learner-format'><code>mlr3::Learner$format()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="help"><a href='../../mlr3/html/Learner.html#method-Learner-help'><code>mlr3::Learner$help()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="predict"><a href='../../mlr3/html/Learner.html#method-Learner-predict'><code>mlr3::Learner$predict()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="predict_newdata"><a href='../../mlr3/html/Learner.html#method-Learner-predict_newdata'><code>mlr3::Learner$predict_newdata()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="print"><a href='../../mlr3/html/Learner.html#method-Learner-print'><code>mlr3::Learner$print()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="reset"><a href='../../mlr3/html/Learner.html#method-Learner-reset'><code>mlr3::Learner$reset()</code></a></span></li>
<li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="train"><a href='../../mlr3/html/Learner.html#method-Learner-train'><code>mlr3::Learner$train()</code></a></span></li>
</ul>
</details>
}}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-LearnerRegrXgboost-new"></a>}}
\if{latex}{\out{\hypertarget{method-LearnerRegrXgboost-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{LearnerRegrXgboost$new()}\if{html}{\out{</div>}}
}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-LearnerRegrXgboost-importance"></a>}}
\if{latex}{\out{\hypertarget{method-LearnerRegrXgboost-importance}{}}}
\subsection{Method \code{importance()}}{
The importance scores are calculated with \code{\link[xgboost:xgb.importance]{xgboost::xgb.importance()}}.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{LearnerRegrXgboost$importance()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
Named \code{numeric()}.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-LearnerRegrXgboost-clone"></a>}}
\if{latex}{\out{\hypertarget{method-LearnerRegrXgboost-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{LearnerRegrXgboost$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>}}
}
}
}
