lightgbm.R 8.25 KB
Newer Older
James Lamb's avatar
James Lamb committed
1
2
3
#' @name lgb_shared_params
#' @title Shared parameter docs
#' @description Parameter docs shared by \code{lgb.train}, \code{lgb.cv}, and \code{lightgbm}
4
5
6
7
8
#' @param callbacks list of callback functions
#'        List of callback functions that are applied at each iteration.
#' @param 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.
9
10
11
12
#' @param early_stopping_rounds int. Activates early stopping. Requires at least one validation data
#'                              and one metric. If there's more than one, will check all of them
#'                              except the training data. Returns the model with (best_iter + early_stopping_rounds).
#'                              If early stopping occurs, the model will have 'best_iter' field.
James Lamb's avatar
James Lamb committed
13
14
15
16
17
#' @param eval_freq evaluation output frequency, only effect when verbose > 0
#' @param init_model path of model file of \code{lgb.Booster} object, will continue training from this model
#' @param nrounds number of training rounds
#' @param params List of parameters
#' @param verbose verbosity for output, if <= 0, also will disable the print of evaluation during training
18
#' @keywords internal
James Lamb's avatar
James Lamb committed
19
20
21
NULL

#' @name lightgbm
22
#' @title Train a LightGBM model
23
#' @description Simple interface for training a LightGBM model.
James Lamb's avatar
James Lamb committed
24
25
26
27
28
29
#' @inheritParams lgb_shared_params
#' @param label Vector of labels, used if \code{data} is not an \code{\link{lgb.Dataset}}
#' @param weight vector of response values. If not NULL, will set to dataset
#' @param save_name File name to use when writing the trained model to disk. Should end in ".model".
#' @param ... Additional arguments passed to \code{\link{lgb.train}}. For example
#'     \itemize{
30
31
#'        \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
32
33
#'                   \code{regression}, \code{regression_l1}, \code{huber},
#'                    \code{binary}, \code{lambdarank}, \code{multiclass}, \code{multiclass}}
34
35
36
37
38
39
40
#'        \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
41
#'                          into a predictor model which frees up memory and the original datasets}
42
43
44
#'         \item{\code{boosting}: Boosting type. \code{"gbdt"}, \code{"rf"}, \code{"dart"} or \code{"goss"}.}
#'         \item{\code{num_leaves}: Maximum number of leaves in one tree.}
#'         \item{\code{max_depth}: Limit the max depth for tree model. This is used to deal with
James Lamb's avatar
James Lamb committed
45
#'                          overfit when #data is small. Tree still grow by leaf-wise.}
46
#'          \item{\code{num_threads}: Number of threads for LightGBM. For the best speed, set this to
47
#'                             the number of real CPU cores, not the number of threads (most
James Lamb's avatar
James Lamb committed
48
49
#'                             CPU using hyper-threading to generate 2 threads per CPU core).}
#'     }
Guolin Ke's avatar
Guolin Ke committed
50
#' @export
51
52
53
54
lightgbm <- function(data,
                     label = NULL,
                     weight = NULL,
                     params = list(),
55
56
                     nrounds = 10L,
                     verbose = 1L,
57
58
59
60
61
62
                     eval_freq = 1L,
                     early_stopping_rounds = NULL,
                     save_name = "lightgbm.model",
                     init_model = NULL,
                     callbacks = list(),
                     ...) {
63

64
  # validate inputs early to avoid unnecessary computation
65
  if (nrounds <= 0L) {
66
67
    stop("nrounds should be greater than zero")
  }
68
69
70
71

  # Set data to a temporary variable
  dtrain <- data

72
  # Check whether data is lgb.Dataset, if not then create lgb.Dataset manually
73
74
  if (!lgb.is.Dataset(dtrain)) {
    dtrain <- lgb.Dataset(data, label = label, weight = weight)
Guolin Ke's avatar
Guolin Ke committed
75
  }
Guolin Ke's avatar
Guolin Ke committed
76

77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
  train_args <- list(
    "params" = params
    , "data" = dtrain
    , "nrounds" = nrounds
    , "verbose" = verbose
    , "eval_freq" = eval_freq
    , "early_stopping_rounds" = early_stopping_rounds
    , "init_model" = init_model
    , "callbacks" = callbacks
  )
  train_args <- append(train_args, list(...))

  if (! "valids" %in% names(train_args)) {
    train_args[["valids"]] <- list()
  }

93
  # Set validation as oneself
94
  if (verbose > 0L) {
95
    train_args[["valids"]][["train"]] <- dtrain
96
  }
97

98
  # Train a model using the regular way
99
100
101
  bst <- do.call(
    what = lgb.train
    , args = train_args
102
  )
103

104
  # Store model under a specific name
Guolin Ke's avatar
Guolin Ke committed
105
  bst$save_model(save_name)
106

107
108
  # Return booster
  return(bst)
Guolin Ke's avatar
Guolin Ke committed
109
110
}

111
112
113
114
115
#' @name agaricus.train
#' @title Training part from Mushroom Data Set
#' @description This data set is originally from the Mushroom data set,
#'              UCI Machine Learning Repository.
#'              This data set includes the following fields:
116
#'
117
118
119
120
#'               \itemize{
#'                   \item{\code{label}: the label for each record}
#'                   \item{\code{data}: a sparse Matrix of \code{dgCMatrix} class, with 126 columns.}
#'                }
Guolin Ke's avatar
Guolin Ke committed
121
122
123
#'
#' @references
#' https://archive.ics.uci.edu/ml/datasets/Mushroom
124
125
126
#'
#' Bache, K. & Lichman, M. (2013). UCI Machine Learning Repository
#' [http://archive.ics.uci.edu/ml]. Irvine, CA: University of California,
Guolin Ke's avatar
Guolin Ke committed
127
#' School of Information and Computer Science.
128
#'
Guolin Ke's avatar
Guolin Ke committed
129
130
131
#' @docType data
#' @keywords datasets
#' @usage data(agaricus.train)
132
#' @format A list containing a label vector, and a dgCMatrix object with 6513
Guolin Ke's avatar
Guolin Ke committed
133
134
135
#' rows and 127 variables
NULL

136
137
138
139
140
141
142
143
144
145
#' @name agaricus.test
#' @title Test part from Mushroom Data Set
#' @description This data set is originally from the Mushroom data set,
#'              UCI Machine Learning Repository.
#'              This data set includes the following fields:
#'
#'              \itemize{
#'                  \item{\code{label}: the label for each record}
#'                  \item{\code{data}: a sparse Matrix of \code{dgCMatrix} class, with 126 columns.}
#'              }
Guolin Ke's avatar
Guolin Ke committed
146
147
#' @references
#' https://archive.ics.uci.edu/ml/datasets/Mushroom
148
149
150
#'
#' Bache, K. & Lichman, M. (2013). UCI Machine Learning Repository
#' [http://archive.ics.uci.edu/ml]. Irvine, CA: University of California,
Guolin Ke's avatar
Guolin Ke committed
151
#' School of Information and Computer Science.
152
#'
Guolin Ke's avatar
Guolin Ke committed
153
154
155
#' @docType data
#' @keywords datasets
#' @usage data(agaricus.test)
156
#' @format A list containing a label vector, and a dgCMatrix object with 1611
Guolin Ke's avatar
Guolin Ke committed
157
158
159
#' rows and 126 variables
NULL

160
161
162
163
#' @name bank
#' @title Bank Marketing Data Set
#' @description This data set is originally from the Bank Marketing data set,
#'              UCI Machine Learning Repository.
164
#'
165
166
#'              It contains only the following: bank.csv with 10% of the examples and 17 inputs,
#'              randomly selected from 3 (older version of this dataset with less inputs).
167
168
169
#'
#' @references
#' http://archive.ics.uci.edu/ml/datasets/Bank+Marketing
170
#'
171
172
173
174
175
176
177
178
179
#' S. Moro, P. Cortez and P. Rita. (2014)
#' A Data-Driven Approach to Predict the Success of Bank Telemarketing. Decision Support Systems
#'
#' @docType data
#' @keywords datasets
#' @usage data(bank)
#' @format A data.table with 4521 rows and 17 variables
NULL

Guolin Ke's avatar
Guolin Ke committed
180
# Various imports
Guolin Ke's avatar
Guolin Ke committed
181
#' @import methods
182
#' @importFrom Matrix Matrix
Guolin Ke's avatar
Guolin Ke committed
183
#' @importFrom R6 R6Class
James Lamb's avatar
James Lamb committed
184
#' @useDynLib lib_lightgbm , .registration = TRUE
185
NULL
James Lamb's avatar
James Lamb committed
186
187
188
189
190
191
192

# Suppress false positive warnings from R CMD CHECK about
# "unrecognized global variable"
globalVariables(c(
    "."
    , ".N"
    , ".SD"
193
    , "abs_contribution"
194
    , "bar_color"
James Lamb's avatar
James Lamb committed
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
    , "Contribution"
    , "Cover"
    , "Feature"
    , "Frequency"
    , "Gain"
    , "internal_count"
    , "internal_value"
    , "leaf_index"
    , "leaf_parent"
    , "leaf_value"
    , "node_parent"
    , "split_feature"
    , "split_gain"
    , "split_index"
    , "tree_index"
))