lightgbm.Rd 4.11 KB
Newer Older
James Lamb's avatar
James Lamb committed
1
2
3
4
5
6
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lightgbm.R
\name{lightgbm}
\alias{lightgbm}
\title{Train a LightGBM model}
\usage{
7
8
9
10
11
lightgbm(
  data,
  label = NULL,
  weight = NULL,
  params = list(),
12
  nrounds = 100L,
13
  verbose = 1L,
14
15
16
17
  eval_freq = 1L,
  early_stopping_rounds = NULL,
  init_model = NULL,
  callbacks = list(),
18
  serializable = TRUE,
19
20
  ...
)
James Lamb's avatar
James Lamb committed
21
22
}
\arguments{
23
24
25
\item{data}{a \code{lgb.Dataset} object, used for training. Some functions, such as \code{\link{lgb.cv}},
may allow you to pass other types of data like \code{matrix} and then separately supply
\code{label} as a keyword argument.}
James Lamb's avatar
James Lamb committed
26
27
28
29
30

\item{label}{Vector of labels, used if \code{data} is not an \code{\link{lgb.Dataset}}}

\item{weight}{vector of response values. If not NULL, will set to dataset}

31
32
\item{params}{a list of parameters. See \href{https://lightgbm.readthedocs.io/en/latest/Parameters.html}{
the "Parameters" section of the documentation} for a list of parameters and valid values.}
James Lamb's avatar
James Lamb committed
33
34
35
36
37
38
39

\item{nrounds}{number of training rounds}

\item{verbose}{verbosity for output, if <= 0, also will disable the print of evaluation during training}

\item{eval_freq}{evaluation output frequency, only effect when verbose > 0}

40
41
42
43
44
\item{early_stopping_rounds}{int. Activates early stopping. When this parameter is non-null,
training will stop if the evaluation of any metric on any validation set
fails to improve for \code{early_stopping_rounds} consecutive boosting rounds.
If training stops early, the returned model will have attribute \code{best_iter}
set to the iteration number of the best iteration.}
James Lamb's avatar
James Lamb committed
45
46
47

\item{init_model}{path of model file of \code{lgb.Booster} object, will continue training from this model}

48
\item{callbacks}{List of callback functions that are applied at each iteration.}
James Lamb's avatar
James Lamb committed
49

50
51
52
\item{serializable}{whether to make the resulting objects serializable through functions such as
\code{save} or \code{saveRDS} (see section "Model serialization").}

James Lamb's avatar
James Lamb committed
53
54
\item{...}{Additional arguments passed to \code{\link{lgb.train}}. For example
\itemize{
55
56
   \item{\code{valids}: a list of \code{lgb.Dataset} objects, used for validation}
   \item{\code{obj}: objective function, can be character or custom objective function. Examples include
James Lamb's avatar
James Lamb committed
57
58
              \code{regression}, \code{regression_l1}, \code{huber},
               \code{binary}, \code{lambdarank}, \code{multiclass}, \code{multiclass}}
59
60
61
62
63
64
65
   \item{\code{eval}: evaluation function, can be (a list of) character or custom eval function}
   \item{\code{record}: Boolean, TRUE will record iteration message to \code{booster$record_evals}}
   \item{\code{colnames}: feature names, if not null, will use this to overwrite the names in dataset}
   \item{\code{categorical_feature}: categorical features. This can either be a character vector of feature
                       names or an integer vector with the indices of the features (e.g. \code{c(1L, 10L)} to
                       say "the first and tenth columns").}
   \item{\code{reset_data}: Boolean, setting it to TRUE (not the default value) will transform the booster model
James Lamb's avatar
James Lamb committed
66
67
68
                     into a predictor model which frees up memory and the original datasets}
}}
}
69
70
71
\value{
a trained \code{lgb.Booster}
}
James Lamb's avatar
James Lamb committed
72
\description{
73
Simple interface for training a LightGBM model.
James Lamb's avatar
James Lamb committed
74
}
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
\section{Early Stopping}{


         "early stopping" refers to stopping the training process if the model's performance on a given
         validation set does not improve for several consecutive iterations.

         If multiple arguments are given to \code{eval}, their order will be preserved. If you enable
         early stopping by setting \code{early_stopping_rounds} in \code{params}, by default all
         metrics will be considered for early stopping.

         If you want to only consider the first metric for early stopping, pass
         \code{first_metric_only = TRUE} in \code{params}. Note that if you also specify \code{metric}
         in \code{params}, that metric will be considered the "first" one. If you omit \code{metric},
         a default metric will be used based on your choice for the parameter \code{obj} (keyword argument)
         or \code{objective} (passed into \code{params}).
}