lgb.train.R 10.2 KB
Newer Older
James Lamb's avatar
James Lamb committed
1
2
#' @title Main training logic for LightGBM
#' @name lgb.train
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 obj objective function, can be character or custom objective function. Examples include
7
8
#'            \code{regression}, \code{regression_l1}, \code{huber},
#'            \code{binary}, \code{lambdarank}, \code{multiclass}, \code{multiclass}
9
#' @param eval evaluation function, can be (a list of) character or custom eval function
10
#' @param record Boolean, TRUE will record iteration message to \code{booster$record_evals}
Guolin Ke's avatar
Guolin Ke committed
11
#' @param colnames feature names, if not null, will use this to overwrite the names in dataset
12
#' @param categorical_feature list of str or int
13
14
15
16
17
18
#'                            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
19
20
21
22
#' @param ... other parameters, see Parameters.rst for more information. A few key parameters:
#'            \itemize{
#'                \item{boosting}{Boosting type. \code{"gbdt"} or \code{"dart"}}
#'                \item{num_leaves}{number of leaves in one tree. defaults to 127}
23
#'                \item{max_depth}{Limit the max depth for tree model. This is used to deal with
James Lamb's avatar
James Lamb committed
24
25
#'                                 overfit when #data is small. Tree still grow by leaf-wise.}
#'                \item{num_threads}{Number of threads for LightGBM. For the best speed, set this to
26
#'                                   the number of real CPU cores, not the number of threads (most
James Lamb's avatar
James Lamb committed
27
28
#'                                   CPU using hyper-threading to generate 2 threads per CPU core).}
#'            }
29
#' @return a trained booster model \code{lgb.Booster}.
30
#'
Guolin Ke's avatar
Guolin Ke committed
31
#' @examples
32
33
34
35
36
37
38
39
40
#' library(lightgbm)
#' 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)
41
42
43
44
45
46
47
48
49
#' model <- lgb.train(
#'   params = params
#'   , data = dtrain
#'   , nrounds = 10
#'   , valids = valids
#'   , min_data = 1
#'   , learning_rate = 1
#'   , early_stopping_rounds = 5
#' )
Guolin Ke's avatar
Guolin Ke committed
50
#' @export
51
52
53
54
55
56
57
58
59
60
61
62
lgb.train <- function(params = list(),
                      data,
                      nrounds = 10,
                      valids = list(),
                      obj = NULL,
                      eval = NULL,
                      verbose = 1,
                      record = TRUE,
                      eval_freq = 1L,
                      init_model = NULL,
                      colnames = NULL,
                      categorical_feature = NULL,
63
                      early_stopping_rounds = NULL,
64
                      callbacks = list(),
65
                      reset_data = FALSE,
66
                      ...) {
67

68
  # Setup temporary variables
69
  additional_params <- list(...)
70
  params <- append(params, additional_params)
Guolin Ke's avatar
Guolin Ke committed
71
  params$verbose <- verbose
72
73
74
75
  params <- lgb.check.obj(params, obj)
  params <- lgb.check.eval(params, eval)
  fobj <- NULL
  feval <- NULL
76

77
78
79
  if (nrounds <= 0) {
    stop("nrounds should be greater than zero")
  }
80

81
  # Check for objective (function or not)
82
  if (is.function(params$objective)) {
83
    fobj <- params$objective
Guolin Ke's avatar
Guolin Ke committed
84
85
    params$objective <- "NONE"
  }
86

87
88
89
90
  # Check for loss (function or not)
  if (is.function(eval)) {
    feval <- eval
  }
91

92
  # Check for parameters
Guolin Ke's avatar
Guolin Ke committed
93
  lgb.check.params(params)
94

95
  # Init predictor to empty
Guolin Ke's avatar
Guolin Ke committed
96
  predictor <- NULL
97

98
  # Check for boosting from a trained model
99
  if (is.character(init_model)) {
Guolin Ke's avatar
Guolin Ke committed
100
    predictor <- Predictor$new(init_model)
101
  } else if (lgb.is.Booster(init_model)) {
Guolin Ke's avatar
Guolin Ke committed
102
103
    predictor <- init_model$to_predictor()
  }
104

105
  # Set the iteration to start from / end to (and check for boosting from a trained model, again)
Guolin Ke's avatar
Guolin Ke committed
106
  begin_iteration <- 1
107
  if (!is.null(predictor)) {
Guolin Ke's avatar
Guolin Ke committed
108
109
    begin_iteration <- predictor$current_iter() + 1
  }
110
  # Check for number of rounds passed as parameter - in case there are multiple ones, take only the first one
111
112
113
114
115
116
117
118
119
120
121
  n_rounds <- c(
    "num_iterations"
    , "num_iteration"
    , "n_iter"
    , "num_tree"
    , "num_trees"
    , "num_round"
    , "num_rounds"
    , "num_boost_round"
    , "n_estimators"
  )
122
123
  if (any(names(params) %in% n_rounds)) {
    end_iteration <- begin_iteration + params[[which(names(params) %in% n_rounds)[1]]] - 1
124
125
126
  } else {
    end_iteration <- begin_iteration + nrounds - 1
  }
127
128


129
  # Check for training dataset type correctness
130
  if (!lgb.is.Dataset(data)) {
Guolin Ke's avatar
Guolin Ke committed
131
132
    stop("lgb.train: data only accepts lgb.Dataset object")
  }
133

134
  # Check for validation dataset type correctness
Guolin Ke's avatar
Guolin Ke committed
135
  if (length(valids) > 0) {
136

137
    # One or more validation dataset
138

139
    # Check for list as input and type correctness by object
140
    if (!is.list(valids) || !all(vapply(valids, lgb.is.Dataset, logical(1)))) {
141
142
      stop("lgb.train: valids must be a list of lgb.Dataset elements")
    }
143

144
    # Attempt to get names
Guolin Ke's avatar
Guolin Ke committed
145
    evnames <- names(valids)
146

147
    # Check for names existance
148
149
150
    if (is.null(evnames) || !all(nzchar(evnames))) {
      stop("lgb.train: each element of the valids must have a name tag")
    }
Guolin Ke's avatar
Guolin Ke committed
151
  }
152

153
  # Update parameters with parsed parameters
Guolin Ke's avatar
Guolin Ke committed
154
  data$update_params(params)
155

156
  # Create the predictor set
Guolin Ke's avatar
Guolin Ke committed
157
  data$.__enclos_env__$private$set_predictor(predictor)
158

159
160
161
162
  # Write column names
  if (!is.null(colnames)) {
    data$set_colnames(colnames)
  }
163

164
165
166
167
  # Write categorical features
  if (!is.null(categorical_feature)) {
    data$set_categorical_feature(categorical_feature)
  }
168

169
  # Construct datasets, if needed
170
  data$construct()
Guolin Ke's avatar
Guolin Ke committed
171
  vaild_contain_train <- FALSE
172
173
  train_data_name <- "train"
  reduced_valid_sets <- list()
174

175
  # Parse validation datasets
176
  if (length(valids) > 0) {
177

178
    # Loop through all validation datasets using name
Guolin Ke's avatar
Guolin Ke committed
179
    for (key in names(valids)) {
180

181
      # Use names to get validation datasets
Guolin Ke's avatar
Guolin Ke committed
182
      valid_data <- valids[[key]]
183

184
      # Check for duplicate train/validation dataset
185
      if (identical(data, valid_data)) {
Guolin Ke's avatar
Guolin Ke committed
186
        vaild_contain_train <- TRUE
187
        train_data_name <- key
Guolin Ke's avatar
Guolin Ke committed
188
189
        next
      }
190

191
      # Update parameters, data
Guolin Ke's avatar
Guolin Ke committed
192
193
194
      valid_data$update_params(params)
      valid_data$set_reference(data)
      reduced_valid_sets[[key]] <- valid_data
195

Guolin Ke's avatar
Guolin Ke committed
196
    }
197

Guolin Ke's avatar
Guolin Ke committed
198
  }
199

200
  # Add printing log callback
201
  if (verbose > 0 && eval_freq > 0) {
Guolin Ke's avatar
Guolin Ke committed
202
203
    callbacks <- add.cb(callbacks, cb.print.evaluation(eval_freq))
  }
204

205
  # Add evaluation log callback
206
  if (record && length(valids) > 0) {
Guolin Ke's avatar
Guolin Ke committed
207
208
    callbacks <- add.cb(callbacks, cb.record.evaluation())
  }
209

210
  # Check for early stopping passed as parameter when adding early stopping callback
211
  early_stop <- c("early_stopping_round", "early_stopping_rounds", "early_stopping", "n_iter_no_change")
212
213
  if (any(names(params) %in% early_stop)) {
    if (params[[which(names(params) %in% early_stop)[1]]] > 0) {
214
215
216
217
218
219
220
      callbacks <- add.cb(
        callbacks
        , cb.early.stop(
          params[[which(names(params) %in% early_stop)[1]]]
          , verbose = verbose
        )
      )
221
222
223
224
    }
  } else {
    if (!is.null(early_stopping_rounds)) {
      if (early_stopping_rounds > 0) {
225
226
227
228
229
230
231
        callbacks <- add.cb(
          callbacks
          , cb.early.stop(
            early_stopping_rounds
            , verbose = verbose
          )
        )
232
      }
Guolin Ke's avatar
Guolin Ke committed
233
234
    }
  }
235

236
  # "Categorize" callbacks
Guolin Ke's avatar
Guolin Ke committed
237
  cb <- categorize.callbacks(callbacks)
238

239
  # Construct booster with datasets
240
241
  booster <- Booster$new(params = params, train_set = data)
  if (vaild_contain_train) { booster$set_train_data_name(train_data_name) }
Guolin Ke's avatar
Guolin Ke committed
242
243
244
  for (key in names(reduced_valid_sets)) {
    booster$add_valid(reduced_valid_sets[[key]], key)
  }
245

246
247
248
  # Callback env
  env <- CB_ENV$new()
  env$model <- booster
Guolin Ke's avatar
Guolin Ke committed
249
  env$begin_iteration <- begin_iteration
250
  env$end_iteration <- end_iteration
251

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

255
    # Overwrite iteration in environment
Guolin Ke's avatar
Guolin Ke committed
256
257
    env$iteration <- i
    env$eval_list <- list()
258

259
260
261
262
    # Loop through "pre_iter" element
    for (f in cb$pre_iter) {
      f(env)
    }
263

264
    # Update one boosting iteration
265
    booster$update(fobj = fobj)
266

267
    # Prepare collection of evaluation results
Guolin Ke's avatar
Guolin Ke committed
268
    eval_list <- list()
269

270
    # Collection: Has validation dataset?
271
    if (length(valids) > 0) {
272

273
      # Validation has training dataset?
274
275
      if (vaild_contain_train) {
        eval_list <- append(eval_list, booster$eval_train(feval = feval))
Guolin Ke's avatar
Guolin Ke committed
276
      }
277

278
      # Has no validation dataset
279
      eval_list <- append(eval_list, booster$eval_valid(feval = feval))
Guolin Ke's avatar
Guolin Ke committed
280
    }
281

282
    # Write evaluation result in environment
Guolin Ke's avatar
Guolin Ke committed
283
    env$eval_list <- eval_list
284

285
286
287
288
    # Loop through env
    for (f in cb$post_iter) {
      f(env)
    }
289

290
    # Check for early stopping and break if needed
291
    if (env$met_early_stop) break
292

Guolin Ke's avatar
Guolin Ke committed
293
  }
294

295
296
  # When early stopping is not activated, we compute the best iteration / score ourselves by
  # selecting the first metric and the first dataset
297
298
299
300
301
302
303
304
305
  if (record && length(valids) > 0 && is.na(env$best_score)) {
    if (env$eval_list[[1]]$higher_better[1] == TRUE) {
      booster$best_iter <- unname(which.max(unlist(booster$record_evals[[2]][[1]][[1]])))
      booster$best_score <- booster$record_evals[[2]][[1]][[1]][[booster$best_iter]]
    } else {
      booster$best_iter <- unname(which.min(unlist(booster$record_evals[[2]][[1]][[1]])))
      booster$best_score <- booster$record_evals[[2]][[1]][[1]][[booster$best_iter]]
    }
  }
306

307
308
  # Check for booster model conversion to predictor model
  if (reset_data) {
309

310
    # Store temporarily model data elsewhere
311
312
313
314
315
    booster_old <- list(
      best_iter = booster$best_iter
      , best_score = booster$best_score
      , record_evals = booster$record_evals
    )
316

317
318
319
320
321
    # 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
322

323
  }
324

325
326
  # Return booster
  return(booster)
327

Guolin Ke's avatar
Guolin Ke committed
328
}