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

Note that using the \code{evals} 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 \code{evals}.
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}.

The \code{outputmargin}, \code{predcontrib}, \code{predinteraction}, and \code{predleaf} parameters are not supported.
You can still call e.g. \code{predict(learner$model, newdata = newdata, outputmargin = TRUE)} to get these predictions.
}
\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.
}
\item \code{verbosity}:
\itemize{
\item Actual default: 1.
\item Adjusted default: 0.
\item Reason for change: Reduce verbosity.
}
}
}

\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 validation 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{custom_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{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:lrn]{mlr3::lrn()}}:

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

\section{Meta Information}{

\itemize{
\item Task type: \dQuote{classif}
\item Predict Types: \dQuote{response}, \dQuote{prob}
\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 - \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
   evals \tab untyped \tab NULL \tab  \tab - \cr
   eval_metric \tab untyped \tab - \tab  \tab - \cr
   custom_metric \tab untyped \tab - \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
   max_bin \tab integer \tab 256 \tab  \tab \eqn{[2, \infty)}{[2, Inf)} \cr
   max_cached_hist_node \tab integer \tab 65536 \tab  \tab \eqn{(-\infty, \infty)}{(-Inf, Inf)} \cr
   max_cat_to_onehot \tab integer \tab - \tab  \tab \eqn{(-\infty, \infty)}{(-Inf, Inf)} \cr
   max_cat_threshold \tab numeric \tab - \tab  \tab \eqn{(-\infty, \infty)}{(-Inf, 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
   nrounds \tab integer \tab - \tab  \tab \eqn{[1, \infty)}{[1, Inf)} \cr
   normalize_type \tab character \tab tree \tab tree, forest \tab - \cr
   nthread \tab integer \tab - \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 "binary:logistic" \tab  \tab - \cr
   one_drop \tab logical \tab FALSE \tab TRUE, FALSE \tab - \cr
   print_every_n \tab integer \tab 1 \tab  \tab \eqn{[1, \infty)}{[1, Inf)} \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
   seed \tab integer \tab - \tab  \tab \eqn{(-\infty, \infty)}{(-Inf, Inf)} \cr
   seed_per_iteration \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
   skip_drop \tab numeric \tab 0 \tab  \tab \eqn{[0, 1]}{[0, 1]} \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
   use_rmm \tab logical \tab - \tab TRUE, FALSE \tab - \cr
   validate_features \tab logical \tab TRUE \tab TRUE, FALSE \tab - \cr
   verbose \tab integer \tab - \tab  \tab \eqn{[0, 2]}{[0, 2]} \cr
   verbosity \tab integer \tab - \tab  \tab \eqn{[0, 2]}{[0, 2]} \cr
   xgb_model \tab untyped \tab NULL \tab  \tab - \cr
   use_pred_offset \tab logical \tab - \tab TRUE, FALSE \tab - \cr
}
}

\section{Offset}{

If a \code{Task} has a column with the role \code{offset}, it will automatically be used during training.
The offset is incorporated through the \link[xgboost:xgb.DMatrix]{xgboost::xgb.DMatrix} interface, using the \code{base_margin} field.
During prediction, the offset column from the test set is used only if \code{use_pred_offset = TRUE} (default) and
the \code{Task} has a column with the role \code{offset}.
The test set offsets are passed via the \code{base_margin} argument in \code{\link[xgboost:predict.xgb.Booster]{xgboost::predict.xgb.Booster()}}.
Otherwise, if the user sets \code{use_pred_offset = FALSE} (or the \code{Task} doesn't have a column with the \code{offset} role),
the (possibly estimated) global intercept from the train set is applied.
See \url{https://xgboost.readthedocs.io/en/stable/tutorials/intercept.html}.
}

\examples{
\dontshow{if (mlr3misc::require_namespaces(lrn("classif.xgboost")$packages, quietly = TRUE)) withAutoprint(\{ # examplesIf}
\donttest{
# Define the Learner and set parameter values
learner = lrn("classif.xgboost")
print(learner)

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

# 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()

# Early stopping
learner = lrn("classif.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
}
\dontshow{\}) # examplesIf}
}
\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_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}},
\code{\link{mlr_learners_regr.xgboost}}
}
\concept{Learner}
\section{Super classes}{
\code{\link[mlr3:Learner]{mlr3::Learner}} -> \code{\link[mlr3:LearnerClassif]{mlr3::LearnerClassif}} -> \code{LearnerClassifXgboost}
}
\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 scores are taken from the final boosting round \code{nrounds}.}

    \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"}.}

    \item{\code{model}}{(any)\cr
The fitted model. Only available after \verb{$train()} has been called.}
  }
  \if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
  \itemize{
    \item \href{#method-LearnerClassifXgboost-initialize}{\code{LearnerClassifXgboost$new()}}
    \item \href{#method-LearnerClassifXgboost-importance}{\code{LearnerClassifXgboost$importance()}}
    \item \href{#method-LearnerClassifXgboost-clone}{\code{LearnerClassifXgboost$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="configure"><a href='../../mlr3/html/Learner.html#method-Learner-configure'><code>mlr3::Learner$configure()</code></a></span></li>
  <li><span class="pkg-link" data-pkg="mlr3" data-topic="Learner" data-id="encapsulate"><a href='../../mlr3/html/Learner.html#method-Learner-encapsulate'><code>mlr3::Learner$encapsulate()</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="selected_features"><a href='../../mlr3/html/Learner.html#method-Learner-selected_features'><code>mlr3::Learner$selected_features()</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>
  <li><span class="pkg-link" data-pkg="mlr3" data-topic="LearnerClassif" data-id="predict_newdata_fast"><a href='../../mlr3/html/LearnerClassif.html#method-LearnerClassif-predict_newdata_fast'><code>mlr3::LearnerClassif$predict_newdata_fast()</code></a></span></li>
</ul>
</details>}}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-LearnerClassifXgboost-initialize"></a>}}
\if{latex}{\out{\hypertarget{method-LearnerClassifXgboost-initialize}{}}}
\subsection{\code{LearnerClassifXgboost$new()}}{
  Creates a new instance of this \link[R6:R6Class]{R6} class.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{LearnerClassifXgboost$new()}
    \if{html}{\out{</div>}}
  }
}

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

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

}
