lgb.train.R 10.3 KB
Newer Older
James Lamb's avatar
James Lamb committed
1
2
#' @title Main training logic for LightGBM
#' @name lgb.train
Guolin Ke's avatar
Guolin Ke committed
3
4
5
#' @param params List of parameters
#' @param data a \code{lgb.Dataset} object, used for training
#' @param nrounds number of training rounds
6
#' @param valids a list of \code{lgb.Dataset} objects, used for validation
7
8
9
10
11
12
13
14
#' @param obj objective function, can be character or custom objective function. Examples include 
#'        \code{regression}, \code{regression_l1}, \code{huber},
#'        \code{binary}, \code{lambdarank}, \code{multiclass}, \code{multiclass}
#' @param boosting boosting type. \code{gbdt}, \code{dart}
#' @param num_leaves number of leaves in one tree. defaults to 127
#' @param max_depth Limit the max depth for tree model. This is used to deal with overfit when #data is small. 
#'        Tree still grow by leaf-wise.
#' @param num_threads Number of threads for LightGBM. For the best speed, set this to the number of real CPU cores, not the number of threads (most CPU using hyper-threading to generate 2 threads per CPU core).
15
#' @param eval evaluation function, can be (a list of) character or custom eval function
16
17
18
#' @param verbose verbosity for output, if <= 0, also will disable the print of evalutaion during training
#' @param record Boolean, TRUE will record iteration message to \code{booster$record_evals} 
#' @param eval_freq evalutaion output frequency, only effect when verbose > 0
19
#' @param init_model path of model file of \code{lgb.Booster} object, will continue training from this model
Guolin Ke's avatar
Guolin Ke committed
20
#' @param colnames feature names, if not null, will use this to overwrite the names in dataset
21
22
23
#' @param categorical_feature list of str or int
#'        type int represents index,
#'        type str represents feature names
Guolin Ke's avatar
Guolin Ke committed
24
25
#' @param early_stopping_rounds int
#'        Activates early stopping.
26
27
28
29
30
#'        The model will train until the validation score stops improving.
#'        Validation score needs to improve at least every early_stopping_rounds round(s) to continue training.
#'        Requires at least one validation data and one metric.
#'        If there's more than one, will check all of them. But the training data is ignored anyway.
#'        Returns the model with (best_iter + early_stopping_rounds).
Guolin Ke's avatar
Guolin Ke committed
31
#'        If early stopping occurs, the model will have 'best_iter' field
32
#' @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
Guolin Ke's avatar
Guolin Ke committed
33
34
#' @param callbacks list of callback functions
#'        List of callback functions that are applied at each iteration.
35
#' @param ... other parameters, see Parameters.rst for more information
36
#' 
37
#' @return a trained booster model \code{lgb.Booster}.
38
#' 
Guolin Ke's avatar
Guolin Ke committed
39
#' @examples
40
#' \dontrun{
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
#' 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)
#' model <- lgb.train(params,
#'                    dtrain,
#'                    100,
#'                    valids,
#'                    min_data = 1,
#'                    learning_rate = 1,
#'                    early_stopping_rounds = 10)
57
#' }
58
#' 
Guolin Ke's avatar
Guolin Ke committed
59
#' @rdname lgb.train
60
#' 
Guolin Ke's avatar
Guolin Ke committed
61
#' @export
62
63
64
65
66
67
68
69
70
71
72
73
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,
74
                      early_stopping_rounds = NULL,
75
                      callbacks = list(),
76
                      reset_data = FALSE,
77
78
79
                      ...) {
  
  # Setup temporary variables
80
  additional_params <- list(...)
81
  params <- append(params, additional_params)
Guolin Ke's avatar
Guolin Ke committed
82
  params$verbose <- verbose
83
84
85
86
87
  params <- lgb.check.obj(params, obj)
  params <- lgb.check.eval(params, eval)
  fobj <- NULL
  feval <- NULL
  
88
89
90
91
  if (nrounds <= 0) {
    stop("nrounds should be greater than zero")
  }

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
99
100
101
102
103
  
  # Check for loss (function or not)
  if (is.function(eval)) {
    feval <- eval
  }
  
  # Check for parameters
Guolin Ke's avatar
Guolin Ke committed
104
  lgb.check.params(params)
105
106
  
  # Init predictor to empty
Guolin Ke's avatar
Guolin Ke committed
107
  predictor <- NULL
108
109
  
  # Check for boosting from a trained model
110
  if (is.character(init_model)) {
Guolin Ke's avatar
Guolin Ke committed
111
    predictor <- Predictor$new(init_model)
112
  } else if (lgb.is.Booster(init_model)) {
Guolin Ke's avatar
Guolin Ke committed
113
114
    predictor <- init_model$to_predictor()
  }
115
116
  
  # Set the iteration to start from / end to (and check for boosting from a trained model, again)
Guolin Ke's avatar
Guolin Ke committed
117
  begin_iteration <- 1
118
  if (!is.null(predictor)) {
Guolin Ke's avatar
Guolin Ke committed
119
120
    begin_iteration <- predictor$current_iter() + 1
  }
121
  # Check for number of rounds passed as parameter - in case there are multiple ones, take only the first one
122
  n_rounds <- c("num_iterations", "num_iteration", "n_iter", "num_tree", "num_trees", "num_round", "num_rounds", "num_boost_round", "n_estimators")
123
124
  if (any(names(params) %in% n_rounds)) {
    end_iteration <- begin_iteration + params[[which(names(params) %in% n_rounds)[1]]] - 1
125
126
127
128
  } else {
    end_iteration <- begin_iteration + nrounds - 1
  }
  
129
130
  
  # Check for training dataset type correctness
131
  if (!lgb.is.Dataset(data)) {
Guolin Ke's avatar
Guolin Ke committed
132
133
    stop("lgb.train: data only accepts lgb.Dataset object")
  }
134
135
  
  # Check for validation dataset type correctness
Guolin Ke's avatar
Guolin Ke committed
136
  if (length(valids) > 0) {
137
138
139
140
    
    # One or more validation dataset
    
    # Check for list as input and type correctness by object
141
    if (!is.list(valids) || !all(vapply(valids, lgb.is.Dataset, logical(1)))) {
142
143
      stop("lgb.train: valids must be a list of lgb.Dataset elements")
    }
144
145
    
    # Attempt to get names
Guolin Ke's avatar
Guolin Ke committed
146
    evnames <- names(valids)
147
148
    
    # Check for names existance
149
150
151
    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
152
  }
153
154
  
  # Update parameters with parsed parameters
Guolin Ke's avatar
Guolin Ke committed
155
  data$update_params(params)
156
157
  
  # Create the predictor set
Guolin Ke's avatar
Guolin Ke committed
158
  data$.__enclos_env__$private$set_predictor(predictor)
159
160
161
162
163
164
165
166
167
168
169
170
  
  # Write column names
  if (!is.null(colnames)) {
    data$set_colnames(colnames)
  }
  
  # Write categorical features
  if (!is.null(categorical_feature)) {
    data$set_categorical_feature(categorical_feature)
  }
  
  # Construct datasets, if needed
171
  data$construct()
Guolin Ke's avatar
Guolin Ke committed
172
  vaild_contain_train <- FALSE
173
174
175
176
  train_data_name <- "train"
  reduced_valid_sets <- list()
  
  # Parse validation datasets
177
  if (length(valids) > 0) {
178
179
    
    # Loop through all validation datasets using name
Guolin Ke's avatar
Guolin Ke committed
180
    for (key in names(valids)) {
181
182
      
      # Use names to get validation datasets
Guolin Ke's avatar
Guolin Ke committed
183
      valid_data <- valids[[key]]
184
185
      
      # Check for duplicate train/validation dataset
186
      if (identical(data, valid_data)) {
Guolin Ke's avatar
Guolin Ke committed
187
        vaild_contain_train <- TRUE
188
        train_data_name <- key
Guolin Ke's avatar
Guolin Ke committed
189
190
        next
      }
191
192
      
      # Update parameters, data
Guolin Ke's avatar
Guolin Ke committed
193
194
195
      valid_data$update_params(params)
      valid_data$set_reference(data)
      reduced_valid_sets[[key]] <- valid_data
196
      
Guolin Ke's avatar
Guolin Ke committed
197
    }
198
    
Guolin Ke's avatar
Guolin Ke committed
199
  }
200
201
  
  # Add printing log callback
202
  if (verbose > 0 && eval_freq > 0) {
Guolin Ke's avatar
Guolin Ke committed
203
204
    callbacks <- add.cb(callbacks, cb.print.evaluation(eval_freq))
  }
205
206
  
  # Add evaluation log callback
207
  if (record && length(valids) > 0) {
Guolin Ke's avatar
Guolin Ke committed
208
209
    callbacks <- add.cb(callbacks, cb.record.evaluation())
  }
210
  
211
  # Check for early stopping passed as parameter when adding early stopping callback
212
213
214
215
  early_stop <- c("early_stopping_round", "early_stopping_rounds", "early_stopping")
  if (any(names(params) %in% early_stop)) {
    if (params[[which(names(params) %in% early_stop)[1]]] > 0) {
      callbacks <- add.cb(callbacks, cb.early.stop(params[[which(names(params) %in% early_stop)[1]]], verbose = verbose))
216
217
218
219
220
221
    }
  } else {
    if (!is.null(early_stopping_rounds)) {
      if (early_stopping_rounds > 0) {
        callbacks <- add.cb(callbacks, cb.early.stop(early_stopping_rounds, verbose = verbose))
      }
Guolin Ke's avatar
Guolin Ke committed
222
223
    }
  }
224
225
  
  # "Categorize" callbacks
Guolin Ke's avatar
Guolin Ke committed
226
  cb <- categorize.callbacks(callbacks)
227
228
  
  # Construct booster with datasets
229
230
  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
231
232
233
  for (key in names(reduced_valid_sets)) {
    booster$add_valid(reduced_valid_sets[[key]], key)
  }
234
235
236
237
  
  # Callback env
  env <- CB_ENV$new()
  env$model <- booster
Guolin Ke's avatar
Guolin Ke committed
238
  env$begin_iteration <- begin_iteration
239
  env$end_iteration <- end_iteration
240
  
241
  # Start training model using number of iterations to start and end with
242
  for (i in seq.int(from = begin_iteration, to = end_iteration)) {
243
244
    
    # Overwrite iteration in environment
Guolin Ke's avatar
Guolin Ke committed
245
246
    env$iteration <- i
    env$eval_list <- list()
247
248
249
250
251
252
253
    
    # Loop through "pre_iter" element
    for (f in cb$pre_iter) {
      f(env)
    }
    
    # Update one boosting iteration
254
    booster$update(fobj = fobj)
255
256
    
    # Prepare collection of evaluation results
Guolin Ke's avatar
Guolin Ke committed
257
    eval_list <- list()
258
259
    
    # Collection: Has validation dataset?
260
    if (length(valids) > 0) {
261
262
      
      # Validation has training dataset?
263
264
      if (vaild_contain_train) {
        eval_list <- append(eval_list, booster$eval_train(feval = feval))
Guolin Ke's avatar
Guolin Ke committed
265
      }
266
267
      
      # Has no validation dataset
268
      eval_list <- append(eval_list, booster$eval_valid(feval = feval))
Guolin Ke's avatar
Guolin Ke committed
269
    }
270
271
    
    # Write evaluation result in environment
Guolin Ke's avatar
Guolin Ke committed
272
    env$eval_list <- eval_list
273
274
275
276
277
278
279
    
    # Loop through env
    for (f in cb$post_iter) {
      f(env)
    }
    
    # Check for early stopping and break if needed
280
    if (env$met_early_stop) break
281
    
Guolin Ke's avatar
Guolin Ke committed
282
  }
283
  
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
  # Check for booster model conversion to predictor model
  if (reset_data) {
    
    # Store temporarily model data elsewhere
    booster_old <- list(best_iter = booster$best_iter,
                        best_score = booster$best_score,
                        record_evals = booster$record_evals)
    
    # 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
    
  }
  
300
301
302
  # Return booster
  return(booster)
  
Guolin Ke's avatar
Guolin Ke committed
303
}