lightgbm_R.h 25.3 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.
 */
Guolin Ke's avatar
Guolin Ke committed
5
6
7
8
#ifndef LIGHTGBM_R_H_
#define LIGHTGBM_R_H_

#include <LightGBM/c_api.h>
9
10
11
12
13

#define R_NO_REMAP
#define R_USE_C99_IN_CXX
#include <Rinternals.h>

14
15
16
17
18
19
20
21
22
/*!
* \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
);

23
24
25
26
27
28
/*!
* \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
29
30
31
// --- start Dataset interface

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

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

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

/*!
85
86
* \brief Create subset of a Dataset
* \param handle handle of full Dataset
Guolin Ke's avatar
Guolin Ke committed
87
88
89
* \param used_row_indices Indices used in subset
* \param len_used_row_indices length of Indices used in subset
* \param parameters additional parameters
90
* \return Dataset handle
Guolin Ke's avatar
Guolin Ke committed
91
*/
92
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetSubset_R(
93
  SEXP handle,
94
  SEXP used_row_indices,
95
  SEXP len_used_row_indices,
96
  SEXP parameters
97
);
Guolin Ke's avatar
Guolin Ke committed
98
99
100
101
102

/*!
* \brief save feature names to Dataset
* \param handle handle
* \param feature_names feature names
103
* \return R character vector of feature names
Guolin Ke's avatar
Guolin Ke committed
104
*/
105
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSetFeatureNames_R(
106
  SEXP handle,
107
  SEXP feature_names
108
);
Guolin Ke's avatar
Guolin Ke committed
109
110

/*!
111
112
113
* \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
114
*/
115
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetFeatureNames_R(
116
  SEXP handle
117
);
Guolin Ke's avatar
Guolin Ke committed
118
119

/*!
120
121
* \brief save Dataset to binary file
* \param handle an instance of Dataset
Guolin Ke's avatar
Guolin Ke committed
122
* \param filename file name
123
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
124
*/
125
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSaveBinary_R(
126
  SEXP handle,
127
  SEXP filename
128
);
Guolin Ke's avatar
Guolin Ke committed
129
130

/*!
131
132
133
* \brief free Dataset
* \param handle an instance of Dataset
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
134
*/
135
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetFree_R(
136
  SEXP handle
137
);
Guolin Ke's avatar
Guolin Ke committed
138
139
140

/*!
* \brief set vector to a content in info
141
*        Note: group and group_id only work for C_API_DTYPE_INT32
Guolin Ke's avatar
Guolin Ke committed
142
*              label and weight only work for C_API_DTYPE_FLOAT32
143
* \param handle an instance of Dataset
Guolin Ke's avatar
Guolin Ke committed
144
145
146
* \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
147
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
148
*/
149
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSetField_R(
150
  SEXP handle,
151
  SEXP field_name,
152
  SEXP field_data,
153
  SEXP num_element
154
);
Guolin Ke's avatar
Guolin Ke committed
155
156

/*!
157
158
* \brief get size of info vector from Dataset
* \param handle an instance of Dataset
Guolin Ke's avatar
Guolin Ke committed
159
* \param field_name field name
160
161
* \param out size of info vector from Dataset
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
162
*/
163
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetFieldSize_R(
164
  SEXP handle,
165
  SEXP field_name,
166
  SEXP out
167
);
Guolin Ke's avatar
Guolin Ke committed
168
169

/*!
170
171
* \brief get info vector from Dataset
* \param handle an instance of Dataset
Guolin Ke's avatar
Guolin Ke committed
172
173
* \param field_name field name
* \param field_data pointer to vector
174
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
175
*/
176
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetField_R(
177
  SEXP handle,
178
  SEXP field_name,
179
  SEXP field_data
180
);
Guolin Ke's avatar
Guolin Ke committed
181

182
/*!
183
184
185
186
187
 * \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
188
 */
189
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetUpdateParamChecking_R(
190
191
  SEXP old_params,
  SEXP new_params
192
);
193

Guolin Ke's avatar
Guolin Ke committed
194
195
/*!
* \brief get number of data.
196
* \param handle the handle to the Dataset
Guolin Ke's avatar
Guolin Ke committed
197
* \param out The address to hold number of data
198
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
199
*/
200
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetNumData_R(
201
  SEXP handle,
202
  SEXP out
203
);
Guolin Ke's avatar
Guolin Ke committed
204
205
206

/*!
* \brief get number of features
207
* \param handle the handle to the Dataset
Guolin Ke's avatar
Guolin Ke committed
208
* \param out The output of number of features
209
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
210
*/
211
LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetNumFeature_R(
212
  SEXP handle,
213
  SEXP out
214
);
Guolin Ke's avatar
Guolin Ke committed
215

216
217
218
219
220
221
222
223
224
225
226
227
228
/*!
* \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
229
230
231
// --- start Booster interfaces

/*!
232
* \brief create a new boosting learner
233
* \param train_data training Dataset
Guolin Ke's avatar
Guolin Ke committed
234
* \param parameters format: 'key1=value1 key2=value2'
235
* \return Booster handle
Guolin Ke's avatar
Guolin Ke committed
236
*/
237
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCreate_R(
238
239
  SEXP train_data,
  SEXP parameters
240
);
Guolin Ke's avatar
Guolin Ke committed
241
242

/*!
243
* \brief free Booster
Guolin Ke's avatar
Guolin Ke committed
244
* \param handle handle to be freed
245
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
246
*/
247
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterFree_R(
248
  SEXP handle
249
);
Guolin Ke's avatar
Guolin Ke committed
250
251

/*!
252
* \brief load an existing Booster from model file
Guolin Ke's avatar
Guolin Ke committed
253
* \param filename filename of model
254
* \return Booster handle
Guolin Ke's avatar
Guolin Ke committed
255
*/
256
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCreateFromModelfile_R(
257
  SEXP filename
258
);
Guolin Ke's avatar
Guolin Ke committed
259

260
/*!
261
* \brief load an existing Booster from a string
262
* \param model_str string containing the model
263
* \return Booster handle
264
*/
265
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterLoadModelFromString_R(
266
  SEXP model_str
267
);
268

269
270
271
272
273
274
275
276
277
/*!
* \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
278
/*!
279
280
281
282
* \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
283
*/
284
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterMerge_R(
285
286
  SEXP handle,
  SEXP other_handle
287
);
Guolin Ke's avatar
Guolin Ke committed
288
289

/*!
290
291
292
293
* \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
294
*/
295
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterAddValidData_R(
296
297
  SEXP handle,
  SEXP valid_data
298
);
Guolin Ke's avatar
Guolin Ke committed
299
300

/*!
301
302
303
304
* \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
305
*/
306
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterResetTrainingData_R(
307
308
  SEXP handle,
  SEXP train_data
309
);
Guolin Ke's avatar
Guolin Ke committed
310
311

/*!
312
313
* \brief Reset config for current Booster
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
314
* \param parameters format: 'key1=value1 key2=value2'
315
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
316
*/
317
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterResetParameter_R(
318
  SEXP handle,
319
  SEXP parameters
320
);
Guolin Ke's avatar
Guolin Ke committed
321
322

/*!
323
* \brief Get number of classes
324
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
325
* \param out number of classes
326
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
327
*/
328
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumClasses_R(
329
  SEXP handle,
330
  SEXP out
331
);
Guolin Ke's avatar
Guolin Ke committed
332

333
334
335
336
337
338
339
340
341
/*!
* \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
342
343
/*!
* \brief update the model in one round
344
345
* \param handle Booster handle
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
346
*/
347
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterUpdateOneIter_R(
348
  SEXP handle
349
);
Guolin Ke's avatar
Guolin Ke committed
350
351

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

/*!
* \brief Rollback one iteration
369
370
* \param handle Booster handle
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
371
*/
372
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterRollbackOneIter_R(
373
  SEXP handle
374
);
Guolin Ke's avatar
Guolin Ke committed
375
376
377

/*!
* \brief Get iteration of current boosting rounds
378
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
379
* \param out iteration of boosting rounds
380
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
381
*/
382
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetCurrentIteration_R(
383
  SEXP handle,
384
  SEXP out
385
);
Guolin Ke's avatar
Guolin Ke committed
386

387
388
/*!
* \brief Get model upper bound value.
389
* \param handle Handle of Booster
390
* \param[out] out_results Result pointing to max value
391
* \return R NULL value
392
*/
393
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetUpperBoundValue_R(
394
    SEXP handle,
395
    SEXP out_result
396
397
398
399
);

/*!
* \brief Get model lower bound value.
400
* \param handle Handle of Booster
401
* \param[out] out_results Result pointing to min value
402
* \return R NULL value
403
*/
404
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetLowerBoundValue_R(
405
    SEXP handle,
406
    SEXP out_result
407
408
);

Guolin Ke's avatar
Guolin Ke committed
409
/*!
410
411
412
* \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
413
*/
414
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetEvalNames_R(
415
  SEXP handle
416
);
Guolin Ke's avatar
Guolin Ke committed
417
418
419

/*!
* \brief get evaluation for training data and validation data
420
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
421
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
422
423
* \param out_result float array containing result
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
424
*/
425
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetEval_R(
426
  SEXP handle,
427
  SEXP data_idx,
428
  SEXP out_result
429
);
Guolin Ke's avatar
Guolin Ke committed
430
431
432

/*!
* \brief Get number of prediction for training data and validation data
433
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
434
435
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
* \param out size of predict
436
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
437
*/
438
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumPredict_R(
439
  SEXP handle,
440
  SEXP data_idx,
441
  SEXP out
442
);
Guolin Ke's avatar
Guolin Ke committed
443
444

/*!
445
446
* \brief Get prediction for training data and validation data.
*        This can be used to support customized eval function
447
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
448
449
* \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
450
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
451
*/
452
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetPredict_R(
453
  SEXP handle,
454
  SEXP data_idx,
455
  SEXP out_result
456
);
Guolin Ke's avatar
Guolin Ke committed
457
458
459

/*!
* \brief make prediction for file
460
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
461
462
* \param data_filename filename of data file
* \param data_has_header data file has header or not
463
464
465
466
467
468
* \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
469
* \param num_iteration number of iteration for prediction, <= 0 means no limit
470
471
472
* \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
473
*/
474
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForFile_R(
475
  SEXP handle,
476
  SEXP data_filename,
477
478
479
480
481
482
  SEXP data_has_header,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
483
484
  SEXP parameter,
  SEXP result_filename
485
);
Guolin Ke's avatar
Guolin Ke committed
486
487
488

/*!
* \brief Get number of prediction
489
490
491
492
493
494
495
496
* \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
497
* \param num_iteration number of iteration for prediction, <= 0 means no limit
498
* \param out_len length of prediction
499
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
500
*/
501
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCalcNumPredict_R(
502
  SEXP handle,
503
504
505
506
507
508
  SEXP num_row,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
509
  SEXP out_len
510
);
Guolin Ke's avatar
Guolin Ke committed
511
512

/*!
513
* \brief make prediction for a new Dataset
Guolin Ke's avatar
Guolin Ke committed
514
*        Note:  should pre-allocate memory for out_result,
515
*               for normal and raw score: its length is equal to num_class * num_data
Guolin Ke's avatar
Guolin Ke committed
516
*               for leaf index, its length is equal to num_class * num_data * num_iteration
517
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
518
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
519
520
521
* \param indptr pointer to row headers
* \param indices findex
* \param data fvalue
522
* \param num_indptr number of cols in the matrix + 1
523
* \param nelem number of non-zero elements in the matrix
Guolin Ke's avatar
Guolin Ke committed
524
* \param num_row number of rows
525
526
527
528
529
* \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
530
* \param start_iteration start index of the iteration to predict
Guolin Ke's avatar
Guolin Ke committed
531
* \param num_iteration number of iteration for prediction, <= 0 means no limit
532
533
534
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
535
*/
536
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSC_R(
537
  SEXP handle,
538
539
540
  SEXP indptr,
  SEXP indices,
  SEXP data,
541
542
543
544
545
546
547
548
  SEXP num_indptr,
  SEXP nelem,
  SEXP num_row,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
549
  SEXP parameter,
550
  SEXP out_result
551
);
Guolin Ke's avatar
Guolin Ke committed
552
553

/*!
554
* \brief make prediction for a new Dataset
Guolin Ke's avatar
Guolin Ke committed
555
*        Note:  should pre-allocate memory for out_result,
556
*               for normal and raw score: its length is equal to num_class * num_data
Guolin Ke's avatar
Guolin Ke committed
557
*               for leaf index, its length is equal to num_class * num_data * num_iteration
558
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
559
* \param handle Booster handle
560
561
562
563
* \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
564
565
566
567
568
* \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
569
* \param start_iteration start index of the iteration to predict
Guolin Ke's avatar
Guolin Ke committed
570
* \param num_iteration number of iteration for prediction, <= 0 means no limit
571
572
573
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
574
*/
575
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSR_R(
576
  SEXP handle,
577
578
  SEXP indptr,
  SEXP indices,
579
  SEXP data,
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
  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
599
* \param ncols number of columns in the data
600
601
602
603
604
* \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
605
* \param start_iteration start index of the iteration to predict
606
607
608
609
610
611
612
613
614
615
* \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,
616
617
618
619
620
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
621
  SEXP parameter,
622
  SEXP out_result
623
);
Guolin Ke's avatar
Guolin Ke committed
624

625
626
627
/*!
* \brief Initialize and return a fast configuration handle to use with ``LGBM_BoosterPredictForCSRSingleRowFast_R``.
* \param handle Booster handle
628
* \param ncols number columns in the data
629
630
631
632
633
* \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
634
* \param start_iteration start index of the iteration to predict
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
* \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
);

669
670
671
672
673
674
675
676
677
/*!
* \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
678
* \param start_iteration start index of the iteration to predict
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
* \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
);

698
699
700
701
702
/*!
* \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
703
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
704
705
706
707
708
709
710
711
712
* \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
713
* \param start_iteration start index of the iteration to predict
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
* \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
746
* \param start_iteration start index of the iteration to predict
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
* \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
767
* \param ncols number columns in the data
768
769
770
771
772
* \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
773
* \param start_iteration start index of the iteration to predict
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
* \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
806
807
/*!
* \brief save model into file
808
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
809
* \param num_iteration, <= 0 means save all
810
* \param feature_importance_type type of feature importance, 0: split, 1: gain
Guolin Ke's avatar
Guolin Ke committed
811
* \param filename file name
812
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
813
*/
814
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterSaveModel_R(
815
  SEXP handle,
816
817
  SEXP num_iteration,
  SEXP feature_importance_type,
818
  SEXP filename
819
);
Guolin Ke's avatar
Guolin Ke committed
820

821
822
/*!
* \brief create string containing model
823
* \param handle Booster handle
824
* \param num_iteration, <= 0 means save all
825
826
* \param feature_importance_type type of feature importance, 0: split, 1: gain
* \return R character vector (length=1) with model string
827
*/
828
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterSaveModelToString_R(
829
  SEXP handle,
830
  SEXP num_iteration,
831
  SEXP feature_importance_type
832
);
833

Guolin Ke's avatar
Guolin Ke committed
834
/*!
835
836
* \brief dump model to JSON
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
837
* \param num_iteration, <= 0 means save all
838
839
* \param feature_importance_type type of feature importance, 0: split, 1: gain
* \return R character vector (length=1) with model JSON
Guolin Ke's avatar
Guolin Ke committed
840
*/
841
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterDumpModel_R(
842
  SEXP handle,
843
  SEXP num_iteration,
844
  SEXP feature_importance_type
845
);
Guolin Ke's avatar
Guolin Ke committed
846

847
848
849
850
851
852
/*!
* \brief Dump parameter aliases to JSON
* \return R character vector (length=1) with aliases JSON
*/
LIGHTGBM_C_EXPORT SEXP LGBM_DumpParamAliases_R();

853
#endif  // LIGHTGBM_R_H_