lgb.Dataset.R 39.7 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
    # Initialize will create a starter dataset
Guolin Ke's avatar
Guolin Ke committed
34
    initialize = function(data,
35
36
37
                          params = list(),
                          reference = NULL,
                          colnames = NULL,
38
                          categorical_feature = NULL,
39
40
41
                          predictor = NULL,
                          free_raw_data = TRUE,
                          used_indices = NULL,
42
43
44
45
                          label = NULL,
                          weight = NULL,
                          group = NULL,
                          init_score = NULL) {
James Lamb's avatar
James Lamb committed
46

47
      # validate inputs early to avoid unnecessary computation
48
      if (!(is.null(reference) || .is_Dataset(reference))) {
49
50
          stop("lgb.Dataset: If provided, reference must be a ", sQuote("lgb.Dataset"))
      }
51
      if (!(is.null(predictor) || .is_Predictor(predictor))) {
52
53
54
          stop("lgb.Dataset: If provided, predictor must be a ", sQuote("lgb.Predictor"))
      }

55
      info <- list()
56
57
58
59
60
61
62
63
64
65
66
      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
67
      }
James Lamb's avatar
James Lamb committed
68

69
70
71
72
73
74
75
      # 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
76

77
78
79
      # Setup private attributes
      private$raw_data <- data
      private$params <- params
Guolin Ke's avatar
Guolin Ke committed
80
      private$reference <- reference
81
      private$colnames <- colnames
82

83
      private$categorical_feature <- categorical_feature
84
85
      private$predictor <- predictor
      private$free_raw_data <- free_raw_data
86
      private$used_indices <- sort(used_indices, decreasing = FALSE)
87
      private$info <- info
88
      private$version <- 0L
James Lamb's avatar
James Lamb committed
89

90
91
      return(invisible(NULL))

Guolin Ke's avatar
Guolin Ke committed
92
    },
James Lamb's avatar
James Lamb committed
93

94
    create_valid = function(data,
95
96
97
98
                            label = NULL,
                            weight = NULL,
                            group = NULL,
                            init_score = NULL,
99
                            params = list()) {
100
101

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

104
      # Create new dataset
105
106
      ret <- Dataset$new(
        data = data
107
        , params = params
108
109
110
111
112
113
        , reference = self
        , colnames = private$colnames
        , categorical_feature = private$categorical_feature
        , predictor = private$predictor
        , free_raw_data = private$free_raw_data
        , used_indices = NULL
114
115
116
117
        , label = label
        , weight = weight
        , group = group
        , init_score = init_score
118
      )
James Lamb's avatar
James Lamb committed
119

120
      return(invisible(ret))
James Lamb's avatar
James Lamb committed
121

Guolin Ke's avatar
Guolin Ke committed
122
    },
James Lamb's avatar
James Lamb committed
123

124
    # Dataset constructor
Guolin Ke's avatar
Guolin Ke committed
125
    construct = function() {
James Lamb's avatar
James Lamb committed
126

127
      # Check for handle null
128
      if (!.is_null_handle(x = private$handle)) {
129
        return(invisible(self))
Guolin Ke's avatar
Guolin Ke committed
130
      }
James Lamb's avatar
James Lamb committed
131

Guolin Ke's avatar
Guolin Ke committed
132
133
      # Get feature names
      cnames <- NULL
James Lamb's avatar
James Lamb committed
134
      if (is.matrix(private$raw_data) || methods::is(private$raw_data, "dgCMatrix")) {
Guolin Ke's avatar
Guolin Ke committed
135
136
        cnames <- colnames(private$raw_data)
      }
James Lamb's avatar
James Lamb committed
137

138
      # set feature names if they do not exist
139
      if (is.null(private$colnames) && !is.null(cnames)) {
Guolin Ke's avatar
Guolin Ke committed
140
141
        private$colnames <- as.character(cnames)
      }
James Lamb's avatar
James Lamb committed
142

143
144
      # Get categorical feature index
      if (!is.null(private$categorical_feature)) {
James Lamb's avatar
James Lamb committed
145

146
        # Check for character name
147
        if (is.character(private$categorical_feature)) {
James Lamb's avatar
James Lamb committed
148

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

151
            # Provided indices, but some indices are missing?
152
            if (sum(is.na(cate_indices)) > 0L) {
153
              stop(
154
                "lgb.Dataset.construct: supplied an unknown feature in categorical_feature: "
155
156
                , sQuote(private$categorical_feature[is.na(cate_indices)])
              )
157
            }
James Lamb's avatar
James Lamb committed
158

159
          } else {
James Lamb's avatar
James Lamb committed
160

161
            # Check if more categorical features were output over the feature space
162
            data_is_not_filename <- !is.character(private$raw_data)
163
164
165
166
167
168
            if (
              data_is_not_filename
              && !is.null(private$raw_data)
              && is.null(private$used_indices)
              && max(private$categorical_feature) > ncol(private$raw_data)
            ) {
169
              stop(
170
                "lgb.Dataset.construct: supplied a too large value in categorical_feature: "
171
172
                , max(private$categorical_feature)
                , " but only "
173
                , ncol(private$raw_data)
174
175
                , " features"
              )
176
            }
James Lamb's avatar
James Lamb committed
177

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

181
          }
James Lamb's avatar
James Lamb committed
182

183
        # Store indices for categorical features
184
        private$params$categorical_feature <- cate_indices
James Lamb's avatar
James Lamb committed
185

186
      }
James Lamb's avatar
James Lamb committed
187

Guolin Ke's avatar
Guolin Ke committed
188
      # Generate parameter str
189
      params_str <- .params2str(params = private$params)
James Lamb's avatar
James Lamb committed
190

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

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

200
201
202
        if (is.null(private$raw_data)) {
          stop(paste0(
            "Attempting to create a Dataset without any raw data. "
203
            , "This can happen if the Dataset's finalizer was called or if this Dataset was saved with saveRDS(). "
204
205
206
207
208
            , "To avoid this error in the future, use lgb.Dataset.save() or "
            , "Dataset$save_binary() to save lightgbm Datasets."
          ))
        }

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

212
          handle <- .Call(
213
            LGBM_DatasetCreateFromFile_R
214
            , path.expand(private$raw_data)
215
216
217
            , params_str
            , ref_handle
          )
James Lamb's avatar
James Lamb committed
218

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

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

        } else if (methods::is(private$raw_data, "dgCMatrix")) {
232
          if (length(private$raw_data@p) > 2147483647L) {
233
234
            stop("Cannot support large CSC matrix")
          }
235
          # Are we using a dgCMatrix (sparse matrix column compressed)
236
          handle <- .Call(
237
            LGBM_DatasetCreateFromCSC_R
238
239
240
241
242
243
244
245
246
            , 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
247

Guolin Ke's avatar
Guolin Ke committed
248
        } else {
James Lamb's avatar
James Lamb committed
249

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

Guolin Ke's avatar
Guolin Ke committed
256
        }
James Lamb's avatar
James Lamb committed
257

Guolin Ke's avatar
Guolin Ke committed
258
      } else {
James Lamb's avatar
James Lamb committed
259

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

265
        # Construct subset
266
        handle <- .Call(
267
          LGBM_DatasetGetSubset_R
268
269
270
271
272
          , 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
273

Guolin Ke's avatar
Guolin Ke committed
274
      }
275
      if (.is_null_handle(x = handle)) {
Guolin Ke's avatar
Guolin Ke committed
276
277
        stop("lgb.Dataset.construct: cannot create Dataset handle")
      }
278
      # Setup class and private type
Guolin Ke's avatar
Guolin Ke committed
279
280
      class(handle) <- "lgb.Dataset.handle"
      private$handle <- handle
James Lamb's avatar
James Lamb committed
281

282
283
      # Set feature names
      if (!is.null(private$colnames)) {
284
        self$set_colnames(colnames = private$colnames)
285
      }
286

287
288
289
290
291
292
293
      # Ensure that private$colnames matches the feature names on the C++ side. This line is necessary
      # in cases like constructing from a file or from a matrix with no column names.
      private$colnames <- .Call(
          LGBM_DatasetGetFeatureNames_R
          , private$handle
      )

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

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

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

307
      }
James Lamb's avatar
James Lamb committed
308

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

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

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

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

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

Guolin Ke's avatar
Guolin Ke committed
328
      }
James Lamb's avatar
James Lamb committed
329

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

335
      return(invisible(self))
James Lamb's avatar
James Lamb committed
336

Guolin Ke's avatar
Guolin Ke committed
337
    },
James Lamb's avatar
James Lamb committed
338

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

342
      # Check for handle
343
      if (!.is_null_handle(x = private$handle)) {
James Lamb's avatar
James Lamb committed
344

345
346
        num_row <- 0L
        num_col <- 0L
James Lamb's avatar
James Lamb committed
347

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

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

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

Guolin Ke's avatar
Guolin Ke committed
369
      } else {
James Lamb's avatar
James Lamb committed
370

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

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

Guolin Ke's avatar
Guolin Ke committed
379
    },
James Lamb's avatar
James Lamb committed
380

381
382
    # Get number of bins for feature
    get_feature_num_bin = function(feature) {
383
      if (.is_null_handle(x = private$handle)) {
384
385
        stop("Cannot get number of bins in feature before constructing Dataset.")
      }
386
387
388
389
390
391
392
      if (is.character(feature)) {
        feature_name <- feature
        feature <- which(private$colnames == feature_name)
        if (length(feature) == 0L) {
          stop(sprintf("feature '%s' not found", feature_name))
        }
      }
393
394
395
396
397
398
399
400
401
402
      num_bin <- integer(1L)
      .Call(
        LGBM_DatasetGetFeatureNumBin_R
        , private$handle
        , feature - 1L
        , num_bin
      )
      return(num_bin)
    },

403
    # Get column names
Guolin Ke's avatar
Guolin Ke committed
404
    get_colnames = function() {
James Lamb's avatar
James Lamb committed
405

406
      # Check for handle
407
      if (!.is_null_handle(x = private$handle)) {
408
        private$colnames <- .Call(
409
410
          LGBM_DatasetGetFeatureNames_R
          , private$handle
411
        )
412
        return(private$colnames)
James Lamb's avatar
James Lamb committed
413
414
415

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

416
        # Check if dgCMatrix (sparse matrix column compressed)
417
        return(colnames(private$raw_data))
James Lamb's avatar
James Lamb committed
418

Guolin Ke's avatar
Guolin Ke committed
419
      } else {
James Lamb's avatar
James Lamb committed
420

421
        # Trying to work with unknown formats is not possible
422
        stop(
423
424
          "Dataset$get_colnames(): cannot get column names before dataset has been constructed, please call "
          , "lgb.Dataset.construct() explicitly"
425
        )
James Lamb's avatar
James Lamb committed
426

Guolin Ke's avatar
Guolin Ke committed
427
      }
James Lamb's avatar
James Lamb committed
428

Guolin Ke's avatar
Guolin Ke committed
429
    },
James Lamb's avatar
James Lamb committed
430

431
    # Set column names
Guolin Ke's avatar
Guolin Ke committed
432
    set_colnames = function(colnames) {
James Lamb's avatar
James Lamb committed
433

434
435
      # Check column names non-existence
      if (is.null(colnames)) {
436
        return(invisible(self))
437
      }
James Lamb's avatar
James Lamb committed
438

439
      # Check empty column names
Guolin Ke's avatar
Guolin Ke committed
440
      colnames <- as.character(colnames)
441
      if (length(colnames) == 0L) {
442
        return(invisible(self))
443
      }
James Lamb's avatar
James Lamb committed
444

445
      # Write column names
Guolin Ke's avatar
Guolin Ke committed
446
      private$colnames <- colnames
447
      if (!.is_null_handle(x = private$handle)) {
James Lamb's avatar
James Lamb committed
448

449
        # Merge names with tab separation
450
        merged_name <- paste(as.list(private$colnames), collapse = "\t")
451
452
        .Call(
          LGBM_DatasetSetFeatureNames_R
453
          , private$handle
454
          , merged_name
455
        )
James Lamb's avatar
James Lamb committed
456

Guolin Ke's avatar
Guolin Ke committed
457
      }
James Lamb's avatar
James Lamb committed
458

459
      return(invisible(self))
James Lamb's avatar
James Lamb committed
460

Guolin Ke's avatar
Guolin Ke committed
461
    },
James Lamb's avatar
James Lamb committed
462

463
    get_field = function(field_name) {
James Lamb's avatar
James Lamb committed
464

465
      # Check if attribute key is in the known attribute list
466
467
468
      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: "
469
          , toString(sQuote(.INFO_KEYS()))
470
        )
Guolin Ke's avatar
Guolin Ke committed
471
      }
James Lamb's avatar
James Lamb committed
472

473
      # Check for info name and handle
474
      if (is.null(private$info[[field_name]])) {
475

476
        if (.is_null_handle(x = private$handle)) {
477
          stop("Cannot perform Dataset$get_field() before constructing Dataset.")
478
        }
479

480
        # Get field size of info
481
        info_len <- 0L
482
483
        .Call(
          LGBM_DatasetGetFieldSize_R
484
          , private$handle
485
          , field_name
486
          , info_len
487
        )
James Lamb's avatar
James Lamb committed
488

489
        if (info_len > 0L) {
James Lamb's avatar
James Lamb committed
490

491
          # Get back fields
492
493
          if (field_name == "group") {
            ret <- integer(info_len)
494
          } else {
495
            ret <- numeric(info_len)
496
          }
James Lamb's avatar
James Lamb committed
497

498
499
          .Call(
            LGBM_DatasetGetField_R
500
            , private$handle
501
            , field_name
502
            , ret
503
          )
James Lamb's avatar
James Lamb committed
504

505
          private$info[[field_name]] <- ret
James Lamb's avatar
James Lamb committed
506

Guolin Ke's avatar
Guolin Ke committed
507
508
        }
      }
James Lamb's avatar
James Lamb committed
509

510
      return(private$info[[field_name]])
James Lamb's avatar
James Lamb committed
511

Guolin Ke's avatar
Guolin Ke committed
512
    },
James Lamb's avatar
James Lamb committed
513

514
    set_field = function(field_name, data) {
James Lamb's avatar
James Lamb committed
515

516
      # Check if attribute key is in the known attribute list
517
518
519
      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: "
520
          , toString(sQuote(.INFO_KEYS()))
521
        )
522
      }
James Lamb's avatar
James Lamb committed
523

524
      # Check for type of information
525
      data <- if (field_name == "group") {
526
        as.integer(data)
527
      } else {
528
        as.numeric(data)
529
      }
James Lamb's avatar
James Lamb committed
530

531
      # Store information privately
532
      private$info[[field_name]] <- data
James Lamb's avatar
James Lamb committed
533

534
      if (!.is_null_handle(x = private$handle) && !is.null(data)) {
James Lamb's avatar
James Lamb committed
535

536
        if (length(data) > 0L) {
James Lamb's avatar
James Lamb committed
537

538
539
          .Call(
            LGBM_DatasetSetField_R
540
            , private$handle
541
542
543
            , field_name
            , data
            , length(data)
544
          )
James Lamb's avatar
James Lamb committed
545

546
547
          private$version <- private$version + 1L

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

Guolin Ke's avatar
Guolin Ke committed
550
      }
James Lamb's avatar
James Lamb committed
551

552
      return(invisible(self))
James Lamb's avatar
James Lamb committed
553

Guolin Ke's avatar
Guolin Ke committed
554
    },
James Lamb's avatar
James Lamb committed
555

556
    slice = function(idxset) {
557

558
559
560
      return(
        Dataset$new(
          data = NULL
561
          , params = private$params
562
563
564
565
566
567
568
          , 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)
        )
569
      )
James Lamb's avatar
James Lamb committed
570

Guolin Ke's avatar
Guolin Ke committed
571
    },
James Lamb's avatar
James Lamb committed
572

573
574
575
    # [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.
576
    update_params = function(params) {
577
578
579
      if (length(params) == 0L) {
        return(invisible(self))
      }
580
      new_params <- utils::modifyList(private$params, params)
581
      if (.is_null_handle(x = private$handle)) {
582
        private$params <- new_params
583
      } else {
584
585
        tryCatch({
          .Call(
586
            LGBM_DatasetUpdateParamChecking_R
587
588
            , .params2str(params = private$params)
            , .params2str(params = new_params)
589
          )
590
          private$params <- new_params
591
592
593
        }, 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
594
          if (is.null(private$raw_data)) {
595
            stop(e)
596
597
          }

598
599
          # If updating failed but raw data is available, modify the params
          # on the R side and re-set ("deconstruct") the Dataset
600
          private$params <- new_params
601
          private$finalize()
602
        })
603
      }
604
      return(invisible(self))
James Lamb's avatar
James Lamb committed
605

Guolin Ke's avatar
Guolin Ke committed
606
    },
James Lamb's avatar
James Lamb committed
607

608
609
610
611
612
    # [description] Get only Dataset-specific parameters. This is primarily used by
    #               Booster to update its parameters based on the characteristics of
    #               a Dataset. It should not be used by other methods in this class,
    #               since "verbose" is not a Dataset parameter and needs to be passed
    #               through to avoid globally re-setting verbosity.
613
614
615
616
617
618
619
620
621
622
623
    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)
    },

624
    # Set categorical feature parameter
625
    set_categorical_feature = function(categorical_feature) {
James Lamb's avatar
James Lamb committed
626

627
628
      # Check for identical input
      if (identical(private$categorical_feature, categorical_feature)) {
629
        return(invisible(self))
630
      }
James Lamb's avatar
James Lamb committed
631

632
      # Check for empty data
633
      if (is.null(private$raw_data)) {
634
635
        stop("set_categorical_feature: cannot set categorical feature after freeing raw data,
          please set ", sQuote("free_raw_data = FALSE"), " when you construct lgb.Dataset")
636
      }
James Lamb's avatar
James Lamb committed
637

638
      # Overwrite categorical features
639
      private$categorical_feature <- categorical_feature
James Lamb's avatar
James Lamb committed
640

641
      # Finalize and return self
642
      private$finalize()
643
      return(invisible(self))
James Lamb's avatar
James Lamb committed
644

645
    },
James Lamb's avatar
James Lamb committed
646

Guolin Ke's avatar
Guolin Ke committed
647
    set_reference = function(reference) {
James Lamb's avatar
James Lamb committed
648

649
      # setting reference to this same Dataset object doesn't require any changes
650
      if (identical(private$reference, reference)) {
651
        return(invisible(self))
652
      }
James Lamb's avatar
James Lamb committed
653

654
655
      # 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
656
      if (is.null(private$raw_data)) {
657
658
        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
659
      }
James Lamb's avatar
James Lamb committed
660

661
      if (!.is_Dataset(reference)) {
662
        stop("set_reference: Can only use lgb.Dataset as a reference")
Guolin Ke's avatar
Guolin Ke committed
663
      }
James Lamb's avatar
James Lamb committed
664

665
666
667
668
669
      # 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)

670
      # Store reference
Guolin Ke's avatar
Guolin Ke committed
671
      private$reference <- reference
James Lamb's avatar
James Lamb committed
672

673
      # Finalize and return self
674
      private$finalize()
675
      return(invisible(self))
James Lamb's avatar
James Lamb committed
676

Guolin Ke's avatar
Guolin Ke committed
677
    },
James Lamb's avatar
James Lamb committed
678

679
    # Save binary model
Guolin Ke's avatar
Guolin Ke committed
680
    save_binary = function(fname) {
James Lamb's avatar
James Lamb committed
681

682
      # Store binary data
Guolin Ke's avatar
Guolin Ke committed
683
      self$construct()
684
685
      .Call(
        LGBM_DatasetSaveBinary_R
686
        , private$handle
687
        , path.expand(fname)
688
      )
689
      return(invisible(self))
Guolin Ke's avatar
Guolin Ke committed
690
    }
James Lamb's avatar
James Lamb committed
691

Guolin Ke's avatar
Guolin Ke committed
692
693
  ),
  private = list(
694
695
696
697
698
    handle = NULL,
    raw_data = NULL,
    params = list(),
    reference = NULL,
    colnames = NULL,
699
    categorical_feature = NULL,
700
701
702
703
    predictor = NULL,
    free_raw_data = TRUE,
    used_indices = NULL,
    info = NULL,
704
    version = 0L,
James Lamb's avatar
James Lamb committed
705

706
707
708
709
710
711
712
713
714
715
    # finalize() will free up the handles
    finalize = function() {
      .Call(
        LGBM_DatasetFree_R
        , private$handle
      )
      private$handle <- NULL
      return(invisible(NULL))
    },

716
    get_handle = function() {
James Lamb's avatar
James Lamb committed
717

718
      # Get handle and construct if needed
719
      if (.is_null_handle(x = private$handle)) {
720
721
        self$construct()
      }
722
      return(private$handle)
James Lamb's avatar
James Lamb committed
723

Guolin Ke's avatar
Guolin Ke committed
724
    },
James Lamb's avatar
James Lamb committed
725

Guolin Ke's avatar
Guolin Ke committed
726
    set_predictor = function(predictor) {
James Lamb's avatar
James Lamb committed
727

728
      if (identical(private$predictor, predictor)) {
729
        return(invisible(self))
730
      }
James Lamb's avatar
James Lamb committed
731

732
      # Check for empty data
Guolin Ke's avatar
Guolin Ke committed
733
      if (is.null(private$raw_data)) {
734
735
        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
736
      }
James Lamb's avatar
James Lamb committed
737

738
      # Check for empty predictor
Guolin Ke's avatar
Guolin Ke committed
739
      if (!is.null(predictor)) {
James Lamb's avatar
James Lamb committed
740

741
        # Predictor is unknown
742
        if (!.is_Predictor(predictor)) {
743
          stop("set_predictor: Can only use lgb.Predictor as predictor")
Guolin Ke's avatar
Guolin Ke committed
744
        }
James Lamb's avatar
James Lamb committed
745

Guolin Ke's avatar
Guolin Ke committed
746
      }
James Lamb's avatar
James Lamb committed
747

748
      # Store predictor
Guolin Ke's avatar
Guolin Ke committed
749
      private$predictor <- predictor
James Lamb's avatar
James Lamb committed
750

751
      # Finalize and return self
752
      private$finalize()
753
      return(invisible(self))
James Lamb's avatar
James Lamb committed
754

Guolin Ke's avatar
Guolin Ke committed
755
    }
James Lamb's avatar
James Lamb committed
756

Guolin Ke's avatar
Guolin Ke committed
757
758
759
  )
)

760
#' @title Construct \code{lgb.Dataset} object
761
762
763
764
765
766
767
#' @description LightGBM does not train on raw data.
#'              It discretizes continuous features into histogram bins, tries to
#'              combine categorical features, and automatically handles missing and
#               infinite values.
#'
#'              The \code{Dataset} class handles that preprocessing, and holds that
#'              alternative representation of the input data.
768
#' @inheritParams lgb_shared_dataset_params
769
770
771
#' @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
772
773
774
775
776
777
778
#' @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
779
#' @param colnames names of columns
780
781
782
783
784
785
786
787
#' @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
788
#'
Guolin Ke's avatar
Guolin Ke committed
789
#' @return constructed dataset
James Lamb's avatar
James Lamb committed
790
#'
Guolin Ke's avatar
Guolin Ke committed
791
#' @examples
792
#' \donttest{
793
794
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
795
796
797
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
798
799
800
#' data_file <- tempfile(fileext = ".data")
#' lgb.Dataset.save(dtrain, data_file)
#' dtrain <- lgb.Dataset(data_file)
801
#' lgb.Dataset.construct(dtrain)
802
#' }
Guolin Ke's avatar
Guolin Ke committed
803
804
#' @export
lgb.Dataset <- function(data,
805
806
807
                        params = list(),
                        reference = NULL,
                        colnames = NULL,
808
                        categorical_feature = NULL,
809
                        free_raw_data = TRUE,
810
811
812
                        label = NULL,
                        weight = NULL,
                        group = NULL,
813
                        init_score = NULL) {
814

815
816
817
818
819
820
821
822
823
824
  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
825
826
827
828
      , label = label
      , weight = weight
      , group = group
      , init_score = init_score
829
830
    ))
  )
James Lamb's avatar
James Lamb committed
831

Guolin Ke's avatar
Guolin Ke committed
832
833
}

834
835
836
#' @name lgb.Dataset.create.valid
#' @title Construct validation data
#' @description Construct validation data according to training data
837
#' @inheritParams lgb_shared_dataset_params
Guolin Ke's avatar
Guolin Ke committed
838
#' @param dataset \code{lgb.Dataset} object, training data
839
840
841
#' @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
842
843
844
845
846
#' @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
847
#'
Guolin Ke's avatar
Guolin Ke committed
848
#' @return constructed dataset
James Lamb's avatar
James Lamb committed
849
#'
Guolin Ke's avatar
Guolin Ke committed
850
#' @examples
851
#' \donttest{
852
853
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
854
855
856
857
858
859
#' 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)
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
#'
#' # 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()
895
#' }
Guolin Ke's avatar
Guolin Ke committed
896
#' @export
897
898
899
900
901
902
lgb.Dataset.create.valid <- function(dataset,
                                     data,
                                     label = NULL,
                                     weight = NULL,
                                     group = NULL,
                                     init_score = NULL,
903
                                     params = list()) {
James Lamb's avatar
James Lamb committed
904

905
  if (!.is_Dataset(x = dataset)) {
906
    stop("lgb.Dataset.create.valid: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
907
  }
James Lamb's avatar
James Lamb committed
908

909
  # Create validation dataset
910
911
912
913
914
915
916
  return(invisible(
    dataset$create_valid(
      data = data
      , label = label
      , weight = weight
      , group = group
      , init_score = init_score
917
      , params = params
918
919
    )
  ))
James Lamb's avatar
James Lamb committed
920

921
}
Guolin Ke's avatar
Guolin Ke committed
922

923
924
925
#' @name lgb.Dataset.construct
#' @title Construct Dataset explicitly
#' @description Construct Dataset explicitly
Guolin Ke's avatar
Guolin Ke committed
926
#' @param dataset Object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
927
#'
Guolin Ke's avatar
Guolin Ke committed
928
#' @examples
929
#' \donttest{
930
931
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
932
933
934
935
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' lgb.Dataset.construct(dtrain)
936
#' }
937
#' @return constructed dataset
Guolin Ke's avatar
Guolin Ke committed
938
939
#' @export
lgb.Dataset.construct <- function(dataset) {
James Lamb's avatar
James Lamb committed
940

941
  if (!.is_Dataset(x = dataset)) {
942
    stop("lgb.Dataset.construct: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
943
  }
James Lamb's avatar
James Lamb committed
944

945
  return(invisible(dataset$construct()))
James Lamb's avatar
James Lamb committed
946

Guolin Ke's avatar
Guolin Ke committed
947
948
}

949
950
#' @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
951
#' @param x Object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
952
#'
Guolin Ke's avatar
Guolin Ke committed
953
#' @return a vector of numbers of rows and of columns
James Lamb's avatar
James Lamb committed
954
#'
Guolin Ke's avatar
Guolin Ke committed
955
956
957
#' @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
958
#'
Guolin Ke's avatar
Guolin Ke committed
959
#' @examples
960
#' \donttest{
961
962
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
963
964
965
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
James Lamb's avatar
James Lamb committed
966
#'
967
968
969
#' stopifnot(nrow(dtrain) == nrow(train$data))
#' stopifnot(ncol(dtrain) == ncol(train$data))
#' stopifnot(all(dim(dtrain) == dim(train$data)))
970
#' }
Guolin Ke's avatar
Guolin Ke committed
971
972
#' @rdname dim
#' @export
973
dim.lgb.Dataset <- function(x) {
974

975
  if (!.is_Dataset(x = x)) {
976
    stop("dim.lgb.Dataset: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
977
  }
James Lamb's avatar
James Lamb committed
978

979
  return(x$dim())
James Lamb's avatar
James Lamb committed
980

Guolin Ke's avatar
Guolin Ke committed
981
982
}

983
984
985
#' @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
986
987
#' @param x object of class \code{lgb.Dataset}
#' @param value a list of two elements: the first one is ignored
988
#'              and the second one is column names
Guolin Ke's avatar
Guolin Ke committed
989
990
991
992
993
994
#'
#' @details
#' Generic \code{dimnames} methods are used by \code{colnames}.
#' Since row names are irrelevant, it is recommended to use \code{colnames} directly.
#'
#' @examples
995
#' \donttest{
996
997
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
998
999
1000
1001
1002
1003
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' lgb.Dataset.construct(dtrain)
#' dimnames(dtrain)
#' colnames(dtrain)
1004
#' colnames(dtrain) <- make.names(seq_len(ncol(train$data)))
1005
#' print(dtrain, verbose = TRUE)
1006
#' }
Guolin Ke's avatar
Guolin Ke committed
1007
#' @rdname dimnames.lgb.Dataset
1008
#' @return A list with the dimension names of the dataset
Guolin Ke's avatar
Guolin Ke committed
1009
1010
#' @export
dimnames.lgb.Dataset <- function(x) {
James Lamb's avatar
James Lamb committed
1011

1012
  if (!.is_Dataset(x = x)) {
1013
    stop("dimnames.lgb.Dataset: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1014
  }
James Lamb's avatar
James Lamb committed
1015

1016
  # Return dimension names
1017
  return(list(NULL, x$get_colnames()))
James Lamb's avatar
James Lamb committed
1018

Guolin Ke's avatar
Guolin Ke committed
1019
1020
1021
1022
1023
}

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

1025
  # Check if invalid element list
1026
  if (!identical(class(value), "list") || length(value) != 2L) {
1027
    stop("invalid ", sQuote("value"), " given: must be a list of two elements")
1028
  }
James Lamb's avatar
James Lamb committed
1029

1030
1031
1032
1033
  # Check for unknown row names
  if (!is.null(value[[1L]])) {
    stop("lgb.Dataset does not have rownames")
  }
James Lamb's avatar
James Lamb committed
1034

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

1037
    x$set_colnames(colnames = NULL)
Guolin Ke's avatar
Guolin Ke committed
1038
    return(x)
James Lamb's avatar
James Lamb committed
1039

1040
  }
James Lamb's avatar
James Lamb committed
1041

1042
  # Check for unmatching column size
1043
  if (ncol(x) != length(value[[2L]])) {
1044
1045
    stop(
      "can't assign "
1046
      , sQuote(length(value[[2L]]))
1047
1048
1049
1050
      , " colnames to an lgb.Dataset with "
      , sQuote(ncol(x))
      , " columns"
    )
Guolin Ke's avatar
Guolin Ke committed
1051
  }
James Lamb's avatar
James Lamb committed
1052

1053
  # Set column names properly, and return
1054
  x$set_colnames(colnames = value[[2L]])
1055
  return(x)
James Lamb's avatar
James Lamb committed
1056

Guolin Ke's avatar
Guolin Ke committed
1057
1058
}

1059
1060
1061
#' @title Slice a dataset
#' @description Get a new \code{lgb.Dataset} containing the specified rows of
#'              original \code{lgb.Dataset} object
James Lamb's avatar
James Lamb committed
1062
1063
1064
#'
#'              \emph{Renamed from} \code{slice()} \emph{in 4.4.0}
#'
Nikita Titov's avatar
Nikita Titov committed
1065
#' @param dataset Object of class \code{lgb.Dataset}
1066
#' @param idxset an integer vector of indices of rows needed
Guolin Ke's avatar
Guolin Ke committed
1067
#' @return constructed sub dataset
James Lamb's avatar
James Lamb committed
1068
#'
Guolin Ke's avatar
Guolin Ke committed
1069
#' @examples
1070
#' \donttest{
1071
1072
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
1073
1074
1075
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
James Lamb's avatar
James Lamb committed
1076
#'
1077
#' dsub <- lgb.slice.Dataset(dtrain, seq_len(42L))
1078
#' lgb.Dataset.construct(dsub)
1079
#' labels <- lightgbm::get_field(dsub, "label")
1080
#' }
Guolin Ke's avatar
Guolin Ke committed
1081
#' @export
1082
lgb.slice.Dataset <- function(dataset, idxset) {
James Lamb's avatar
James Lamb committed
1083

1084
  if (!.is_Dataset(x = dataset)) {
1085
    stop("lgb.slice.Dataset: input dataset should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1086
  }
James Lamb's avatar
James Lamb committed
1087

1088
  return(invisible(dataset$slice(idxset = idxset)))
James Lamb's avatar
James Lamb committed
1089

Guolin Ke's avatar
Guolin Ke committed
1090
1091
}

1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
#' @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{
1111
1112
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
#' 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
1134
  if (!.is_Dataset(x = dataset)) {
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
    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{
1162
1163
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
#' 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) {

1184
  if (!.is_Dataset(x = dataset)) {
1185
1186
1187
1188
    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
1189
1190
}

1191
1192
1193
1194
#' @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.
1195
#' @param dataset object of class \code{lgb.Dataset}
1196
1197
1198
#' @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").
1199
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1200
#'
1201
#' @examples
1202
#' \donttest{
1203
1204
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
1205
1206
1207
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1208
1209
1210
#' data_file <- tempfile(fileext = ".data")
#' lgb.Dataset.save(dtrain, data_file)
#' dtrain <- lgb.Dataset(data_file)
1211
#' lgb.Dataset.set.categorical(dtrain, 1L:2L)
1212
#' }
1213
1214
1215
#' @rdname lgb.Dataset.set.categorical
#' @export
lgb.Dataset.set.categorical <- function(dataset, categorical_feature) {
James Lamb's avatar
James Lamb committed
1216

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

1221
  return(invisible(dataset$set_categorical_feature(categorical_feature = categorical_feature)))
James Lamb's avatar
James Lamb committed
1222

1223
1224
}

1225
1226
1227
#' @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
1228
1229
#' @param dataset object of class \code{lgb.Dataset}
#' @param reference object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
1230
#'
1231
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1232
#'
Guolin Ke's avatar
Guolin Ke committed
1233
#' @examples
1234
#' \donttest{
1235
1236
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
1237
#' # create training Dataset
1238
1239
1240
#' data(agaricus.train, package ="lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1241
1242
#'
#' # create a validation Dataset, using dtrain as a reference
1243
1244
#' data(agaricus.test, package = "lightgbm")
#' test <- agaricus.test
1245
#' dtest <- lgb.Dataset(test$data, label = test$label)
1246
#' lgb.Dataset.set.reference(dtest, dtrain)
1247
#' }
Guolin Ke's avatar
Guolin Ke committed
1248
1249
1250
#' @rdname lgb.Dataset.set.reference
#' @export
lgb.Dataset.set.reference <- function(dataset, reference) {
James Lamb's avatar
James Lamb committed
1251

1252
  if (!.is_Dataset(x = dataset)) {
1253
    stop("lgb.Dataset.set.reference: input dataset should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1254
  }
James Lamb's avatar
James Lamb committed
1255

1256
  return(invisible(dataset$set_reference(reference = reference)))
Guolin Ke's avatar
Guolin Ke committed
1257
1258
}

1259
1260
1261
1262
#' @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
1263
1264
#' @param dataset object of class \code{lgb.Dataset}
#' @param fname object filename of output file
James Lamb's avatar
James Lamb committed
1265
#'
1266
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1267
#'
Guolin Ke's avatar
Guolin Ke committed
1268
#' @examples
1269
#' \donttest{
1270
1271
#' \dontshow{setLGBMthreads(2L)}
#' \dontshow{data.table::setDTthreads(1L)}
1272
1273
1274
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1275
#' lgb.Dataset.save(dtrain, tempfile(fileext = ".bin"))
1276
#' }
Guolin Ke's avatar
Guolin Ke committed
1277
1278
#' @export
lgb.Dataset.save <- function(dataset, fname) {
James Lamb's avatar
James Lamb committed
1279

1280
  if (!.is_Dataset(x = dataset)) {
1281
    stop("lgb.Dataset.save: input dataset should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1282
  }
James Lamb's avatar
James Lamb committed
1283

1284
  if (!is.character(fname)) {
1285
    stop("lgb.Dataset.save: fname should be a character or a file connection")
Guolin Ke's avatar
Guolin Ke committed
1286
  }
James Lamb's avatar
James Lamb committed
1287

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