lightgbm_R.h 26.7 KB
Newer Older
1
2
3
4
/*!
 * Copyright (c) 2017 Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License. See LICENSE file in the project root for license information.
 */
5
6
#ifndef LIGHTGBM_R_PACKAGE_SRC_LIGHTGBM_R_H_
#define LIGHTGBM_R_PACKAGE_SRC_LIGHTGBM_R_H_
Guolin Ke's avatar
Guolin Ke committed
7
8

#include <LightGBM/c_api.h>
9

10
#ifndef R_NO_REMAP
11
#define R_NO_REMAP
12
13
14
#endif

#ifndef R_USE_C99_IN_CXX
15
#define R_USE_C99_IN_CXX
16
17
#endif

18
19
#include <Rinternals.h>

20
21
22
23
24
25
26
27
28
/*!
* \brief check if an R external pointer (like a Booster or Dataset handle) is a null pointer
* \param handle handle for a Booster, Dataset, or Predictor
* \return R logical, TRUE if the handle is a null pointer
*/
LIGHTGBM_C_EXPORT SEXP LGBM_HandleIsNull_R(
  SEXP handle
);

29
30
31
32
33
34
/*!
* \brief Throw a standardized error message when encountering a null Booster handle
* \return No return, will throw an error
*/
LIGHTGBM_C_EXPORT SEXP LGBM_NullBoosterHandleError_R();

Guolin Ke's avatar
Guolin Ke committed
35
36
37
// --- start Dataset interface

/*!
38
* \brief load Dataset from file like the command_line LightGBM does
Guolin Ke's avatar
Guolin Ke committed
39
40
* \param filename the name of the file
* \param parameters additional parameters
41
* \param reference used to align bin mapper with other Dataset, nullptr means not used
42
* \return Dataset handle
Guolin Ke's avatar
Guolin Ke committed
43
*/
44
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromFile_R(
45
46
  SEXP filename,
  SEXP parameters,
47
  SEXP reference
48
);
Guolin Ke's avatar
Guolin Ke committed
49
50

/*!
51
* \brief create a Dataset from Compressed Sparse Column (CSC) format
Guolin Ke's avatar
Guolin Ke committed
52
53
54
* \param indptr pointer to row headers
* \param indices findex
* \param data fvalue
55
* \param num_indptr number of cols in the matrix + 1
Guolin Ke's avatar
Guolin Ke committed
56
57
58
* \param nelem number of nonzero elements in the matrix
* \param num_row number of rows
* \param parameters additional parameters
59
* \param reference used to align bin mapper with other Dataset, nullptr means not used
60
* \return Dataset handle
Guolin Ke's avatar
Guolin Ke committed
61
*/
62
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromCSC_R(
63
64
65
  SEXP indptr,
  SEXP indices,
  SEXP data,
66
67
68
  SEXP num_indptr,
  SEXP nelem,
  SEXP num_row,
69
  SEXP parameters,
70
  SEXP reference
71
);
Guolin Ke's avatar
Guolin Ke committed
72
73

/*!
74
75
* \brief create Dataset from dense matrix
* \param data matrix data
76
77
* \param num_row number of rows
* \param num_col number columns
Guolin Ke's avatar
Guolin Ke committed
78
* \param parameters additional parameters
79
* \param reference used to align bin mapper with other Dataset, nullptr means not used
80
* \return Dataset handle
Guolin Ke's avatar
Guolin Ke committed
81
*/
82
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromMat_R(
83
  SEXP data,
84
85
  SEXP num_row,
  SEXP num_col,
86
  SEXP parameters,
87
  SEXP reference
88
);
Guolin Ke's avatar
Guolin Ke committed
89
90

/*!
91
92
* \brief Create subset of a Dataset
* \param handle handle of full Dataset
Guolin Ke's avatar
Guolin Ke committed
93
94
95
* \param used_row_indices Indices used in subset
* \param len_used_row_indices length of Indices used in subset
* \param parameters additional parameters
96
* \return Dataset handle
Guolin Ke's avatar
Guolin Ke committed
97
*/
98
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetSubset_R(
99
  SEXP handle,
100
  SEXP used_row_indices,
101
  SEXP len_used_row_indices,
102
  SEXP parameters
103
);
Guolin Ke's avatar
Guolin Ke committed
104
105
106
107
108

/*!
* \brief save feature names to Dataset
* \param handle handle
* \param feature_names feature names
109
* \return R character vector of feature names
Guolin Ke's avatar
Guolin Ke committed
110
*/
111
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSetFeatureNames_R(
112
  SEXP handle,
113
  SEXP feature_names
114
);
Guolin Ke's avatar
Guolin Ke committed
115
116

/*!
117
118
119
* \brief get feature names from Dataset
* \param handle Dataset handle
* \return an R character vector with feature names from the Dataset or NULL if no feature names
Guolin Ke's avatar
Guolin Ke committed
120
*/
121
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetFeatureNames_R(
122
  SEXP handle
123
);
Guolin Ke's avatar
Guolin Ke committed
124
125

/*!
126
127
* \brief save Dataset to binary file
* \param handle an instance of Dataset
Guolin Ke's avatar
Guolin Ke committed
128
* \param filename file name
129
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
130
*/
131
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSaveBinary_R(
132
  SEXP handle,
133
  SEXP filename
134
);
Guolin Ke's avatar
Guolin Ke committed
135
136

/*!
137
138
139
* \brief free Dataset
* \param handle an instance of Dataset
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
140
*/
141
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetFree_R(
142
  SEXP handle
143
);
Guolin Ke's avatar
Guolin Ke committed
144
145
146

/*!
* \brief set vector to a content in info
147
*        Note: group and group_id only work for C_API_DTYPE_INT32
Guolin Ke's avatar
Guolin Ke committed
148
*              label and weight only work for C_API_DTYPE_FLOAT32
149
* \param handle an instance of Dataset
Guolin Ke's avatar
Guolin Ke committed
150
151
152
* \param field_name field name, can be label, weight, group, group_id
* \param field_data pointer to vector
* \param num_element number of element in field_data
153
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
154
*/
155
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSetField_R(
156
  SEXP handle,
157
  SEXP field_name,
158
  SEXP field_data,
159
  SEXP num_element
160
);
Guolin Ke's avatar
Guolin Ke committed
161
162

/*!
163
164
* \brief get size of info vector from Dataset
* \param handle an instance of Dataset
Guolin Ke's avatar
Guolin Ke committed
165
* \param field_name field name
166
167
* \param out size of info vector from Dataset
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
168
*/
169
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetFieldSize_R(
170
  SEXP handle,
171
  SEXP field_name,
172
  SEXP out
173
);
Guolin Ke's avatar
Guolin Ke committed
174
175

/*!
176
177
* \brief get info vector from Dataset
* \param handle an instance of Dataset
Guolin Ke's avatar
Guolin Ke committed
178
179
* \param field_name field name
* \param field_data pointer to vector
180
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
181
*/
182
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetField_R(
183
  SEXP handle,
184
  SEXP field_name,
185
  SEXP field_data
186
);
Guolin Ke's avatar
Guolin Ke committed
187

188
/*!
189
190
191
192
193
 * \brief Raise errors for attempts to update Dataset parameters.
 *        Some parameters cannot be updated after construction.
 * \param old_params Current Dataset parameters
 * \param new_params New Dataset parameters
 * \return R NULL value
194
 */
195
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetUpdateParamChecking_R(
196
197
  SEXP old_params,
  SEXP new_params
198
);
199

Guolin Ke's avatar
Guolin Ke committed
200
201
/*!
* \brief get number of data.
202
* \param handle the handle to the Dataset
Guolin Ke's avatar
Guolin Ke committed
203
* \param out The address to hold number of data
204
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
205
*/
206
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetNumData_R(
207
  SEXP handle,
208
  SEXP out
209
);
Guolin Ke's avatar
Guolin Ke committed
210
211
212

/*!
* \brief get number of features
213
* \param handle the handle to the Dataset
Guolin Ke's avatar
Guolin Ke committed
214
* \param out The output of number of features
215
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
216
*/
217
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetNumFeature_R(
218
  SEXP handle,
219
  SEXP out
220
);
Guolin Ke's avatar
Guolin Ke committed
221

222
223
224
225
226
227
228
229
230
231
232
233
234
/*!
* \brief get number of bins for feature
* \param handle the handle to the Dataset
* \param feature the index of the feature
* \param out The output of number of bins
* \return R NULL value
*/
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetFeatureNumBin_R(
  SEXP handle,
  SEXP feature,
  SEXP out
);

Guolin Ke's avatar
Guolin Ke committed
235
236
237
// --- start Booster interfaces

/*!
238
* \brief create a new boosting learner
239
* \param train_data training Dataset
Guolin Ke's avatar
Guolin Ke committed
240
* \param parameters format: 'key1=value1 key2=value2'
241
* \return Booster handle
Guolin Ke's avatar
Guolin Ke committed
242
*/
243
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCreate_R(
244
245
  SEXP train_data,
  SEXP parameters
246
);
Guolin Ke's avatar
Guolin Ke committed
247
248

/*!
249
* \brief free Booster
Guolin Ke's avatar
Guolin Ke committed
250
* \param handle handle to be freed
251
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
252
*/
253
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterFree_R(
254
  SEXP handle
255
);
Guolin Ke's avatar
Guolin Ke committed
256
257

/*!
258
* \brief load an existing Booster from model file
Guolin Ke's avatar
Guolin Ke committed
259
* \param filename filename of model
260
* \return Booster handle
Guolin Ke's avatar
Guolin Ke committed
261
*/
262
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCreateFromModelfile_R(
263
  SEXP filename
264
);
Guolin Ke's avatar
Guolin Ke committed
265

266
/*!
267
* \brief load an existing Booster from a string
268
* \param model_str string containing the model
269
* \return Booster handle
270
*/
271
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterLoadModelFromString_R(
272
  SEXP model_str
273
);
274

275
276
277
278
279
280
281
282
283
/*!
* \brief Get parameters as JSON string.
* \param handle Booster handle
* \return R character vector (length=1) with parameters in JSON format
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetLoadedParam_R(
  SEXP handle
);

Guolin Ke's avatar
Guolin Ke committed
284
/*!
285
286
287
288
* \brief Merge model in two Boosters to first handle
* \param handle handle primary Booster handle, will merge other handle to this
* \param other_handle secondary Booster handle
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
289
*/
290
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterMerge_R(
291
292
  SEXP handle,
  SEXP other_handle
293
);
Guolin Ke's avatar
Guolin Ke committed
294
295

/*!
296
297
298
299
* \brief Add new validation to Booster
* \param handle Booster handle
* \param valid_data validation Dataset
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
300
*/
301
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterAddValidData_R(
302
303
  SEXP handle,
  SEXP valid_data
304
);
Guolin Ke's avatar
Guolin Ke committed
305
306

/*!
307
308
309
310
* \brief Reset training data for Booster
* \param handle Booster handle
* \param train_data training Dataset
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
311
*/
312
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterResetTrainingData_R(
313
314
  SEXP handle,
  SEXP train_data
315
);
Guolin Ke's avatar
Guolin Ke committed
316
317

/*!
318
319
* \brief Reset config for current Booster
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
320
* \param parameters format: 'key1=value1 key2=value2'
321
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
322
*/
323
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterResetParameter_R(
324
  SEXP handle,
325
  SEXP parameters
326
);
Guolin Ke's avatar
Guolin Ke committed
327
328

/*!
329
* \brief Get number of classes
330
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
331
* \param out number of classes
332
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
333
*/
334
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumClasses_R(
335
  SEXP handle,
336
  SEXP out
337
);
Guolin Ke's avatar
Guolin Ke committed
338

339
340
341
342
343
344
345
346
347
/*!
* \brief Get number of features.
* \param handle Booster handle
* \return Total number of features, as R integer
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumFeature_R(
  SEXP handle
);

Guolin Ke's avatar
Guolin Ke committed
348
349
/*!
* \brief update the model in one round
350
351
* \param handle Booster handle
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
352
*/
353
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterUpdateOneIter_R(
354
  SEXP handle
355
);
Guolin Ke's avatar
Guolin Ke committed
356
357

/*!
358
* \brief update the model, by directly specifying gradient and second order gradient,
Guolin Ke's avatar
Guolin Ke committed
359
*       this can be used to support customized loss function
360
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
361
362
363
* \param grad gradient statistics
* \param hess second order gradient statistics
* \param len length of grad/hess
364
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
365
*/
366
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterUpdateOneIterCustom_R(
367
  SEXP handle,
368
369
  SEXP grad,
  SEXP hess,
370
  SEXP len
371
);
Guolin Ke's avatar
Guolin Ke committed
372
373
374

/*!
* \brief Rollback one iteration
375
376
* \param handle Booster handle
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
377
*/
378
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterRollbackOneIter_R(
379
  SEXP handle
380
);
Guolin Ke's avatar
Guolin Ke committed
381
382
383

/*!
* \brief Get iteration of current boosting rounds
384
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
385
* \param out iteration of boosting rounds
386
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
387
*/
388
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetCurrentIteration_R(
389
  SEXP handle,
390
  SEXP out
391
);
Guolin Ke's avatar
Guolin Ke committed
392

393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
/*!
 * \brief Get number of trees per iteration
 * \param handle Booster handle
 * \param out Number of trees per iteration
 * \return R NULL value
 */
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterNumModelPerIteration_R(
    SEXP handle,
    SEXP out
);

/*!
 * \brief Get total number of trees
 * \param handle Booster handle
 * \param out Total number of trees of Booster
 * \return R NULL value
 */
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterNumberOfTotalModel_R(
    SEXP handle,
    SEXP out
);

415
416
/*!
* \brief Get model upper bound value.
417
* \param handle Handle of Booster
418
* \param[out] out_results Result pointing to max value
419
* \return R NULL value
420
*/
421
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetUpperBoundValue_R(
422
    SEXP handle,
423
    SEXP out_result
424
425
426
427
);

/*!
* \brief Get model lower bound value.
428
* \param handle Handle of Booster
429
* \param[out] out_results Result pointing to min value
430
* \return R NULL value
431
*/
432
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetLowerBoundValue_R(
433
    SEXP handle,
434
    SEXP out_result
435
436
);

Guolin Ke's avatar
Guolin Ke committed
437
/*!
438
439
440
* \brief Get names of eval metrics
* \param handle Handle of booster
* \return R character vector with names of eval metrics
Guolin Ke's avatar
Guolin Ke committed
441
*/
442
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetEvalNames_R(
443
  SEXP handle
444
);
Guolin Ke's avatar
Guolin Ke committed
445
446
447

/*!
* \brief get evaluation for training data and validation data
448
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
449
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
450
451
* \param out_result float array containing result
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
452
*/
453
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetEval_R(
454
  SEXP handle,
455
  SEXP data_idx,
456
  SEXP out_result
457
);
Guolin Ke's avatar
Guolin Ke committed
458
459
460

/*!
* \brief Get number of prediction for training data and validation data
461
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
462
463
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
* \param out size of predict
464
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
465
*/
466
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumPredict_R(
467
  SEXP handle,
468
  SEXP data_idx,
469
  SEXP out
470
);
Guolin Ke's avatar
Guolin Ke committed
471
472

/*!
473
474
* \brief Get prediction for training data and validation data.
*        This can be used to support customized eval function
475
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
476
477
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
* \param out_result, used to store predict result, should pre-allocate memory
478
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
479
*/
480
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetPredict_R(
481
  SEXP handle,
482
  SEXP data_idx,
483
  SEXP out_result
484
);
Guolin Ke's avatar
Guolin Ke committed
485
486
487

/*!
* \brief make prediction for file
488
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
489
490
* \param data_filename filename of data file
* \param data_has_header data file has header or not
491
492
493
494
495
496
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
* \param start_iteration Start index of the iteration to predict
Guolin Ke's avatar
Guolin Ke committed
497
* \param num_iteration number of iteration for prediction, <= 0 means no limit
498
499
500
* \param parameter additional parameters
* \param result_filename filename of file to write predictions to
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
501
*/
502
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForFile_R(
503
  SEXP handle,
504
  SEXP data_filename,
505
506
507
508
509
510
  SEXP data_has_header,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
511
512
  SEXP parameter,
  SEXP result_filename
513
);
Guolin Ke's avatar
Guolin Ke committed
514
515
516

/*!
* \brief Get number of prediction
517
518
519
520
521
522
523
524
* \param handle Booster handle
* \param num_row number of rows in input
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
* \param start_iteration Start index of the iteration to predict
Guolin Ke's avatar
Guolin Ke committed
525
* \param num_iteration number of iteration for prediction, <= 0 means no limit
526
* \param out_len length of prediction
527
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
528
*/
529
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCalcNumPredict_R(
530
  SEXP handle,
531
532
533
534
535
536
  SEXP num_row,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
537
  SEXP out_len
538
);
Guolin Ke's avatar
Guolin Ke committed
539
540

/*!
541
* \brief make prediction for a new Dataset
Guolin Ke's avatar
Guolin Ke committed
542
*        Note:  should pre-allocate memory for out_result,
543
*               for normal and raw score: its length is equal to num_class * num_data
Guolin Ke's avatar
Guolin Ke committed
544
*               for leaf index, its length is equal to num_class * num_data * num_iteration
545
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
546
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
547
548
549
* \param indptr pointer to row headers
* \param indices findex
* \param data fvalue
550
* \param num_indptr number of cols in the matrix + 1
551
* \param nelem number of non-zero elements in the matrix
Guolin Ke's avatar
Guolin Ke committed
552
* \param num_row number of rows
553
554
555
556
557
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
558
* \param start_iteration start index of the iteration to predict
Guolin Ke's avatar
Guolin Ke committed
559
* \param num_iteration number of iteration for prediction, <= 0 means no limit
560
561
562
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
563
*/
564
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSC_R(
565
  SEXP handle,
566
567
568
  SEXP indptr,
  SEXP indices,
  SEXP data,
569
570
571
572
573
574
575
576
  SEXP num_indptr,
  SEXP nelem,
  SEXP num_row,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
577
  SEXP parameter,
578
  SEXP out_result
579
);
Guolin Ke's avatar
Guolin Ke committed
580
581

/*!
582
* \brief make prediction for a new Dataset
Guolin Ke's avatar
Guolin Ke committed
583
*        Note:  should pre-allocate memory for out_result,
584
*               for normal and raw score: its length is equal to num_class * num_data
Guolin Ke's avatar
Guolin Ke committed
585
*               for leaf index, its length is equal to num_class * num_data * num_iteration
586
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
587
* \param handle Booster handle
588
589
590
591
* \param indptr array with the index pointer of the data in CSR format
* \param indices array with the non-zero indices of the data in CSR format
* \param data array with the non-zero values of the data in CSR format
* \param ncols number of columns in the data
592
593
594
595
596
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
597
* \param start_iteration start index of the iteration to predict
Guolin Ke's avatar
Guolin Ke committed
598
* \param num_iteration number of iteration for prediction, <= 0 means no limit
599
600
601
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
602
*/
603
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSR_R(
604
  SEXP handle,
605
606
  SEXP indptr,
  SEXP indices,
607
  SEXP data,
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
  SEXP ncols,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
  SEXP parameter,
  SEXP out_result
);

/*!
* \brief make prediction for a single row of data
*        Note:  should pre-allocate memory for out_result,
*               for normal and raw score: its length is equal to num_class
*               for leaf index, its length is equal to num_class * num_iteration
*               for feature contributions, its length is equal to num_class * (num_features + 1)
* \param handle Booster handle
* \param indices array corresponding to the indices of the columns with non-zero values of the row to predict on
* \param data array corresponding to the non-zero values of row to predict on
627
* \param ncols number of columns in the data
628
629
630
631
632
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
633
* \param start_iteration start index of the iteration to predict
634
635
636
637
638
639
640
641
642
643
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSRSingleRow_R(
  SEXP handle,
  SEXP indices,
  SEXP data,
  SEXP ncols,
644
645
646
647
648
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
649
  SEXP parameter,
650
  SEXP out_result
651
);
Guolin Ke's avatar
Guolin Ke committed
652

653
654
655
/*!
* \brief Initialize and return a fast configuration handle to use with ``LGBM_BoosterPredictForCSRSingleRowFast_R``.
* \param handle Booster handle
656
* \param ncols number columns in the data
657
658
659
660
661
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
662
* \param start_iteration start index of the iteration to predict
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param parameter additional parameters
* \return Fast configuration handle
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSRSingleRowFastInit_R(
  SEXP handle,
  SEXP ncols,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
  SEXP parameter
);

/*!
* \brief make prediction for a single row of data
*        Note:  should pre-allocate memory for out_result,
*               for normal and raw score: its length is equal to num_class
*               for leaf index, its length is equal to num_class * num_iteration
*               for feature contributions, its length is equal to num_class * (num_features + 1)
* \param handle_fastConfig Fast configuration handle
* \param indices array corresponding to the indices of the columns with non-zero values of the row to predict on
* \param data array corresponding to the non-zero values of row to predict on
* \param out_result prediction result
* \return R NULL value
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSRSingleRowFast_R(
  SEXP handle_fastConfig,
  SEXP indices,
  SEXP data,
  SEXP out_result
);

697
698
699
700
701
702
703
704
705
/*!
* \brief make feature contribution prediction for a new Dataset
* \param handle Booster handle
* \param indptr array with the index pointer of the data in CSR or CSC format
* \param indices array with the non-zero indices of the data in CSR or CSC format
* \param data array with the non-zero values of the data in CSR or CSC format
* \param is_csr whether the input data is in CSR format or not (pass FALSE for CSC)
* \param nrows number of rows in the data
* \param ncols number of columns in the data
706
* \param start_iteration start index of the iteration to predict
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param parameter additional parameters
* \return An R list with entries "indptr", "indices", "data", constituting the
*         feature contributions in sparse format, in the same storage order as
*         the input data.
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictSparseOutput_R(
  SEXP handle,
  SEXP indptr,
  SEXP indices,
  SEXP data,
  SEXP is_csr,
  SEXP nrows,
  SEXP ncols,
  SEXP start_iteration,
  SEXP num_iteration,
  SEXP parameter
);

726
727
728
729
730
/*!
* \brief make prediction for a new Dataset
*        Note:  should pre-allocate memory for out_result,
*               for normal and raw score: its length is equal to num_class * num_data
*               for leaf index, its length is equal to num_class * num_data * num_iteration
731
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
732
733
734
735
736
737
738
739
740
* \param handle Booster handle
* \param data pointer to the data space
* \param num_row number of rows
* \param num_col number columns
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
741
* \param start_iteration start index of the iteration to predict
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForMat_R(
  SEXP handle,
  SEXP data,
  SEXP num_row,
  SEXP num_col,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
  SEXP parameter,
  SEXP out_result
);

/*!
* \brief make prediction for a single row of data
*        Note:  should pre-allocate memory for out_result,
*               for normal and raw score: its length is equal to num_class
*               for leaf index, its length is equal to num_class * num_iteration
*               for feature contributions, its length is equal to num_class * (num_features + 1)
* \param handle Booster handle
* \param data array corresponding to the row to predict on
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
774
* \param start_iteration start index of the iteration to predict
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForMatSingleRow_R(
  SEXP handle,
  SEXP data,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
  SEXP parameter,
  SEXP out_result
);

/*!
* \brief Initialize and return a fast configuration handle to use with ``LGBM_BoosterPredictForMatSingleRowFast_R``.
* \param handle Booster handle
795
* \param ncols number columns in the data
796
797
798
799
800
* \param is_rawscore 1 to get raw predictions, before transformations like
*                    converting to probabilities, 0 otherwise
* \param is_leafidx 1 to get record of which leaf in each tree
*                   observations fell into, 0 otherwise
* \param is_predcontrib 1 to get feature contributions, 0 otherwise
801
* \param start_iteration start index of the iteration to predict
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param parameter additional parameters
* \return Fast configuration handle
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForMatSingleRowFastInit_R(
  SEXP handle,
  SEXP ncols,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
  SEXP parameter
);

/*!
* \brief make prediction for a single row of data
*        Note:  should pre-allocate memory for out_result,
*               for normal and raw score: its length is equal to num_class
*               for leaf index, its length is equal to num_class * num_iteration
*               for feature contributions, its length is equal to num_class * (num_features + 1)
* \param handle_fastConfig Fast configuration handle
* \param data array corresponding to the row to predict on
* \param out_result prediction result
* \return R NULL value
*/
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForMatSingleRowFast_R(
  SEXP handle_fastConfig,
  SEXP data,
  SEXP out_result
);

Guolin Ke's avatar
Guolin Ke committed
834
835
/*!
* \brief save model into file
836
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
837
* \param num_iteration, <= 0 means save all
838
* \param feature_importance_type type of feature importance, 0: split, 1: gain
Guolin Ke's avatar
Guolin Ke committed
839
* \param filename file name
840
* \param start_iteration Starting iteration (0 based)
841
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
842
*/
843
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterSaveModel_R(
844
  SEXP handle,
845
846
  SEXP num_iteration,
  SEXP feature_importance_type,
847
848
  SEXP filename,
  SEXP start_iteration
849
);
Guolin Ke's avatar
Guolin Ke committed
850

851
852
/*!
* \brief create string containing model
853
* \param handle Booster handle
854
* \param num_iteration, <= 0 means save all
855
* \param feature_importance_type type of feature importance, 0: split, 1: gain
856
* \param start_iteration Starting iteration (0 based)
857
* \return R character vector (length=1) with model string
858
*/
859
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterSaveModelToString_R(
860
  SEXP handle,
861
  SEXP num_iteration,
862
863
  SEXP feature_importance_type,
  SEXP start_iteration
864
);
865

Guolin Ke's avatar
Guolin Ke committed
866
/*!
867
868
* \brief dump model to JSON
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
869
* \param num_iteration, <= 0 means save all
870
* \param feature_importance_type type of feature importance, 0: split, 1: gain
871
* \param start_iteration Index of starting iteration (0 based)
872
* \return R character vector (length=1) with model JSON
Guolin Ke's avatar
Guolin Ke committed
873
*/
874
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterDumpModel_R(
875
  SEXP handle,
876
  SEXP num_iteration,
877
878
  SEXP feature_importance_type,
  SEXP start_iteration
879
);
Guolin Ke's avatar
Guolin Ke committed
880

881
882
883
884
885
886
/*!
* \brief Dump parameter aliases to JSON
* \return R character vector (length=1) with aliases JSON
*/
LIGHTGBM_C_EXPORT SEXP LGBM_DumpParamAliases_R();

887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
/*!
* \brief Get current maximum number of threads used by LightGBM routines in this process.
* \param[out] out current maximum number of threads used by LightGBM. -1 means defaulting to omp_get_num_threads().
* \return R NULL value
*/
LIGHTGBM_C_EXPORT SEXP LGBM_GetMaxThreads_R(
  SEXP out
);


/*!
* \brief Set maximum number of threads used by LightGBM routines in this process.
* \param num_threads maximum number of threads used by LightGBM. -1 means defaulting to omp_get_num_threads().
* \return R NULL value
*/
LIGHTGBM_C_EXPORT SEXP LGBM_SetMaxThreads_R(
  SEXP num_threads
);

906
#endif  // LIGHTGBM_R_PACKAGE_SRC_LIGHTGBM_R_H_