lgb.Dataset.R 38.5 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) || .is_Dataset(reference))) {
59
60
          stop("lgb.Dataset: If provided, reference must be a ", sQuote("lgb.Dataset"))
      }
61
      if (!(is.null(predictor) || .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

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

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 (!.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
              stop(
164
                "lgb.Dataset.construct: supplied an unknown feature in categorical_feature: "
165
166
                , 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
173
            data_is_not_filename <- !is.character(private$raw_data)
            if (data_is_not_filename && max(private$categorical_feature) > ncol(private$raw_data)) {
174
              stop(
175
                "lgb.Dataset.construct: supplied a too large value in categorical_feature: "
176
177
                , max(private$categorical_feature)
                , " but only "
178
                , ncol(private$raw_data)
179
180
                , " features"
              )
181
            }
James Lamb's avatar
James Lamb committed
182

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

186
          }
James Lamb's avatar
James Lamb committed
187

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

191
      }
James Lamb's avatar
James Lamb committed
192

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

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

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

205
206
207
208
209
210
211
212
213
        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."
          ))
        }

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

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

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

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

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

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

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

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

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

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

270
        # Construct subset
271
        handle <- .Call(
272
          LGBM_DatasetGetSubset_R
273
274
275
276
277
          , 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
278

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

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

292
293
294
295
296
297
298
      # 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
      )

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

302
        # Setup initial scores
303
        init_score <- private$predictor$predict(
304
          data = private$raw_data
305
306
          , rawscore = TRUE
        )
James Lamb's avatar
James Lamb committed
307

308
        # Not needed to transpose, for is col_marjor
Guolin Ke's avatar
Guolin Ke committed
309
310
        init_score <- as.vector(init_score)
        private$info$init_score <- init_score
James Lamb's avatar
James Lamb committed
311

312
      }
James Lamb's avatar
James Lamb committed
313

314
315
316
      # Should we free raw data?
      if (isTRUE(private$free_raw_data)) {
        private$raw_data <- NULL
Guolin Ke's avatar
Guolin Ke committed
317
      }
James Lamb's avatar
James Lamb committed
318

319
      # Get private information
320
      if (length(private$info) > 0L) {
James Lamb's avatar
James Lamb committed
321

322
        # Set infos
323
        for (i in seq_along(private$info)) {
James Lamb's avatar
James Lamb committed
324

Guolin Ke's avatar
Guolin Ke committed
325
          p <- private$info[i]
326
327
328
329
          self$set_field(
            field_name = names(p)
            , data = p[[1L]]
          )
James Lamb's avatar
James Lamb committed
330

Guolin Ke's avatar
Guolin Ke committed
331
        }
James Lamb's avatar
James Lamb committed
332

Guolin Ke's avatar
Guolin Ke committed
333
      }
James Lamb's avatar
James Lamb committed
334

335
      # Get label information existence
336
      if (is.null(self$get_field(field_name = "label"))) {
Guolin Ke's avatar
Guolin Ke committed
337
338
        stop("lgb.Dataset.construct: label should be set")
      }
James Lamb's avatar
James Lamb committed
339

340
      return(invisible(self))
James Lamb's avatar
James Lamb committed
341

Guolin Ke's avatar
Guolin Ke committed
342
    },
James Lamb's avatar
James Lamb committed
343

344
    # Dimension function
Guolin Ke's avatar
Guolin Ke committed
345
    dim = function() {
James Lamb's avatar
James Lamb committed
346

347
      # Check for handle
348
      if (!.is_null_handle(x = private$handle)) {
James Lamb's avatar
James Lamb committed
349

350
351
        num_row <- 0L
        num_col <- 0L
James Lamb's avatar
James Lamb committed
352

353
        # Get numeric data and numeric features
354
355
356
357
358
359
360
361
362
363
        .Call(
          LGBM_DatasetGetNumData_R
          , private$handle
          , num_row
        )
        .Call(
          LGBM_DatasetGetNumFeature_R
          , private$handle
          , num_col
        )
364
        return(
365
          c(num_row, num_col)
366
        )
James Lamb's avatar
James Lamb committed
367
368
369

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

370
        # Check if dgCMatrix (sparse matrix column compressed)
371
        # NOTE: requires Matrix package
372
        return(dim(private$raw_data))
James Lamb's avatar
James Lamb committed
373

Guolin Ke's avatar
Guolin Ke committed
374
      } else {
James Lamb's avatar
James Lamb committed
375

376
        # Trying to work with unknown dimensions is not possible
377
378
379
380
        stop(
          "dim: cannot get dimensions before dataset has been constructed, "
          , "please call lgb.Dataset.construct explicitly"
        )
James Lamb's avatar
James Lamb committed
381

Guolin Ke's avatar
Guolin Ke committed
382
      }
James Lamb's avatar
James Lamb committed
383

Guolin Ke's avatar
Guolin Ke committed
384
    },
James Lamb's avatar
James Lamb committed
385

386
387
    # Get number of bins for feature
    get_feature_num_bin = function(feature) {
388
      if (.is_null_handle(x = private$handle)) {
389
390
        stop("Cannot get number of bins in feature before constructing Dataset.")
      }
391
392
393
394
395
396
397
      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))
        }
      }
398
399
400
401
402
403
404
405
406
407
      num_bin <- integer(1L)
      .Call(
        LGBM_DatasetGetFeatureNumBin_R
        , private$handle
        , feature - 1L
        , num_bin
      )
      return(num_bin)
    },

408
    # Get column names
Guolin Ke's avatar
Guolin Ke committed
409
    get_colnames = function() {
James Lamb's avatar
James Lamb committed
410

411
      # Check for handle
412
      if (!.is_null_handle(x = private$handle)) {
413
        private$colnames <- .Call(
414
415
          LGBM_DatasetGetFeatureNames_R
          , private$handle
416
        )
417
        return(private$colnames)
James Lamb's avatar
James Lamb committed
418
419
420

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

421
        # Check if dgCMatrix (sparse matrix column compressed)
422
        return(colnames(private$raw_data))
James Lamb's avatar
James Lamb committed
423

Guolin Ke's avatar
Guolin Ke committed
424
      } else {
James Lamb's avatar
James Lamb committed
425

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

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

Guolin Ke's avatar
Guolin Ke committed
434
    },
James Lamb's avatar
James Lamb committed
435

436
    # Set column names
Guolin Ke's avatar
Guolin Ke committed
437
    set_colnames = function(colnames) {
James Lamb's avatar
James Lamb committed
438

439
440
      # Check column names non-existence
      if (is.null(colnames)) {
441
        return(invisible(self))
442
      }
James Lamb's avatar
James Lamb committed
443

444
      # Check empty column names
Guolin Ke's avatar
Guolin Ke committed
445
      colnames <- as.character(colnames)
446
      if (length(colnames) == 0L) {
447
        return(invisible(self))
448
      }
James Lamb's avatar
James Lamb committed
449

450
      # Write column names
Guolin Ke's avatar
Guolin Ke committed
451
      private$colnames <- colnames
452
      if (!.is_null_handle(x = private$handle)) {
James Lamb's avatar
James Lamb committed
453

454
        # Merge names with tab separation
Guolin Ke's avatar
Guolin Ke committed
455
        merged_name <- paste0(as.list(private$colnames), collapse = "\t")
456
457
        .Call(
          LGBM_DatasetSetFeatureNames_R
458
          , private$handle
459
          , merged_name
460
        )
James Lamb's avatar
James Lamb committed
461

Guolin Ke's avatar
Guolin Ke committed
462
      }
James Lamb's avatar
James Lamb committed
463

464
      return(invisible(self))
James Lamb's avatar
James Lamb committed
465

Guolin Ke's avatar
Guolin Ke committed
466
    },
James Lamb's avatar
James Lamb committed
467

468
    get_field = function(field_name) {
James Lamb's avatar
James Lamb committed
469

470
      # Check if attribute key is in the known attribute list
471
472
473
      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: "
474
          , toString(sQuote(.INFO_KEYS()))
475
        )
Guolin Ke's avatar
Guolin Ke committed
476
      }
James Lamb's avatar
James Lamb committed
477

478
      # Check for info name and handle
479
      if (is.null(private$info[[field_name]])) {
480

481
        if (.is_null_handle(x = private$handle)) {
482
          stop("Cannot perform Dataset$get_field() before constructing Dataset.")
483
        }
484

485
        # Get field size of info
486
        info_len <- 0L
487
488
        .Call(
          LGBM_DatasetGetFieldSize_R
489
          , private$handle
490
          , field_name
491
          , info_len
492
        )
James Lamb's avatar
James Lamb committed
493

494
        if (info_len > 0L) {
James Lamb's avatar
James Lamb committed
495

496
          # Get back fields
497
498
          if (field_name == "group") {
            ret <- integer(info_len)
499
          } else {
500
            ret <- numeric(info_len)
501
          }
James Lamb's avatar
James Lamb committed
502

503
504
          .Call(
            LGBM_DatasetGetField_R
505
            , private$handle
506
            , field_name
507
            , ret
508
          )
James Lamb's avatar
James Lamb committed
509

510
          private$info[[field_name]] <- ret
James Lamb's avatar
James Lamb committed
511

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

515
      return(private$info[[field_name]])
James Lamb's avatar
James Lamb committed
516

Guolin Ke's avatar
Guolin Ke committed
517
    },
James Lamb's avatar
James Lamb committed
518

519
    set_field = function(field_name, data) {
James Lamb's avatar
James Lamb committed
520

521
      # Check if attribute key is in the known attribute list
522
523
524
      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: "
525
          , toString(sQuote(.INFO_KEYS()))
526
        )
527
      }
James Lamb's avatar
James Lamb committed
528

529
      # Check for type of information
530
      data <- if (field_name == "group") {
531
        as.integer(data)
532
      } else {
533
        as.numeric(data)
534
      }
James Lamb's avatar
James Lamb committed
535

536
      # Store information privately
537
      private$info[[field_name]] <- data
James Lamb's avatar
James Lamb committed
538

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

541
        if (length(data) > 0L) {
James Lamb's avatar
James Lamb committed
542

543
544
          .Call(
            LGBM_DatasetSetField_R
545
            , private$handle
546
547
548
            , field_name
            , data
            , length(data)
549
          )
James Lamb's avatar
James Lamb committed
550

551
552
          private$version <- private$version + 1L

Guolin Ke's avatar
Guolin Ke committed
553
        }
James Lamb's avatar
James Lamb committed
554

Guolin Ke's avatar
Guolin Ke committed
555
      }
James Lamb's avatar
James Lamb committed
556

557
      return(invisible(self))
James Lamb's avatar
James Lamb committed
558

Guolin Ke's avatar
Guolin Ke committed
559
    },
James Lamb's avatar
James Lamb committed
560

561
    slice = function(idxset) {
562

563
564
565
      return(
        Dataset$new(
          data = NULL
566
          , params = private$params
567
568
569
570
571
572
573
          , 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)
        )
574
      )
James Lamb's avatar
James Lamb committed
575

Guolin Ke's avatar
Guolin Ke committed
576
    },
James Lamb's avatar
James Lamb committed
577

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

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

Guolin Ke's avatar
Guolin Ke committed
611
    },
James Lamb's avatar
James Lamb committed
612

613
614
615
616
617
    # [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.
618
619
620
621
622
623
624
625
626
627
628
    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)
    },

629
    # Set categorical feature parameter
630
    set_categorical_feature = function(categorical_feature) {
James Lamb's avatar
James Lamb committed
631

632
633
      # Check for identical input
      if (identical(private$categorical_feature, categorical_feature)) {
634
        return(invisible(self))
635
      }
James Lamb's avatar
James Lamb committed
636

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

643
      # Overwrite categorical features
644
      private$categorical_feature <- categorical_feature
James Lamb's avatar
James Lamb committed
645

646
      # Finalize and return self
647
      self$finalize()
648
      return(invisible(self))
James Lamb's avatar
James Lamb committed
649

650
    },
James Lamb's avatar
James Lamb committed
651

Guolin Ke's avatar
Guolin Ke committed
652
    set_reference = function(reference) {
James Lamb's avatar
James Lamb committed
653

654
      # setting reference to this same Dataset object doesn't require any changes
655
      if (identical(private$reference, reference)) {
656
        return(invisible(self))
657
      }
James Lamb's avatar
James Lamb committed
658

659
660
      # 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
661
      if (is.null(private$raw_data)) {
662
663
        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
664
      }
James Lamb's avatar
James Lamb committed
665

666
      if (!.is_Dataset(reference)) {
667
        stop("set_reference: Can only use lgb.Dataset as a reference")
Guolin Ke's avatar
Guolin Ke committed
668
      }
James Lamb's avatar
James Lamb committed
669

670
671
672
673
674
      # 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)

675
      # Store reference
Guolin Ke's avatar
Guolin Ke committed
676
      private$reference <- reference
James Lamb's avatar
James Lamb committed
677

678
      # Finalize and return self
Guolin Ke's avatar
Guolin Ke committed
679
      self$finalize()
680
      return(invisible(self))
James Lamb's avatar
James Lamb committed
681

Guolin Ke's avatar
Guolin Ke committed
682
    },
James Lamb's avatar
James Lamb committed
683

684
    # Save binary model
Guolin Ke's avatar
Guolin Ke committed
685
    save_binary = function(fname) {
James Lamb's avatar
James Lamb committed
686

687
      # Store binary data
Guolin Ke's avatar
Guolin Ke committed
688
      self$construct()
689
690
      .Call(
        LGBM_DatasetSaveBinary_R
691
        , private$handle
692
        , path.expand(fname)
693
      )
694
      return(invisible(self))
Guolin Ke's avatar
Guolin Ke committed
695
    }
James Lamb's avatar
James Lamb committed
696

Guolin Ke's avatar
Guolin Ke committed
697
698
  ),
  private = list(
699
700
701
702
703
    handle = NULL,
    raw_data = NULL,
    params = list(),
    reference = NULL,
    colnames = NULL,
704
    categorical_feature = NULL,
705
706
707
708
    predictor = NULL,
    free_raw_data = TRUE,
    used_indices = NULL,
    info = NULL,
709
    version = 0L,
James Lamb's avatar
James Lamb committed
710

711
    get_handle = function() {
James Lamb's avatar
James Lamb committed
712

713
      # Get handle and construct if needed
714
      if (.is_null_handle(x = private$handle)) {
715
716
        self$construct()
      }
717
      return(private$handle)
James Lamb's avatar
James Lamb committed
718

Guolin Ke's avatar
Guolin Ke committed
719
    },
James Lamb's avatar
James Lamb committed
720

Guolin Ke's avatar
Guolin Ke committed
721
    set_predictor = function(predictor) {
James Lamb's avatar
James Lamb committed
722

723
      if (identical(private$predictor, predictor)) {
724
        return(invisible(self))
725
      }
James Lamb's avatar
James Lamb committed
726

727
      # Check for empty data
Guolin Ke's avatar
Guolin Ke committed
728
      if (is.null(private$raw_data)) {
729
730
        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
731
      }
James Lamb's avatar
James Lamb committed
732

733
      # Check for empty predictor
Guolin Ke's avatar
Guolin Ke committed
734
      if (!is.null(predictor)) {
James Lamb's avatar
James Lamb committed
735

736
        # Predictor is unknown
737
        if (!.is_Predictor(predictor)) {
738
          stop("set_predictor: Can only use lgb.Predictor as predictor")
Guolin Ke's avatar
Guolin Ke committed
739
        }
James Lamb's avatar
James Lamb committed
740

Guolin Ke's avatar
Guolin Ke committed
741
      }
James Lamb's avatar
James Lamb committed
742

743
      # Store predictor
Guolin Ke's avatar
Guolin Ke committed
744
      private$predictor <- predictor
James Lamb's avatar
James Lamb committed
745

746
      # Finalize and return self
Guolin Ke's avatar
Guolin Ke committed
747
      self$finalize()
748
      return(invisible(self))
James Lamb's avatar
James Lamb committed
749

Guolin Ke's avatar
Guolin Ke committed
750
    }
James Lamb's avatar
James Lamb committed
751

Guolin Ke's avatar
Guolin Ke committed
752
753
754
  )
)

755
756
757
#' @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}).
758
#' @inheritParams lgb_shared_dataset_params
759
760
761
#' @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
762
763
764
765
766
767
768
#' @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
769
#' @param colnames names of columns
770
771
772
773
774
775
776
777
#' @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
778
#'
Guolin Ke's avatar
Guolin Ke committed
779
#' @return constructed dataset
James Lamb's avatar
James Lamb committed
780
#'
Guolin Ke's avatar
Guolin Ke committed
781
#' @examples
782
#' \donttest{
783
784
785
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
786
787
788
#' data_file <- tempfile(fileext = ".data")
#' lgb.Dataset.save(dtrain, data_file)
#' dtrain <- lgb.Dataset(data_file)
789
#' lgb.Dataset.construct(dtrain)
790
#' }
Guolin Ke's avatar
Guolin Ke committed
791
792
#' @export
lgb.Dataset <- function(data,
793
794
795
                        params = list(),
                        reference = NULL,
                        colnames = NULL,
796
                        categorical_feature = NULL,
797
                        free_raw_data = TRUE,
798
799
800
                        label = NULL,
                        weight = NULL,
                        group = NULL,
801
                        init_score = NULL) {
802

803
804
805
806
807
808
809
810
811
812
  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
813
814
815
816
      , label = label
      , weight = weight
      , group = group
      , init_score = init_score
817
818
    ))
  )
James Lamb's avatar
James Lamb committed
819

Guolin Ke's avatar
Guolin Ke committed
820
821
}

822
823
824
#' @name lgb.Dataset.create.valid
#' @title Construct validation data
#' @description Construct validation data according to training data
825
#' @inheritParams lgb_shared_dataset_params
Guolin Ke's avatar
Guolin Ke committed
826
#' @param dataset \code{lgb.Dataset} object, training data
827
828
829
#' @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
830
831
832
833
834
#' @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
835
#'
Guolin Ke's avatar
Guolin Ke committed
836
#' @return constructed dataset
James Lamb's avatar
James Lamb committed
837
#'
Guolin Ke's avatar
Guolin Ke committed
838
#' @examples
839
#' \donttest{
840
841
842
843
844
845
#' 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)
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
#'
#' # 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()
881
#' }
Guolin Ke's avatar
Guolin Ke committed
882
#' @export
883
884
885
886
887
888
lgb.Dataset.create.valid <- function(dataset,
                                     data,
                                     label = NULL,
                                     weight = NULL,
                                     group = NULL,
                                     init_score = NULL,
889
                                     params = list()) {
James Lamb's avatar
James Lamb committed
890

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

895
  # Create validation dataset
896
897
898
899
900
901
902
  return(invisible(
    dataset$create_valid(
      data = data
      , label = label
      , weight = weight
      , group = group
      , init_score = init_score
903
      , params = params
904
905
    )
  ))
James Lamb's avatar
James Lamb committed
906

907
}
Guolin Ke's avatar
Guolin Ke committed
908

909
910
911
#' @name lgb.Dataset.construct
#' @title Construct Dataset explicitly
#' @description Construct Dataset explicitly
Guolin Ke's avatar
Guolin Ke committed
912
#' @param dataset Object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
913
#'
Guolin Ke's avatar
Guolin Ke committed
914
#' @examples
915
#' \donttest{
916
917
918
919
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' lgb.Dataset.construct(dtrain)
920
#' }
921
#' @return constructed dataset
Guolin Ke's avatar
Guolin Ke committed
922
923
#' @export
lgb.Dataset.construct <- function(dataset) {
James Lamb's avatar
James Lamb committed
924

925
  if (!.is_Dataset(x = dataset)) {
926
    stop("lgb.Dataset.construct: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
927
  }
James Lamb's avatar
James Lamb committed
928

929
  return(invisible(dataset$construct()))
James Lamb's avatar
James Lamb committed
930

Guolin Ke's avatar
Guolin Ke committed
931
932
}

933
934
#' @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
935
#' @param x Object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
936
#'
Guolin Ke's avatar
Guolin Ke committed
937
#' @return a vector of numbers of rows and of columns
James Lamb's avatar
James Lamb committed
938
#'
Guolin Ke's avatar
Guolin Ke committed
939
940
941
#' @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
942
#'
Guolin Ke's avatar
Guolin Ke committed
943
#' @examples
944
#' \donttest{
945
946
947
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
James Lamb's avatar
James Lamb committed
948
#'
949
950
951
#' stopifnot(nrow(dtrain) == nrow(train$data))
#' stopifnot(ncol(dtrain) == ncol(train$data))
#' stopifnot(all(dim(dtrain) == dim(train$data)))
952
#' }
Guolin Ke's avatar
Guolin Ke committed
953
954
#' @rdname dim
#' @export
955
dim.lgb.Dataset <- function(x) {
956

957
  if (!.is_Dataset(x = x)) {
958
    stop("dim.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(x$dim())
James Lamb's avatar
James Lamb committed
962

Guolin Ke's avatar
Guolin Ke committed
963
964
}

965
966
967
#' @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
968
969
#' @param x object of class \code{lgb.Dataset}
#' @param value a list of two elements: the first one is ignored
970
#'              and the second one is column names
Guolin Ke's avatar
Guolin Ke committed
971
972
973
974
975
976
#'
#' @details
#' Generic \code{dimnames} methods are used by \code{colnames}.
#' Since row names are irrelevant, it is recommended to use \code{colnames} directly.
#'
#' @examples
977
#' \donttest{
978
979
980
981
982
983
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
#' lgb.Dataset.construct(dtrain)
#' dimnames(dtrain)
#' colnames(dtrain)
984
#' colnames(dtrain) <- make.names(seq_len(ncol(train$data)))
985
#' print(dtrain, verbose = TRUE)
986
#' }
Guolin Ke's avatar
Guolin Ke committed
987
#' @rdname dimnames.lgb.Dataset
988
#' @return A list with the dimension names of the dataset
Guolin Ke's avatar
Guolin Ke committed
989
990
#' @export
dimnames.lgb.Dataset <- function(x) {
James Lamb's avatar
James Lamb committed
991

992
  if (!.is_Dataset(x = x)) {
993
    stop("dimnames.lgb.Dataset: input data should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
994
  }
James Lamb's avatar
James Lamb committed
995

996
  # Return dimension names
997
  return(list(NULL, x$get_colnames()))
James Lamb's avatar
James Lamb committed
998

Guolin Ke's avatar
Guolin Ke committed
999
1000
1001
1002
1003
}

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

1005
  # Check if invalid element list
1006
  if (!identical(class(value), "list") || length(value) != 2L) {
1007
    stop("invalid ", sQuote("value"), " given: must be a list of two elements")
1008
  }
James Lamb's avatar
James Lamb committed
1009

1010
1011
1012
1013
  # Check for unknown row names
  if (!is.null(value[[1L]])) {
    stop("lgb.Dataset does not have rownames")
  }
James Lamb's avatar
James Lamb committed
1014

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

1017
    x$set_colnames(colnames = NULL)
Guolin Ke's avatar
Guolin Ke committed
1018
    return(x)
James Lamb's avatar
James Lamb committed
1019

1020
  }
James Lamb's avatar
James Lamb committed
1021

1022
  # Check for unmatching column size
1023
  if (ncol(x) != length(value[[2L]])) {
1024
1025
    stop(
      "can't assign "
1026
      , sQuote(length(value[[2L]]))
1027
1028
1029
1030
      , " colnames to an lgb.Dataset with "
      , sQuote(ncol(x))
      , " columns"
    )
Guolin Ke's avatar
Guolin Ke committed
1031
  }
James Lamb's avatar
James Lamb committed
1032

1033
  # Set column names properly, and return
1034
  x$set_colnames(colnames = value[[2L]])
1035
  return(x)
James Lamb's avatar
James Lamb committed
1036

Guolin Ke's avatar
Guolin Ke committed
1037
1038
}

1039
1040
1041
#' @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
1042
#' @param dataset Object of class \code{lgb.Dataset}
1043
#' @param idxset an integer vector of indices of rows needed
Guolin Ke's avatar
Guolin Ke committed
1044
#' @return constructed sub dataset
James Lamb's avatar
James Lamb committed
1045
#'
Guolin Ke's avatar
Guolin Ke committed
1046
#' @examples
1047
#' \donttest{
1048
1049
1050
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
James Lamb's avatar
James Lamb committed
1051
#'
1052
#' dsub <- lightgbm::slice(dtrain, seq_len(42L))
1053
#' lgb.Dataset.construct(dsub)
1054
#' labels <- lightgbm::get_field(dsub, "label")
1055
#' }
Guolin Ke's avatar
Guolin Ke committed
1056
#' @export
1057
slice <- function(dataset, idxset) {
1058
1059
  UseMethod("slice")
}
Guolin Ke's avatar
Guolin Ke committed
1060
1061
1062

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

1065
  if (!.is_Dataset(x = dataset)) {
1066
    stop("slice.lgb.Dataset: input dataset should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1067
  }
James Lamb's avatar
James Lamb committed
1068

1069
  return(invisible(dataset$slice(idxset = idxset)))
James Lamb's avatar
James Lamb committed
1070

Guolin Ke's avatar
Guolin Ke committed
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
#' @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
1113
  if (!.is_Dataset(x = dataset)) {
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
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
    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) {

1161
  if (!.is_Dataset(x = dataset)) {
1162
1163
1164
1165
    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
1166
1167
}

1168
1169
1170
1171
#' @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.
1172
#' @param dataset object of class \code{lgb.Dataset}
1173
1174
1175
#' @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").
1176
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1177
#'
1178
#' @examples
1179
#' \donttest{
1180
1181
1182
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1183
1184
1185
#' data_file <- tempfile(fileext = ".data")
#' lgb.Dataset.save(dtrain, data_file)
#' dtrain <- lgb.Dataset(data_file)
1186
#' lgb.Dataset.set.categorical(dtrain, 1L:2L)
1187
#' }
1188
1189
1190
#' @rdname lgb.Dataset.set.categorical
#' @export
lgb.Dataset.set.categorical <- function(dataset, categorical_feature) {
James Lamb's avatar
James Lamb committed
1191

1192
  if (!.is_Dataset(x = dataset)) {
1193
1194
    stop("lgb.Dataset.set.categorical: input dataset should be an lgb.Dataset object")
  }
James Lamb's avatar
James Lamb committed
1195

1196
  return(invisible(dataset$set_categorical_feature(categorical_feature = categorical_feature)))
James Lamb's avatar
James Lamb committed
1197

1198
1199
}

1200
1201
1202
#' @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
1203
1204
#' @param dataset object of class \code{lgb.Dataset}
#' @param reference object of class \code{lgb.Dataset}
James Lamb's avatar
James Lamb committed
1205
#'
1206
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1207
#'
Guolin Ke's avatar
Guolin Ke committed
1208
#' @examples
1209
#' \donttest{
1210
#' # create training Dataset
1211
1212
1213
#' data(agaricus.train, package ="lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1214
1215
#'
#' # create a validation Dataset, using dtrain as a reference
1216
1217
#' data(agaricus.test, package = "lightgbm")
#' test <- agaricus.test
1218
#' dtest <- lgb.Dataset(test$data, label = test$label)
1219
#' lgb.Dataset.set.reference(dtest, dtrain)
1220
#' }
Guolin Ke's avatar
Guolin Ke committed
1221
1222
1223
#' @rdname lgb.Dataset.set.reference
#' @export
lgb.Dataset.set.reference <- function(dataset, reference) {
James Lamb's avatar
James Lamb committed
1224

1225
  if (!.is_Dataset(x = dataset)) {
1226
    stop("lgb.Dataset.set.reference: input dataset should be an lgb.Dataset object")
Guolin Ke's avatar
Guolin Ke committed
1227
  }
James Lamb's avatar
James Lamb committed
1228

1229
  return(invisible(dataset$set_reference(reference = reference)))
Guolin Ke's avatar
Guolin Ke committed
1230
1231
}

1232
1233
1234
1235
#' @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
1236
1237
#' @param dataset object of class \code{lgb.Dataset}
#' @param fname object filename of output file
James Lamb's avatar
James Lamb committed
1238
#'
1239
#' @return the dataset you passed in
James Lamb's avatar
James Lamb committed
1240
#'
Guolin Ke's avatar
Guolin Ke committed
1241
#' @examples
1242
#' \donttest{
1243
1244
1245
#' data(agaricus.train, package = "lightgbm")
#' train <- agaricus.train
#' dtrain <- lgb.Dataset(train$data, label = train$label)
1246
#' lgb.Dataset.save(dtrain, tempfile(fileext = ".bin"))
1247
#' }
Guolin Ke's avatar
Guolin Ke committed
1248
1249
#' @export
lgb.Dataset.save <- function(dataset, fname) {
James Lamb's avatar
James Lamb committed
1250

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

1255
  if (!is.character(fname)) {
1256
    stop("lgb.Dataset.save: fname should be a character or a file connection")
Guolin Ke's avatar
Guolin Ke committed
1257
  }
James Lamb's avatar
James Lamb committed
1258

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