lgb.train.R 12.2 KB
Newer Older
James Lamb's avatar
James Lamb committed
1
#' @name lgb.train
2
#' @title Main training logic for LightGBM
James Lamb's avatar
James Lamb committed
3
4
#' @description Logic to train with LightGBM
#' @inheritParams lgb_shared_params
5
#' @param valids a list of \code{lgb.Dataset} objects, used for validation
6
#' @param record Boolean, TRUE will record iteration message to \code{booster$record_evals}
Guolin Ke's avatar
Guolin Ke committed
7
#' @param colnames feature names, if not null, will use this to overwrite the names in dataset
8
#' @param categorical_feature list of str or int
9
10
11
12
13
14
#'                            type int represents index,
#'                            type str represents feature names
#' @param callbacks List of callback functions that are applied at each iteration.
#' @param reset_data Boolean, setting it to TRUE (not the default value) will transform the
#'                   booster model into a predictor model which frees up memory and the
#'                   original datasets
James Lamb's avatar
James Lamb committed
15
16
#' @param ... other parameters, see Parameters.rst for more information. A few key parameters:
#'            \itemize{
17
18
19
#'                \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
20
#'                                 overfit when #data is small. Tree still grow by leaf-wise.}
21
#'                \item{\code{num_threads}: Number of threads for LightGBM. For the best speed, set this to
22
#'                                   the number of real CPU cores, not the number of threads (most
James Lamb's avatar
James Lamb committed
23
24
#'                                   CPU using hyper-threading to generate 2 threads per CPU core).}
#'            }
25
#' @inheritSection lgb_shared_params Early Stopping
26
#' @return a trained booster model \code{lgb.Booster}.
27
#'
Guolin Ke's avatar
Guolin Ke committed
28
#' @examples
29
#' \dontrun{
30
31
32
33
34
35
36
37
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' data(agaricus.test, package = "lightgbm")
#' test <- agaricus.test
#' dtest <- lgb.Dataset.create.valid(dtrain, test$data, label = test$label)
#' params <- list(objective = "regression", metric = "l2")
#' valids <- list(test = dtest)
38
39
40
#' model <- lgb.train(
#'   params = params
#'   , data = dtrain
41
#'   , nrounds = 5L
42
#'   , valids = valids
43
44
#'   , min_data = 1L
#'   , learning_rate = 1.0
45
#'   , early_stopping_rounds = 3L
46
#' )
47
#' }
Guolin Ke's avatar
Guolin Ke committed
48
#' @export
49
50
lgb.train <- function(params = list(),
                      data,
51
                      nrounds = 10L,
52
53
54
                      valids = list(),
                      obj = NULL,
                      eval = NULL,
55
                      verbose = 1L,
56
57
58
59
60
                      record = TRUE,
                      eval_freq = 1L,
                      init_model = NULL,
                      colnames = NULL,
                      categorical_feature = NULL,
61
                      early_stopping_rounds = NULL,
62
                      callbacks = list(),
63
                      reset_data = FALSE,
64
                      ...) {
65

66
67
68
69
70
71
72
73
  # validate inputs early to avoid unnecessary computation
  if (nrounds <= 0L) {
    stop("nrounds should be greater than zero")
  }
  if (!lgb.is.Dataset(data)) {
    stop("lgb.train: data must be an lgb.Dataset instance")
  }
  if (length(valids) > 0L) {
74
    if (!identical(class(valids), "list") || !all(vapply(valids, lgb.is.Dataset, logical(1L)))) {
75
76
77
78
79
80
81
82
      stop("lgb.train: valids must be a list of lgb.Dataset elements")
    }
    evnames <- names(valids)
    if (is.null(evnames) || !all(nzchar(evnames))) {
      stop("lgb.train: each element of valids must have a name")
    }
  }

83
  # Setup temporary variables
84
  additional_params <- list(...)
85
  params <- append(params, additional_params)
Guolin Ke's avatar
Guolin Ke committed
86
  params$verbose <- verbose
87
88
89
  params <- lgb.check.obj(params, obj)
  params <- lgb.check.eval(params, eval)
  fobj <- NULL
90
  eval_functions <- list(NULL)
91

92
  # Check for objective (function or not)
93
  if (is.function(params$objective)) {
94
    fobj <- params$objective
Guolin Ke's avatar
Guolin Ke committed
95
96
    params$objective <- "NONE"
  }
97

98
  # If eval is a single function, store it as a 1-element list
99
  # (for backwards compatibility). If it is a list of functions, store
100
101
  # all of them. This makes it possible to pass any mix of strings like "auc"
  # and custom functions to eval
102
  if (is.function(eval)) {
103
104
105
106
107
108
109
    eval_functions <- list(eval)
  }
  if (methods::is(eval, "list")) {
    eval_functions <- Filter(
      f = is.function
      , x = eval
    )
110
  }
111

112
  # Init predictor to empty
Guolin Ke's avatar
Guolin Ke committed
113
  predictor <- NULL
114

115
  # Check for boosting from a trained model
116
  if (is.character(init_model)) {
Guolin Ke's avatar
Guolin Ke committed
117
    predictor <- Predictor$new(init_model)
118
  } else if (lgb.is.Booster(init_model)) {
Guolin Ke's avatar
Guolin Ke committed
119
120
    predictor <- init_model$to_predictor()
  }
121

122
  # Set the iteration to start from / end to (and check for boosting from a trained model, again)
123
  begin_iteration <- 1L
124
  if (!is.null(predictor)) {
125
    begin_iteration <- predictor$current_iter() + 1L
Guolin Ke's avatar
Guolin Ke committed
126
  }
127
  # Check for number of rounds passed as parameter - in case there are multiple ones, take only the first one
128
129
  n_trees <- .PARAMETER_ALIASES()[["num_iterations"]]
  if (any(names(params) %in% n_trees)) {
130
    end_iteration <- begin_iteration + params[[which(names(params) %in% n_trees)[1L]]] - 1L
131
  } else {
132
    end_iteration <- begin_iteration + nrounds - 1L
133
  }
134

135
136
137
138
139
140
  # Check interaction constraints
  cnames <- NULL
  if (!is.null(colnames)) {
    cnames <- colnames
  } else if (!is.null(data$get_colnames())) {
    cnames <- data$get_colnames()
141
  }
142
  params[["interaction_constraints"]] <- lgb.check_interaction_constraints(params, cnames)
143

144
  # Update parameters with parsed parameters
Guolin Ke's avatar
Guolin Ke committed
145
  data$update_params(params)
146

147
  # Create the predictor set
Guolin Ke's avatar
Guolin Ke committed
148
  data$.__enclos_env__$private$set_predictor(predictor)
149

150
151
152
153
  # Write column names
  if (!is.null(colnames)) {
    data$set_colnames(colnames)
  }
154

155
156
157
158
  # Write categorical features
  if (!is.null(categorical_feature)) {
    data$set_categorical_feature(categorical_feature)
  }
159

160
  # Construct datasets, if needed
161
  data$construct()
162
  valid_contain_train <- FALSE
163
164
  train_data_name <- "train"
  reduced_valid_sets <- list()
165

166
  # Parse validation datasets
167
  if (length(valids) > 0L) {
168

169
    # Loop through all validation datasets using name
Guolin Ke's avatar
Guolin Ke committed
170
    for (key in names(valids)) {
171

172
      # Use names to get validation datasets
Guolin Ke's avatar
Guolin Ke committed
173
      valid_data <- valids[[key]]
174

175
      # Check for duplicate train/validation dataset
176
      if (identical(data, valid_data)) {
177
        valid_contain_train <- TRUE
178
        train_data_name <- key
Guolin Ke's avatar
Guolin Ke committed
179
180
        next
      }
181

182
      # Update parameters, data
Guolin Ke's avatar
Guolin Ke committed
183
184
185
      valid_data$update_params(params)
      valid_data$set_reference(data)
      reduced_valid_sets[[key]] <- valid_data
186

Guolin Ke's avatar
Guolin Ke committed
187
    }
188

Guolin Ke's avatar
Guolin Ke committed
189
  }
190

191
  # Add printing log callback
192
  if (verbose > 0L && eval_freq > 0L) {
Guolin Ke's avatar
Guolin Ke committed
193
194
    callbacks <- add.cb(callbacks, cb.print.evaluation(eval_freq))
  }
195

196
  # Add evaluation log callback
197
  if (record && length(valids) > 0L) {
Guolin Ke's avatar
Guolin Ke committed
198
199
    callbacks <- add.cb(callbacks, cb.record.evaluation())
  }
200

201
202
203
204
205
  # If early stopping was passed as a parameter in params(), prefer that to keyword argument
  # early_stopping_rounds by overwriting the value in 'early_stopping_rounds'
  early_stop <- .PARAMETER_ALIASES()[["early_stopping_round"]]
  early_stop_param_indx <- names(params) %in% early_stop
  if (any(early_stop_param_indx)) {
206
    first_early_stop_param <- which(early_stop_param_indx)[[1L]]
207
208
209
210
211
    first_early_stop_param_name <- names(params)[[first_early_stop_param]]
    early_stopping_rounds <- params[[first_early_stop_param_name]]
  }

  # Did user pass parameters that indicate they want to use early stopping?
212
  using_early_stopping_via_args <- !is.null(early_stopping_rounds) && early_stopping_rounds > 0L
213
214
215
216
217

  boosting_param_names <- .PARAMETER_ALIASES()[["boosting"]]
  using_dart <- any(
    sapply(
      X = boosting_param_names
218
219
      , FUN = function(param) {
        identical(params[[param]], "dart")
220
      }
221
222
223
224
    )
  )

  # Cannot use early stopping with 'dart' boosting
225
  if (using_dart) {
226
227
228
229
230
    warning("Early stopping is not available in 'dart' mode.")
    using_early_stopping_via_args <- FALSE

    # Remove the cb.early.stop() function if it was passed in to callbacks
    callbacks <- Filter(
231
      f = function(cb_func) {
232
233
234
235
236
237
238
        !identical(attr(cb_func, "name"), "cb.early.stop")
      }
      , x = callbacks
    )
  }

  # If user supplied early_stopping_rounds, add the early stopping callback
239
  if (using_early_stopping_via_args) {
240
241
242
243
    callbacks <- add.cb(
      callbacks
      , cb.early.stop(
        stopping_rounds = early_stopping_rounds
244
        , first_metric_only = isTRUE(params[["first_metric_only"]])
245
246
247
        , verbose = verbose
      )
    )
Guolin Ke's avatar
Guolin Ke committed
248
  }
249

Guolin Ke's avatar
Guolin Ke committed
250
  cb <- categorize.callbacks(callbacks)
251

252
  # Construct booster with datasets
253
  booster <- Booster$new(params = params, train_set = data)
254
255
256
  if (valid_contain_train) {
    booster$set_train_data_name(train_data_name)
  }
257

Guolin Ke's avatar
Guolin Ke committed
258
259
260
  for (key in names(reduced_valid_sets)) {
    booster$add_valid(reduced_valid_sets[[key]], key)
  }
261

262
263
264
  # Callback env
  env <- CB_ENV$new()
  env$model <- booster
Guolin Ke's avatar
Guolin Ke committed
265
  env$begin_iteration <- begin_iteration
266
  env$end_iteration <- end_iteration
267

268
  # Start training model using number of iterations to start and end with
269
  for (i in seq.int(from = begin_iteration, to = end_iteration)) {
270

271
    # Overwrite iteration in environment
Guolin Ke's avatar
Guolin Ke committed
272
273
    env$iteration <- i
    env$eval_list <- list()
274

275
276
277
278
    # Loop through "pre_iter" element
    for (f in cb$pre_iter) {
      f(env)
    }
279

280
    # Update one boosting iteration
281
    booster$update(fobj = fobj)
282

283
    # Prepare collection of evaluation results
Guolin Ke's avatar
Guolin Ke committed
284
    eval_list <- list()
285

286
    # Collection: Has validation dataset?
287
    if (length(valids) > 0L) {
288

289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
      # Get evaluation results with passed-in functions
      for (eval_function in eval_functions) {

        # Validation has training dataset?
        if (valid_contain_train) {
          eval_list <- append(eval_list, booster$eval_train(feval = eval_function))
        }

        eval_list <- append(eval_list, booster$eval_valid(feval = eval_function))
      }

      # Calling booster$eval_valid() will get
      # evaluation results with the metrics in params$metric by calling LGBM_BoosterGetEval_R",
      # so need to be sure that gets called, which it wouldn't be above if no functions
      # were passed in
      if (length(eval_functions) == 0L) {
        if (valid_contain_train) {
          eval_list <- append(eval_list, booster$eval_train(feval = eval_function))
        }
        eval_list <- append(eval_list, booster$eval_valid(feval = eval_function))
Guolin Ke's avatar
Guolin Ke committed
309
      }
310

Guolin Ke's avatar
Guolin Ke committed
311
    }
312

313
    # Write evaluation result in environment
Guolin Ke's avatar
Guolin Ke committed
314
    env$eval_list <- eval_list
315

316
317
318
319
    # Loop through env
    for (f in cb$post_iter) {
      f(env)
    }
320

321
    # Check for early stopping and break if needed
322
    if (env$met_early_stop) break
323

Guolin Ke's avatar
Guolin Ke committed
324
  }
325

326
327
328
329
  # check if any valids were given other than the training data
  non_train_valid_names <- names(valids)[!(names(valids) == train_data_name)]
  first_valid_name <- non_train_valid_names[1L]

330
331
  # When early stopping is not activated, we compute the best iteration / score ourselves by
  # selecting the first metric and the first dataset
332
  if (record && length(non_train_valid_names) > 0L && is.na(env$best_score)) {
333
334
335

    # when using a custom eval function, the metric name is returned from the
    # function, so figure it out from record_evals
336
    if (!is.null(eval_functions[1L])) {
337
338
339
340
341
      first_metric <- names(booster$record_evals[[first_valid_name]])[1L]
    } else {
      first_metric <- booster$.__enclos_env__$private$eval_names[1L]
    }

342
343
344
    .find_best <- which.min
    if (isTRUE(env$eval_list[[1L]]$higher_better[1L])) {
      .find_best <- which.max
345
    }
346
347
348
349
350
351
352
353
    booster$best_iter <- unname(
      .find_best(
        unlist(
          booster$record_evals[[first_valid_name]][[first_metric]][[.EVAL_KEY()]]
        )
      )
    )
    booster$best_score <- booster$record_evals[[first_valid_name]][[first_metric]][[.EVAL_KEY()]][[booster$best_iter]]
354
  }
355

356
357
  # Check for booster model conversion to predictor model
  if (reset_data) {
358

359
    # Store temporarily model data elsewhere
360
361
362
363
364
    booster_old <- list(
      best_iter = booster$best_iter
      , best_score = booster$best_score
      , record_evals = booster$record_evals
    )
365

366
367
368
369
370
    # Reload model
    booster <- lgb.load(model_str = booster$save_model_to_string())
    booster$best_iter <- booster_old$best_iter
    booster$best_score <- booster_old$best_score
    booster$record_evals <- booster_old$record_evals
371

372
  }
373

374
  return(booster)
375

Guolin Ke's avatar
Guolin Ke committed
376
}