lgb.Dataset.R 37.2 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#' @name lgb_shared_dataset_params
#' @title Shared Dataset parameter docs
#' @description Parameter docs for fields used in \code{lgb.Dataset} construction
#' @param label vector of labels to use as the target variable
#' @param weight numeric vector of sample weights
#' @param init_score initial score is the base prediction lightgbm will boost from
#' @param group used for learning-to-rank tasks. An integer vector describing how to
#'              group rows together as ordered results from the same set of candidate results
#'              to be ranked. For example, if you have a 100-document dataset with
#'              \code{group = c(10, 20, 40, 10, 10, 10)}, that means that you have 6 groups,
#'              where the first 10 records are in the first group, records 11-30 are in the
#'              second group, etc.
#' @keywords internal
NULL

16
17
18
19
20
21
22
23
# [description] List of valid keys for "info" arguments in lgb.Dataset.
#               Wrapped in a function to take advantage of lazy evaluation
#               (so it doesn't matter what order R sources files during installation).
# [return] A character vector of names.
.INFO_KEYS <- function() {
  return(c("label", "weight", "init_score", "group"))
}

James Lamb's avatar
James Lamb committed
24
#' @importFrom methods is
James Lamb's avatar
James Lamb committed
25
#' @importFrom R6 R6Class
26
#' @importFrom utils modifyList
James Lamb's avatar
James Lamb committed
27
28
Dataset <- R6::R6Class(

29
  classname = "lgb.Dataset",
30
  cloneable = FALSE,
Guolin Ke's avatar
Guolin Ke committed
31
  public = list(
James Lamb's avatar
James Lamb committed
32

33
    # Finalize will free up the handles
Guolin Ke's avatar
Guolin Ke committed
34
    finalize = function() {
35
36
37
38
39
      .Call(
        LGBM_DatasetFree_R
        , private$handle
      )
      private$handle <- NULL
40
      return(invisible(NULL))
Guolin Ke's avatar
Guolin Ke committed
41
    },
James Lamb's avatar
James Lamb committed
42

43
    # Initialize will create a starter dataset
Guolin Ke's avatar
Guolin Ke committed
44
    initialize = function(data,
45
46
47
                          params = list(),
                          reference = NULL,
                          colnames = NULL,
48
                          categorical_feature = NULL,
49
50
51
                          predictor = NULL,
                          free_raw_data = TRUE,
                          used_indices = NULL,
52
53
54
55
                          label = NULL,
                          weight = NULL,
                          group = NULL,
                          init_score = NULL) {
James Lamb's avatar
James Lamb committed
56

57
      # validate inputs early to avoid unnecessary computation
58
      if (!(is.null(reference) || lgb.is.Dataset(reference))) {
59
60
          stop("lgb.Dataset: If provided, reference must be a ", sQuote("lgb.Dataset"))
      }
61
      if (!(is.null(predictor) || lgb.is.Predictor(predictor))) {
62
63
64
          stop("lgb.Dataset: If provided, predictor must be a ", sQuote("lgb.Predictor"))
      }

65
      info <- list()
66
67
68
69
70
71
72
73
74
75
76
      if (!is.null(label)) {
        info[["label"]] <- label
      }
      if (!is.null(weight)) {
        info[["weight"]] <- weight
      }
      if (!is.null(group)) {
        info[["group"]] <- group
      }
      if (!is.null(init_score)) {
        info[["init_score"]] <- init_score
Guolin Ke's avatar
Guolin Ke committed
77
      }
James Lamb's avatar
James Lamb committed
78

79
80
81
82
83
84
85
      # Check for matrix format
      if (is.matrix(data)) {
        # Check whether matrix is the correct type first ("double")
        if (storage.mode(data) != "double") {
          storage.mode(data) <- "double"
        }
      }
James Lamb's avatar
James Lamb committed
86

87
88
89
      # Setup private attributes
      private$raw_data <- data
      private$params <- params
Guolin Ke's avatar
Guolin Ke committed
90
      private$reference <- reference
91
      private$colnames <- colnames
92

93
      private$categorical_feature <- categorical_feature
94
95
      private$predictor <- predictor
      private$free_raw_data <- free_raw_data
96
      private$used_indices <- sort(used_indices, decreasing = FALSE)
97
      private$info <- info
98
      private$version <- 0L
James Lamb's avatar
James Lamb committed
99

100
101
      return(invisible(NULL))

Guolin Ke's avatar
Guolin Ke committed
102
    },
James Lamb's avatar
James Lamb committed
103

104
    create_valid = function(data,
105
106
107
108
                            label = NULL,
                            weight = NULL,
                            group = NULL,
                            init_score = NULL,
109
                            params = list()) {
110
111
112
113

      # the Dataset's existing parameters should be overwritten by any passed in to this call
      params <- modifyList(self$get_params(), params)

114
      # Create new dataset
115
116
      ret <- Dataset$new(
        data = data
117
        , params = params
118
119
120
121
122
123
        , reference = self
        , colnames = private$colnames
        , categorical_feature = private$categorical_feature
        , predictor = private$predictor
        , free_raw_data = private$free_raw_data
        , used_indices = NULL
124
125
126
127
        , label = label
        , weight = weight
        , group = group
        , init_score = init_score
128
      )
James Lamb's avatar
James Lamb committed
129

130
      return(invisible(ret))
James Lamb's avatar
James Lamb committed
131

Guolin Ke's avatar
Guolin Ke committed
132
    },
James Lamb's avatar
James Lamb committed
133

134
    # Dataset constructor
Guolin Ke's avatar
Guolin Ke committed
135
    construct = function() {
James Lamb's avatar
James Lamb committed
136

137
      # Check for handle null
138
      if (!lgb.is.null.handle(x = private$handle)) {
139
        return(invisible(self))
Guolin Ke's avatar
Guolin Ke committed
140
      }
James Lamb's avatar
James Lamb committed
141

Guolin Ke's avatar
Guolin Ke committed
142
143
      # Get feature names
      cnames <- NULL
James Lamb's avatar
James Lamb committed
144
      if (is.matrix(private$raw_data) || methods::is(private$raw_data, "dgCMatrix")) {
Guolin Ke's avatar
Guolin Ke committed
145
146
        cnames <- colnames(private$raw_data)
      }
James Lamb's avatar
James Lamb committed
147

148
      # set feature names if they do not exist
149
      if (is.null(private$colnames) && !is.null(cnames)) {
Guolin Ke's avatar
Guolin Ke committed
150
151
        private$colnames <- as.character(cnames)
      }
James Lamb's avatar
James Lamb committed
152

153
154
      # Get categorical feature index
      if (!is.null(private$categorical_feature)) {
James Lamb's avatar
James Lamb committed
155

156
        # Check for character name
157
        if (is.character(private$categorical_feature)) {
James Lamb's avatar
James Lamb committed
158

159
            cate_indices <- as.list(match(private$categorical_feature, private$colnames) - 1L)
James Lamb's avatar
James Lamb committed
160

161
            # Provided indices, but some indices are missing?
162
            if (sum(is.na(cate_indices)) > 0L) {
163
164
165
166
              stop(
                "lgb.self.get.handle: supplied an unknown feature in categorical_feature: "
                , sQuote(private$categorical_feature[is.na(cate_indices)])
              )
167
            }
James Lamb's avatar
James Lamb committed
168

169
          } else {
James Lamb's avatar
James Lamb committed
170

171
            # Check if more categorical features were output over the feature space
172
            if (max(private$categorical_feature) > length(private$colnames)) {
173
174
175
176
177
178
179
              stop(
                "lgb.self.get.handle: supplied a too large value in categorical_feature: "
                , max(private$categorical_feature)
                , " but only "
                , length(private$colnames)
                , " features"
              )
180
            }
James Lamb's avatar
James Lamb committed
181

182
            # Store indices as [0, n-1] indexed instead of [1, n] indexed
183
            cate_indices <- as.list(private$categorical_feature - 1L)
James Lamb's avatar
James Lamb committed
184

185
          }
James Lamb's avatar
James Lamb committed
186

187
        # Store indices for categorical features
188
        private$params$categorical_feature <- cate_indices
James Lamb's avatar
James Lamb committed
189

190
      }
James Lamb's avatar
James Lamb committed
191

Guolin Ke's avatar
Guolin Ke committed
192
      # Generate parameter str
193
      params_str <- lgb.params2str(params = private$params)
James Lamb's avatar
James Lamb committed
194

195
      # Get handle of reference dataset
Guolin Ke's avatar
Guolin Ke committed
196
197
198
199
      ref_handle <- NULL
      if (!is.null(private$reference)) {
        ref_handle <- private$reference$.__enclos_env__$private$get_handle()
      }
James Lamb's avatar
James Lamb committed
200

201
      # not subsetting, constructing from raw data
Guolin Ke's avatar
Guolin Ke committed
202
      if (is.null(private$used_indices)) {
James Lamb's avatar
James Lamb committed
203

204
205
206
207
208
209
210
211
212
        if (is.null(private$raw_data)) {
          stop(paste0(
            "Attempting to create a Dataset without any raw data. "
            , "This can happen if you have called Dataset$finalize() or if this Dataset was saved with saveRDS(). "
            , "To avoid this error in the future, use lgb.Dataset.save() or "
            , "Dataset$save_binary() to save lightgbm Datasets."
          ))
        }

213
        # Are we using a data file?
214
        if (is.character(private$raw_data)) {
James Lamb's avatar
James Lamb committed
215

216
          handle <- .Call(
217
            LGBM_DatasetCreateFromFile_R
218
            , path.expand(private$raw_data)
219
220
221
            , params_str
            , ref_handle
          )
James Lamb's avatar
James Lamb committed
222

Guolin Ke's avatar
Guolin Ke committed
223
        } else if (is.matrix(private$raw_data)) {
James Lamb's avatar
James Lamb committed
224

225
          # Are we using a matrix?
226
          handle <- .Call(
227
            LGBM_DatasetCreateFromMat_R
228
229
230
231
232
233
            , private$raw_data
            , nrow(private$raw_data)
            , ncol(private$raw_data)
            , params_str
            , ref_handle
          )
James Lamb's avatar
James Lamb committed
234
235

        } else if (methods::is(private$raw_data, "dgCMatrix")) {
236
          if (length(private$raw_data@p) > 2147483647L) {
237
238
            stop("Cannot support large CSC matrix")
          }
239
          # Are we using a dgCMatrix (sparse matrix column compressed)
240
          handle <- .Call(
241
            LGBM_DatasetCreateFromCSC_R
242
243
244
245
246
247
248
249
250
            , private$raw_data@p
            , private$raw_data@i
            , private$raw_data@x
            , length(private$raw_data@p)
            , length(private$raw_data@x)
            , nrow(private$raw_data)
            , params_str
            , ref_handle
          )
James Lamb's avatar
James Lamb committed
251

Guolin Ke's avatar
Guolin Ke committed
252
        } else {
James Lamb's avatar
James Lamb committed
253

254
          # Unknown data type
255
256
257
258
          stop(
            "lgb.Dataset.construct: does not support constructing from "
            , sQuote(class(private$raw_data))
          )
James Lamb's avatar
James Lamb committed
259

Guolin Ke's avatar
Guolin Ke committed
260
        }
James Lamb's avatar
James Lamb committed
261

Guolin Ke's avatar
Guolin Ke committed
262
      } else {
James Lamb's avatar
James Lamb committed
263

264
        # Reference is empty
Guolin Ke's avatar
Guolin Ke committed
265
        if (is.null(private$reference)) {
266
          stop("lgb.Dataset.construct: reference cannot be NULL for constructing data subset")
Guolin Ke's avatar
Guolin Ke committed
267
        }
James Lamb's avatar
James Lamb committed
268

269
        # Construct subset
270
        handle <- .Call(
271
          LGBM_DatasetGetSubset_R
272
273
274
275
276
          , ref_handle
          , c(private$used_indices) # Adding c() fixes issue in R v3.5
          , length(private$used_indices)
          , params_str
        )
James Lamb's avatar
James Lamb committed
277

Guolin Ke's avatar
Guolin Ke committed
278
      }
279
      if (lgb.is.null.handle(x = handle)) {
Guolin Ke's avatar
Guolin Ke committed
280
281
        stop("lgb.Dataset.construct: cannot create Dataset handle")
      }
282
      # Setup class and private type
Guolin Ke's avatar
Guolin Ke committed
283
284
      class(handle) <- "lgb.Dataset.handle"
      private$handle <- handle
James Lamb's avatar
James Lamb committed
285

286
287
      # Set feature names
      if (!is.null(private$colnames)) {
288
        self$set_colnames(colnames = private$colnames)
289
      }
290

291
292
      # Load init score if requested
      if (!is.null(private$predictor) && is.null(private$used_indices)) {
James Lamb's avatar
James Lamb committed
293

294
        # Setup initial scores
295
        init_score <- private$predictor$predict(
296
          data = private$raw_data
297
298
299
          , rawscore = TRUE
          , reshape = TRUE
        )
James Lamb's avatar
James Lamb committed
300

301
        # Not needed to transpose, for is col_marjor
Guolin Ke's avatar
Guolin Ke committed
302
303
        init_score <- as.vector(init_score)
        private$info$init_score <- init_score
James Lamb's avatar
James Lamb committed
304

305
      }
James Lamb's avatar
James Lamb committed
306

307
308
309
      # Should we free raw data?
      if (isTRUE(private$free_raw_data)) {
        private$raw_data <- NULL
Guolin Ke's avatar
Guolin Ke committed
310
      }
James Lamb's avatar
James Lamb committed
311

312
      # Get private information
313
      if (length(private$info) > 0L) {
James Lamb's avatar
James Lamb committed
314

315
        # Set infos
316
        for (i in seq_along(private$info)) {
James Lamb's avatar
James Lamb committed
317

Guolin Ke's avatar
Guolin Ke committed
318
          p <- private$info[i]
319
320
321
322
          self$set_field(
            field_name = names(p)
            , data = p[[1L]]
          )
James Lamb's avatar
James Lamb committed
323

Guolin Ke's avatar
Guolin Ke committed
324
        }
James Lamb's avatar
James Lamb committed
325

Guolin Ke's avatar
Guolin Ke committed
326
      }
James Lamb's avatar
James Lamb committed
327

328
      # Get label information existence
329
      if (is.null(self$get_field(field_name = "label"))) {
Guolin Ke's avatar
Guolin Ke committed
330
331
        stop("lgb.Dataset.construct: label should be set")
      }
James Lamb's avatar
James Lamb committed
332

333
      return(invisible(self))
James Lamb's avatar
James Lamb committed
334

Guolin Ke's avatar
Guolin Ke committed
335
    },
James Lamb's avatar
James Lamb committed
336

337
    # Dimension function
Guolin Ke's avatar
Guolin Ke committed
338
    dim = function() {
James Lamb's avatar
James Lamb committed
339

340
      # Check for handle
341
      if (!lgb.is.null.handle(x = private$handle)) {
James Lamb's avatar
James Lamb committed
342

343
344
        num_row <- 0L
        num_col <- 0L
James Lamb's avatar
James Lamb committed
345

346
        # Get numeric data and numeric features
347
348
349
350
351
352
353
354
355
356
        .Call(
          LGBM_DatasetGetNumData_R
          , private$handle
          , num_row
        )
        .Call(
          LGBM_DatasetGetNumFeature_R
          , private$handle
          , num_col
        )
357
        return(
358
          c(num_row, num_col)
359
        )
James Lamb's avatar
James Lamb committed
360
361
362

      } else if (is.matrix(private$raw_data) || methods::is(private$raw_data, "dgCMatrix")) {

363
        # Check if dgCMatrix (sparse matrix column compressed)
364
        # NOTE: requires Matrix package
365
        return(dim(private$raw_data))
James Lamb's avatar
James Lamb committed
366

Guolin Ke's avatar
Guolin Ke committed
367
      } else {
James Lamb's avatar
James Lamb committed
368

369
        # Trying to work with unknown dimensions is not possible
370
371
372
373
        stop(
          "dim: cannot get dimensions before dataset has been constructed, "
          , "please call lgb.Dataset.construct explicitly"
        )
James Lamb's avatar
James Lamb committed
374

Guolin Ke's avatar
Guolin Ke committed
375
      }
James Lamb's avatar
James Lamb committed
376

Guolin Ke's avatar
Guolin Ke committed
377
    },
James Lamb's avatar
James Lamb committed
378

379
    # Get column names
Guolin Ke's avatar
Guolin Ke committed
380
    get_colnames = function() {
James Lamb's avatar
James Lamb committed
381

382
      # Check for handle
383
      if (!lgb.is.null.handle(x = private$handle)) {
384
        private$colnames <- .Call(
385
386
          LGBM_DatasetGetFeatureNames_R
          , private$handle
387
        )
388
        return(private$colnames)
James Lamb's avatar
James Lamb committed
389
390
391

      } else if (is.matrix(private$raw_data) || methods::is(private$raw_data, "dgCMatrix")) {

392
        # Check if dgCMatrix (sparse matrix column compressed)
393
        return(colnames(private$raw_data))
James Lamb's avatar
James Lamb committed
394

Guolin Ke's avatar
Guolin Ke committed
395
      } else {
James Lamb's avatar
James Lamb committed
396

397
        # Trying to work with unknown formats is not possible
398
        stop(
399
400
          "Dataset$get_colnames(): cannot get column names before dataset has been constructed, please call "
          , "lgb.Dataset.construct() explicitly"
401
        )
James Lamb's avatar
James Lamb committed
402

Guolin Ke's avatar
Guolin Ke committed
403
      }
James Lamb's avatar
James Lamb committed
404

Guolin Ke's avatar
Guolin Ke committed
405
    },
James Lamb's avatar
James Lamb committed
406

407
    # Set column names
Guolin Ke's avatar
Guolin Ke committed
408
    set_colnames = function(colnames) {
James Lamb's avatar
James Lamb committed
409

410
411
      # Check column names non-existence
      if (is.null(colnames)) {
412
        return(invisible(self))
413
      }
James Lamb's avatar
James Lamb committed
414

415
      # Check empty column names
Guolin Ke's avatar
Guolin Ke committed
416
      colnames <- as.character(colnames)
417
      if (length(colnames) == 0L) {
418
        return(invisible(self))
419
      }
James Lamb's avatar
James Lamb committed
420

421
      # Write column names
Guolin Ke's avatar
Guolin Ke committed
422
      private$colnames <- colnames
423
      if (!lgb.is.null.handle(x = private$handle)) {
James Lamb's avatar
James Lamb committed
424

425
        # Merge names with tab separation
Guolin Ke's avatar
Guolin Ke committed
426
        merged_name <- paste0(as.list(private$colnames), collapse = "\t")
427
428
        .Call(
          LGBM_DatasetSetFeatureNames_R
429
          , private$handle
430
          , merged_name
431
        )
James Lamb's avatar
James Lamb committed
432

Guolin Ke's avatar
Guolin Ke committed
433
      }
James Lamb's avatar
James Lamb committed
434

435
      return(invisible(self))
James Lamb's avatar
James Lamb committed
436

Guolin Ke's avatar
Guolin Ke committed
437
    },
James Lamb's avatar
James Lamb committed
438

439
    get_field = function(field_name) {
James Lamb's avatar
James Lamb committed
440

441
      # Check if attribute key is in the known attribute list
442
443
444
445
446
      if (!is.character(field_name) || length(field_name) != 1L || !field_name %in% .INFO_KEYS()) {
        stop(
          "Dataset$get_field(): field_name must one of the following: "
          , paste0(sQuote(.INFO_KEYS()), collapse = ", ")
        )
Guolin Ke's avatar
Guolin Ke committed
447
      }
James Lamb's avatar
James Lamb committed
448

449
      # Check for info name and handle
450
      if (is.null(private$info[[field_name]])) {
451

452
        if (lgb.is.null.handle(x = private$handle)) {
453
          stop("Cannot perform Dataset$get_field() before constructing Dataset.")
454
        }
455

456
        # Get field size of info
457
        info_len <- 0L
458
459
        .Call(
          LGBM_DatasetGetFieldSize_R
460
          , private$handle
461
          , field_name
462
          , info_len
463
        )
James Lamb's avatar
James Lamb committed
464

465
        if (info_len > 0L) {
James Lamb's avatar
James Lamb committed
466

467
          # Get back fields
Guolin Ke's avatar
Guolin Ke committed
468
          ret <- NULL
469
          ret <- if (field_name == "group") {
470
            integer(info_len)
471
          } else {
472
            numeric(info_len)
473
          }
James Lamb's avatar
James Lamb committed
474

475
476
          .Call(
            LGBM_DatasetGetField_R
477
            , private$handle
478
            , field_name
479
            , ret
480
          )
James Lamb's avatar
James Lamb committed
481

482
          private$info[[field_name]] <- ret
James Lamb's avatar
James Lamb committed
483

Guolin Ke's avatar
Guolin Ke committed
484
485
        }
      }
James Lamb's avatar
James Lamb committed
486

487
      return(private$info[[field_name]])
James Lamb's avatar
James Lamb committed
488

Guolin Ke's avatar
Guolin Ke committed
489
    },
James Lamb's avatar
James Lamb committed
490

491
    set_field = function(field_name, data) {
James Lamb's avatar
James Lamb committed
492

493
      # Check if attribute key is in the known attribute list
494
495
496
497
498
      if (!is.character(field_name) || length(field_name) != 1L || !field_name %in% .INFO_KEYS()) {
        stop(
          "Dataset$set_field(): field_name must one of the following: "
          , paste0(sQuote(.INFO_KEYS()), collapse = ", ")
        )
499
      }
James Lamb's avatar
James Lamb committed
500

501
      # Check for type of information
502
      data <- if (field_name == "group") {
503
        as.integer(data)
504
      } else {
505
        as.numeric(data)
506
      }
James Lamb's avatar
James Lamb committed
507

508
      # Store information privately
509
      private$info[[field_name]] <- data
James Lamb's avatar
James Lamb committed
510

511
      if (!lgb.is.null.handle(x = private$handle) && !is.null(data)) {
James Lamb's avatar
James Lamb committed
512

513
        if (length(data) > 0L) {
James Lamb's avatar
James Lamb committed
514

515
516
          .Call(
            LGBM_DatasetSetField_R
517
            , private$handle
518
519
520
            , field_name
            , data
            , length(data)
521
          )
James Lamb's avatar
James Lamb committed
522

523
524
          private$version <- private$version + 1L

Guolin Ke's avatar
Guolin Ke committed
525
        }
James Lamb's avatar
James Lamb committed
526

Guolin Ke's avatar
Guolin Ke committed
527
      }
James Lamb's avatar
James Lamb committed
528

529
      return(invisible(self))
James Lamb's avatar
James Lamb committed
530

Guolin Ke's avatar
Guolin Ke committed
531
    },
James Lamb's avatar
James Lamb committed
532

533
    slice = function(idxset) {
534

535
536
537
      return(
        Dataset$new(
          data = NULL
538
          , params = self$get_params()
539
540
541
542
543
544
545
          , reference = self
          , colnames = private$colnames
          , categorical_feature = private$categorical_feature
          , predictor = private$predictor
          , free_raw_data = private$free_raw_data
          , used_indices = sort(idxset, decreasing = FALSE)
        )
546
      )
James Lamb's avatar
James Lamb committed
547

Guolin Ke's avatar
Guolin Ke committed
548
    },
James Lamb's avatar
James Lamb committed
549

550
551
552
    # [description] Update Dataset parameters. If it has not been constructed yet,
    #               this operation just happens on the R side (updating private$params).
    #               If it has been constructed, parameters will be updated on the C++ side.
553
    update_params = function(params) {
554
555
556
      if (length(params) == 0L) {
        return(invisible(self))
      }
557
      if (lgb.is.null.handle(x = private$handle)) {
558
        private$params <- utils::modifyList(private$params, params)
559
      } else {
560
561
        tryCatch({
          .Call(
562
            LGBM_DatasetUpdateParamChecking_R
563
564
565
566
567
568
            , lgb.params2str(params = private$params)
            , lgb.params2str(params = params)
          )
        }, error = function(e) {
          # If updating failed but raw data is not available, raise an error because
          # achieving what the user asked for is not possible
569
          if (is.null(private$raw_data)) {
570
            stop(e)
571
572
          }

573
574
          # If updating failed but raw data is available, modify the params
          # on the R side and re-set ("deconstruct") the Dataset
575
          private$params <- utils::modifyList(private$params, params)
576
          self$finalize()
577
        })
578
      }
579
      return(invisible(self))
James Lamb's avatar
James Lamb committed
580

Guolin Ke's avatar
Guolin Ke committed
581
    },
James Lamb's avatar
James Lamb committed
582

583
584
585
586
587
588
589
590
591
592
593
    get_params = function() {
      dataset_params <- unname(unlist(.DATASET_PARAMETERS()))
      ret <- list()
      for (param_key in names(private$params)) {
        if (param_key %in% dataset_params) {
          ret[[param_key]] <- private$params[[param_key]]
        }
      }
      return(ret)
    },

594
    # Set categorical feature parameter
595
    set_categorical_feature = function(categorical_feature) {
James Lamb's avatar
James Lamb committed
596

597
598
      # Check for identical input
      if (identical(private$categorical_feature, categorical_feature)) {
599
        return(invisible(self))
600
      }
James Lamb's avatar
James Lamb committed
601

602
      # Check for empty data
603
      if (is.null(private$raw_data)) {
604
605
        stop("set_categorical_feature: cannot set categorical feature after freeing raw data,
          please set ", sQuote("free_raw_data = FALSE"), " when you construct lgb.Dataset")
606
      }
James Lamb's avatar
James Lamb committed
607

608
      # Overwrite categorical features
609
      private$categorical_feature <- categorical_feature
James Lamb's avatar
James Lamb committed
610

611
      # Finalize and return self
612
      self$finalize()
613
      return(invisible(self))
James Lamb's avatar
James Lamb committed
614

615
    },
James Lamb's avatar
James Lamb committed
616

Guolin Ke's avatar
Guolin Ke committed
617
    set_reference = function(reference) {
James Lamb's avatar
James Lamb committed
618

619
      # setting reference to this same Dataset object doesn't require any changes
620
      if (identical(private$reference, reference)) {
621
        return(invisible(self))
622
      }
James Lamb's avatar
James Lamb committed
623

624
625
      # changing the reference removes the Dataset object on the C++ side, so it should only
      # be done if you still have the raw_data available, so that the new Dataset can be reconstructed
Guolin Ke's avatar
Guolin Ke committed
626
      if (is.null(private$raw_data)) {
627
628
        stop("set_reference: cannot set reference after freeing raw data,
          please set ", sQuote("free_raw_data = FALSE"), " when you construct lgb.Dataset")
Guolin Ke's avatar
Guolin Ke committed
629
      }
James Lamb's avatar
James Lamb committed
630

631
632
      if (!lgb.is.Dataset(reference)) {
        stop("set_reference: Can only use lgb.Dataset as a reference")
Guolin Ke's avatar
Guolin Ke committed
633
      }
James Lamb's avatar
James Lamb committed
634

635
636
637
638
639
      # Set known references
      self$set_categorical_feature(categorical_feature = reference$.__enclos_env__$private$categorical_feature)
      self$set_colnames(colnames = reference$get_colnames())
      private$set_predictor(predictor = reference$.__enclos_env__$private$predictor)

640
      # Store reference
Guolin Ke's avatar
Guolin Ke committed
641
      private$reference <- reference
James Lamb's avatar
James Lamb committed
642

643
      # Finalize and return self
Guolin Ke's avatar
Guolin Ke committed
644
      self$finalize()
645
      return(invisible(self))
James Lamb's avatar
James Lamb committed
646

Guolin Ke's avatar
Guolin Ke committed
647
    },
James Lamb's avatar
James Lamb committed
648

649
    # Save binary model
Guolin Ke's avatar
Guolin Ke committed
650
    save_binary = function(fname) {
James Lamb's avatar
James Lamb committed
651

652
      # Store binary data
Guolin Ke's avatar
Guolin Ke committed
653
      self$construct()
654
655
      .Call(
        LGBM_DatasetSaveBinary_R
656
        , private$handle
657
        , path.expand(fname)
658
      )
659
      return(invisible(self))
Guolin Ke's avatar
Guolin Ke committed
660
    }
James Lamb's avatar
James Lamb committed
661

Guolin Ke's avatar
Guolin Ke committed
662
663
  ),
  private = list(
664
665
666
667
668
    handle = NULL,
    raw_data = NULL,
    params = list(),
    reference = NULL,
    colnames = NULL,
669
    categorical_feature = NULL,
670
671
672
673
    predictor = NULL,
    free_raw_data = TRUE,
    used_indices = NULL,
    info = NULL,
674
    version = 0L,
James Lamb's avatar
James Lamb committed
675

676
    get_handle = function() {
James Lamb's avatar
James Lamb committed
677

678
      # Get handle and construct if needed
679
      if (lgb.is.null.handle(x = private$handle)) {
680
681
        self$construct()
      }
682
      return(private$handle)
James Lamb's avatar
James Lamb committed
683

Guolin Ke's avatar
Guolin Ke committed
684
    },
James Lamb's avatar
James Lamb committed
685

Guolin Ke's avatar
Guolin Ke committed
686
    set_predictor = function(predictor) {
James Lamb's avatar
James Lamb committed
687

688
      if (identical(private$predictor, predictor)) {
689
        return(invisible(self))
690
      }
James Lamb's avatar
James Lamb committed
691

692
      # Check for empty data
Guolin Ke's avatar
Guolin Ke committed
693
      if (is.null(private$raw_data)) {
694
695
        stop("set_predictor: cannot set predictor after free raw data,
          please set ", sQuote("free_raw_data = FALSE"), " when you construct lgb.Dataset")
Guolin Ke's avatar
Guolin Ke committed
696
      }
James Lamb's avatar
James Lamb committed
697

698
      # Check for empty predictor
Guolin Ke's avatar
Guolin Ke committed
699
      if (!is.null(predictor)) {
James Lamb's avatar
James Lamb committed
700

701
        # Predictor is unknown
702
        if (!lgb.is.Predictor(predictor)) {
703
          stop("set_predictor: Can only use lgb.Predictor as predictor")
Guolin Ke's avatar
Guolin Ke committed
704
        }
James Lamb's avatar
James Lamb committed
705

Guolin Ke's avatar
Guolin Ke committed
706
      }
James Lamb's avatar
James Lamb committed
707

708
      # Store predictor
Guolin Ke's avatar
Guolin Ke committed
709
      private$predictor <- predictor
James Lamb's avatar
James Lamb committed
710

711
      # Finalize and return self
Guolin Ke's avatar
Guolin Ke committed
712
      self$finalize()
713
      return(invisible(self))
James Lamb's avatar
James Lamb committed
714

Guolin Ke's avatar
Guolin Ke committed
715
    }
James Lamb's avatar
James Lamb committed
716

Guolin Ke's avatar
Guolin Ke committed
717
718
719
  )
)

720
721
722
#' @title Construct \code{lgb.Dataset} object
#' @description Construct \code{lgb.Dataset} object from dense matrix, sparse matrix
#'              or local file (that was created previously by saving an \code{lgb.Dataset}).
723
#' @inheritParams lgb_shared_dataset_params
724
725
726
#' @param data a \code{matrix} object, a \code{dgCMatrix} object,
#'             a character representing a path to a text file (CSV, TSV, or LibSVM),
#'             or a character representing a path to a binary \code{lgb.Dataset} file
727
728
729
730
731
732
733
#' @param params a list of parameters. See
#'               \href{https://lightgbm.readthedocs.io/en/latest/Parameters.html#dataset-parameters}{
#'               The "Dataset Parameters" section of the documentation} for a list of parameters
#'               and valid values.
#' @param reference reference dataset. When LightGBM creates a Dataset, it does some preprocessing like binning
#'                  continuous features into histograms. If you want to apply the same bin boundaries from an existing
#'                  dataset to new \code{data}, pass that existing Dataset to this argument.
Guolin Ke's avatar
Guolin Ke committed
734
#' @param colnames names of columns
735
736
737
738
739
740
741
742
#' @param 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").
#' @param free_raw_data LightGBM constructs its data format, called a "Dataset", from tabular data.
#'                      By default, that Dataset object on the R side does not keep a copy of the raw data.
#'                      This reduces LightGBM's memory consumption, but it means that the Dataset object
#'                      cannot be changed after it has been constructed. If you'd prefer to be able to
#'                      change the Dataset object after construction, set \code{free_raw_data = FALSE}.
James Lamb's avatar
James Lamb committed
743
#'
Guolin Ke's avatar
Guolin Ke committed
744
#' @return constructed dataset
James Lamb's avatar
James Lamb committed
745
#'
Guolin Ke's avatar
Guolin Ke committed
746
#' @examples
747
#' \donttest{
748
749
750
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
751
752
753
#' data_file <- tempfile(fileext = ".data")
#' lgb.Dataset.save(dtrain, data_file)
#' dtrain <- lgb.Dataset(data_file)
754
#' lgb.Dataset.construct(dtrain)
755
#' }
Guolin Ke's avatar
Guolin Ke committed
756
757
#' @export
lgb.Dataset <- function(data,
758
759
760
                        params = list(),
                        reference = NULL,
                        colnames = NULL,
761
                        categorical_feature = NULL,
762
                        free_raw_data = TRUE,
763
764
765
                        label = NULL,
                        weight = NULL,
                        group = NULL,
766
                        init_score = NULL) {
767

768
769
770
771
772
773
774
775
776
777
  return(
    invisible(Dataset$new(
      data = data
      , params = params
      , reference = reference
      , colnames = colnames
      , categorical_feature = categorical_feature
      , predictor = NULL
      , free_raw_data = free_raw_data
      , used_indices = NULL
778
779
780
781
      , label = label
      , weight = weight
      , group = group
      , init_score = init_score
782
783
    ))
  )
James Lamb's avatar
James Lamb committed
784

Guolin Ke's avatar
Guolin Ke committed
785
786
}

787
788
789
#' @name lgb.Dataset.create.valid
#' @title Construct validation data
#' @description Construct validation data according to training data
790
#' @inheritParams lgb_shared_dataset_params
Guolin Ke's avatar
Guolin Ke committed
791
#' @param dataset \code{lgb.Dataset} object, training data
792
793
794
#' @param data a \code{matrix} object, a \code{dgCMatrix} object,
#'             a character representing a path to a text file (CSV, TSV, or LibSVM),
#'             or a character representing a path to a binary \code{Dataset} file
795
796
797
798
799
#' @param params a list of parameters. See
#'               \href{https://lightgbm.readthedocs.io/en/latest/Parameters.html#dataset-parameters}{
#'               The "Dataset Parameters" section of the documentation} for a list of parameters
#'               and valid values. If this is an empty list (the default), the validation Dataset
#'               will have the same parameters as the Dataset passed to argument \code{dataset}.
James Lamb's avatar
James Lamb committed
800
#'
Guolin Ke's avatar
Guolin Ke committed
801
#' @return constructed dataset
James Lamb's avatar
James Lamb committed
802
#'
Guolin Ke's avatar
Guolin Ke committed
803
#' @examples
804
#' \donttest{
805
806
807
808
809
810
#' 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)
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
#'
#' # parameters can be changed between the training data and validation set,
#' # for example to account for training data in a text file with a header row
#' # and validation data in a text file without it
#' train_file <- tempfile(pattern = "train_", fileext = ".csv")
#' write.table(
#'   data.frame(y = rnorm(100L), x1 = rnorm(100L), x2 = rnorm(100L))
#'   , file = train_file
#'   , sep = ","
#'   , col.names = TRUE
#'   , row.names = FALSE
#'   , quote = FALSE
#' )
#'
#' valid_file <- tempfile(pattern = "valid_", fileext = ".csv")
#' write.table(
#'   data.frame(y = rnorm(100L), x1 = rnorm(100L), x2 = rnorm(100L))
#'   , file = valid_file
#'   , sep = ","
#'   , col.names = FALSE
#'   , row.names = FALSE
#'   , quote = FALSE
#' )
#'
#' dtrain <- lgb.Dataset(
#'   data = train_file
#'   , params = list(has_header = TRUE)
#' )
#' dtrain$construct()
#'
#' dvalid <- lgb.Dataset(
#'   data = valid_file
#'   , params = list(has_header = FALSE)
#' )
#' dvalid$construct()
846
#' }
Guolin Ke's avatar
Guolin Ke committed
847
#' @export
848
849
850
851
852
853
lgb.Dataset.create.valid <- function(dataset,
                                     data,
                                     label = NULL,
                                     weight = NULL,
                                     group = NULL,
                                     init_score = NULL,
854
                                     params = list()) {
James Lamb's avatar
James Lamb committed
855

856
  if (!lgb.is.Dataset(x = dataset)) {
857
    stop("lgb.Dataset.create.valid: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
858
  }
James Lamb's avatar
James Lamb committed
859

860
  # Create validation dataset
861
862
863
864
865
866
867
  return(invisible(
    dataset$create_valid(
      data = data
      , label = label
      , weight = weight
      , group = group
      , init_score = init_score
868
      , params = params
869
870
    )
  ))
James Lamb's avatar
James Lamb committed
871

872
}
Guolin Ke's avatar
Guolin Ke committed
873

874
875
876
#' @name lgb.Dataset.construct
#' @title Construct Dataset explicitly
#' @description Construct Dataset explicitly
Guolin Ke's avatar
Guolin Ke committed
877
#' @param dataset Object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
878
#'
Guolin Ke's avatar
Guolin Ke committed
879
#' @examples
880
#' \donttest{
881
882
883
884
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' lgb.Dataset.construct(dtrain)
885
#' }
886
#' @return constructed dataset
Guolin Ke's avatar
Guolin Ke committed
887
888
#' @export
lgb.Dataset.construct <- function(dataset) {
James Lamb's avatar
James Lamb committed
889

890
  if (!lgb.is.Dataset(x = dataset)) {
891
    stop("lgb.Dataset.construct: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
892
  }
James Lamb's avatar
James Lamb committed
893

894
  return(invisible(dataset$construct()))
James Lamb's avatar
James Lamb committed
895

Guolin Ke's avatar
Guolin Ke committed
896
897
}

898
899
#' @title Dimensions of an \code{lgb.Dataset}
#' @description Returns a vector of numbers of rows and of columns in an \code{lgb.Dataset}.
Guolin Ke's avatar
Guolin Ke committed
900
#' @param x Object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
901
#'
Guolin Ke's avatar
Guolin Ke committed
902
#' @return a vector of numbers of rows and of columns
James Lamb's avatar
James Lamb committed
903
#'
Guolin Ke's avatar
Guolin Ke committed
904
905
906
#' @details
#' Note: since \code{nrow} and \code{ncol} internally use \code{dim}, they can also
#' be directly used with an \code{lgb.Dataset} object.
James Lamb's avatar
James Lamb committed
907
#'
Guolin Ke's avatar
Guolin Ke committed
908
#' @examples
909
#' \donttest{
910
911
912
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
James Lamb's avatar
James Lamb committed
913
#'
914
915
916
#' stopifnot(nrow(dtrain) == nrow(train$data))
#' stopifnot(ncol(dtrain) == ncol(train$data))
#' stopifnot(all(dim(dtrain) == dim(train$data)))
917
#' }
Guolin Ke's avatar
Guolin Ke committed
918
919
#' @rdname dim
#' @export
920
dim.lgb.Dataset <- function(x) {
921

922
  if (!lgb.is.Dataset(x = x)) {
923
    stop("dim.lgb.Dataset: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
924
  }
James Lamb's avatar
James Lamb committed
925

926
  return(x$dim())
James Lamb's avatar
James Lamb committed
927

Guolin Ke's avatar
Guolin Ke committed
928
929
}

930
931
932
#' @title Handling of column names of \code{lgb.Dataset}
#' @description Only column names are supported for \code{lgb.Dataset}, thus setting of
#'              row names would have no effect and returned row names would be NULL.
Guolin Ke's avatar
Guolin Ke committed
933
934
#' @param x object of class \code{lgb.Dataset}
#' @param value a list of two elements: the first one is ignored
935
#'              and the second one is column names
Guolin Ke's avatar
Guolin Ke committed
936
937
938
939
940
941
#'
#' @details
#' Generic \code{dimnames} methods are used by \code{colnames}.
#' Since row names are irrelevant, it is recommended to use \code{colnames} directly.
#'
#' @examples
942
#' \donttest{
943
944
945
946
947
948
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' lgb.Dataset.construct(dtrain)
#' dimnames(dtrain)
#' colnames(dtrain)
949
#' colnames(dtrain) <- make.names(seq_len(ncol(train$data)))
950
#' print(dtrain, verbose = TRUE)
951
#' }
Guolin Ke's avatar
Guolin Ke committed
952
#' @rdname dimnames.lgb.Dataset
953
#' @return A list with the dimension names of the dataset
Guolin Ke's avatar
Guolin Ke committed
954
955
#' @export
dimnames.lgb.Dataset <- function(x) {
James Lamb's avatar
James Lamb committed
956

957
  if (!lgb.is.Dataset(x = x)) {
958
    stop("dimnames.lgb.Dataset: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
959
  }
James Lamb's avatar
James Lamb committed
960

961
  # Return dimension names
962
  return(list(NULL, x$get_colnames()))
James Lamb's avatar
James Lamb committed
963

Guolin Ke's avatar
Guolin Ke committed
964
965
966
967
968
}

#' @rdname dimnames.lgb.Dataset
#' @export
`dimnames<-.lgb.Dataset` <- function(x, value) {
James Lamb's avatar
James Lamb committed
969

970
  # Check if invalid element list
971
  if (!identical(class(value), "list") || length(value) != 2L) {
972
    stop("invalid ", sQuote("value"), " given: must be a list of two elements")
973
  }
James Lamb's avatar
James Lamb committed
974

975
976
977
978
  # Check for unknown row names
  if (!is.null(value[[1L]])) {
    stop("lgb.Dataset does not have rownames")
  }
James Lamb's avatar
James Lamb committed
979

980
  if (is.null(value[[2L]])) {
James Lamb's avatar
James Lamb committed
981

982
    x$set_colnames(colnames = NULL)
Guolin Ke's avatar
Guolin Ke committed
983
    return(x)
James Lamb's avatar
James Lamb committed
984

985
  }
James Lamb's avatar
James Lamb committed
986

987
  # Check for unmatching column size
988
  if (ncol(x) != length(value[[2L]])) {
989
990
    stop(
      "can't assign "
991
      , sQuote(length(value[[2L]]))
992
993
994
995
      , " colnames to an lgb.Dataset with "
      , sQuote(ncol(x))
      , " columns"
    )
Guolin Ke's avatar
Guolin Ke committed
996
  }
James Lamb's avatar
James Lamb committed
997

998
  # Set column names properly, and return
999
  x$set_colnames(colnames = value[[2L]])
1000
  return(x)
James Lamb's avatar
James Lamb committed
1001

Guolin Ke's avatar
Guolin Ke committed
1002
1003
}

1004
1005
1006
#' @title Slice a dataset
#' @description Get a new \code{lgb.Dataset} containing the specified rows of
#'              original \code{lgb.Dataset} object
Nikita Titov's avatar
Nikita Titov committed
1007
#' @param dataset Object of class \code{lgb.Dataset}
1008
#' @param idxset an integer vector of indices of rows needed
Guolin Ke's avatar
Guolin Ke committed
1009
#' @return constructed sub dataset
James Lamb's avatar
James Lamb committed
1010
#'
Guolin Ke's avatar
Guolin Ke committed
1011
#' @examples
1012
#' \donttest{
1013
1014
1015
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
James Lamb's avatar
James Lamb committed
1016
#'
1017
#' dsub <- lightgbm::slice(dtrain, seq_len(42L))
1018
#' lgb.Dataset.construct(dsub)
1019
#' labels <- lightgbm::get_field(dsub, "label")
1020
#' }
Guolin Ke's avatar
Guolin Ke committed
1021
#' @export
1022
slice <- function(dataset, idxset) {
1023
1024
  UseMethod("slice")
}
Guolin Ke's avatar
Guolin Ke committed
1025
1026
1027

#' @rdname slice
#' @export
1028
slice.lgb.Dataset <- function(dataset, idxset) {
James Lamb's avatar
James Lamb committed
1029

1030
  if (!lgb.is.Dataset(x = dataset)) {
1031
    stop("slice.lgb.Dataset: input dataset should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1032
  }
James Lamb's avatar
James Lamb committed
1033

1034
  return(invisible(dataset$slice(idxset = idxset)))
James Lamb's avatar
James Lamb committed
1035

Guolin Ke's avatar
Guolin Ke committed
1036
1037
}

1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
#' @name get_field
#' @title Get one attribute of a \code{lgb.Dataset}
#' @description Get one attribute of a \code{lgb.Dataset}
#' @param dataset Object of class \code{lgb.Dataset}
#' @param field_name String with the name of the attribute to get. One of the following.
#' \itemize{
#'     \item \code{label}: label lightgbm learns from ;
#'     \item \code{weight}: to do a weight rescale ;
#'     \item{\code{group}: used for learning-to-rank tasks. An integer vector describing how to
#'         group rows together as ordered results from the same set of candidate results to be ranked.
#'         For example, if you have a 100-document dataset with \code{group = c(10, 20, 40, 10, 10, 10)},
#'         that means that you have 6 groups, where the first 10 records are in the first group,
#'         records 11-30 are in the second group, etc.}
#'     \item \code{init_score}: initial score is the base prediction lightgbm will boost from.
#' }
#' @return requested attribute
#'
#' @examples
#' \donttest{
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' lgb.Dataset.construct(dtrain)
#'
#' labels <- lightgbm::get_field(dtrain, "label")
#' lightgbm::set_field(dtrain, "label", 1 - labels)
#'
#' labels2 <- lightgbm::get_field(dtrain, "label")
#' stopifnot(all(labels2 == 1 - labels))
#' }
#' @export
get_field <- function(dataset, field_name) {
  UseMethod("get_field")
}

#' @rdname get_field
#' @export
get_field.lgb.Dataset <- function(dataset, field_name) {

  # Check if dataset is not a dataset
  if (!lgb.is.Dataset(x = dataset)) {
    stop("get_field.lgb.Dataset(): input dataset should be an lgb.Dataset object")
  }

  return(dataset$get_field(field_name = field_name))

}

#' @name set_field
#' @title Set one attribute of a \code{lgb.Dataset} object
#' @description Set one attribute of a \code{lgb.Dataset}
#' @param dataset Object of class \code{lgb.Dataset}
#' @param field_name String with the name of the attribute to set. One of the following.
#' \itemize{
#'     \item \code{label}: label lightgbm learns from ;
#'     \item \code{weight}: to do a weight rescale ;
#'     \item{\code{group}: used for learning-to-rank tasks. An integer vector describing how to
#'         group rows together as ordered results from the same set of candidate results to be ranked.
#'         For example, if you have a 100-document dataset with \code{group = c(10, 20, 40, 10, 10, 10)},
#'         that means that you have 6 groups, where the first 10 records are in the first group,
#'         records 11-30 are in the second group, etc.}
#'     \item \code{init_score}: initial score is the base prediction lightgbm will boost from.
#' }
#' @param data The data for the field. See examples.
#' @return The \code{lgb.Dataset} you passed in.
#'
#' @examples
#' \donttest{
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' lgb.Dataset.construct(dtrain)
#'
#' labels <- lightgbm::get_field(dtrain, "label")
#' lightgbm::set_field(dtrain, "label", 1 - labels)
#'
#' labels2 <- lightgbm::get_field(dtrain, "label")
#' stopifnot(all.equal(labels2, 1 - labels))
#' }
#' @export
set_field <- function(dataset, field_name, data) {
  UseMethod("set_field")
}

#' @rdname set_field
#' @export
set_field.lgb.Dataset <- function(dataset, field_name, data) {

  if (!lgb.is.Dataset(x = dataset)) {
    stop("set_field.lgb.Dataset: input dataset should be an lgb.Dataset object")
  }

  return(invisible(dataset$set_field(field_name = field_name, data = data)))
Guolin Ke's avatar
Guolin Ke committed
1131
1132
}

1133
1134
1135
1136
#' @name lgb.Dataset.set.categorical
#' @title Set categorical feature of \code{lgb.Dataset}
#' @description Set the categorical features of an \code{lgb.Dataset} object. Use this function
#'              to tell LightGBM which features should be treated as categorical.
1137
#' @param dataset object of class \code{lgb.Dataset}
1138
1139
1140
#' @param 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").
1141
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1142
#'
1143
#' @examples
1144
#' \donttest{
1145
1146
1147
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1148
1149
1150
#' data_file <- tempfile(fileext = ".data")
#' lgb.Dataset.save(dtrain, data_file)
#' dtrain <- lgb.Dataset(data_file)
1151
#' lgb.Dataset.set.categorical(dtrain, 1L:2L)
1152
#' }
1153
1154
1155
#' @rdname lgb.Dataset.set.categorical
#' @export
lgb.Dataset.set.categorical <- function(dataset, categorical_feature) {
James Lamb's avatar
James Lamb committed
1156

1157
  if (!lgb.is.Dataset(x = dataset)) {
1158
1159
    stop("lgb.Dataset.set.categorical: input dataset should be an lgb.Dataset object")
  }
James Lamb's avatar
James Lamb committed
1160

1161
  return(invisible(dataset$set_categorical_feature(categorical_feature = categorical_feature)))
James Lamb's avatar
James Lamb committed
1162

1163
1164
}

1165
1166
1167
#' @name lgb.Dataset.set.reference
#' @title Set reference of \code{lgb.Dataset}
#' @description If you want to use validation data, you should set reference to training data
Guolin Ke's avatar
Guolin Ke committed
1168
1169
#' @param dataset object of class \code{lgb.Dataset}
#' @param reference object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
1170
#'
1171
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1172
#'
Guolin Ke's avatar
Guolin Ke committed
1173
#' @examples
1174
#' \donttest{
1175
#' # create training Dataset
1176
1177
1178
#' data(agaricus.train, package ="lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1179
1180
#'
#' # create a validation Dataset, using dtrain as a reference
1181
1182
#' data(agaricus.test, package = "lightgbm")
#' test <- agaricus.test
1183
#' dtest <- lgb.Dataset(test$data, label = test$label)
1184
#' lgb.Dataset.set.reference(dtest, dtrain)
1185
#' }
Guolin Ke's avatar
Guolin Ke committed
1186
1187
1188
#' @rdname lgb.Dataset.set.reference
#' @export
lgb.Dataset.set.reference <- function(dataset, reference) {
James Lamb's avatar
James Lamb committed
1189

1190
  if (!lgb.is.Dataset(x = dataset)) {
1191
    stop("lgb.Dataset.set.reference: input dataset should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1192
  }
James Lamb's avatar
James Lamb committed
1193

1194
  return(invisible(dataset$set_reference(reference = reference)))
Guolin Ke's avatar
Guolin Ke committed
1195
1196
}

1197
1198
1199
1200
#' @name lgb.Dataset.save
#' @title Save \code{lgb.Dataset} to a binary file
#' @description Please note that \code{init_score} is not saved in binary file.
#'              If you need it, please set it again after loading Dataset.
Guolin Ke's avatar
Guolin Ke committed
1201
1202
#' @param dataset object of class \code{lgb.Dataset}
#' @param fname object filename of output file
James Lamb's avatar
James Lamb committed
1203
#'
1204
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1205
#'
Guolin Ke's avatar
Guolin Ke committed
1206
#' @examples
1207
#' \donttest{
1208
1209
1210
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1211
#' lgb.Dataset.save(dtrain, tempfile(fileext = ".bin"))
1212
#' }
Guolin Ke's avatar
Guolin Ke committed
1213
1214
#' @export
lgb.Dataset.save <- function(dataset, fname) {
James Lamb's avatar
James Lamb committed
1215

1216
  if (!lgb.is.Dataset(x = dataset)) {
1217
    stop("lgb.Dataset.set: input dataset should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1218
  }
James Lamb's avatar
James Lamb committed
1219

1220
1221
  if (!is.character(fname)) {
    stop("lgb.Dataset.set: fname should be a character or a file connection")
Guolin Ke's avatar
Guolin Ke committed
1222
  }
James Lamb's avatar
James Lamb committed
1223

1224
  return(invisible(dataset$save_binary(fname = fname)))
Guolin Ke's avatar
Guolin Ke committed
1225
}