lightgbm_R.h 26.6 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
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
/*!
 * \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
);

409
410
/*!
* \brief Get model upper bound value.
411
* \param handle Handle of Booster
412
* \param[out] out_results Result pointing to max value
413
* \return R NULL value
414
*/
415
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetUpperBoundValue_R(
416
    SEXP handle,
417
    SEXP out_result
418
419
420
421
);

/*!
* \brief Get model lower bound value.
422
* \param handle Handle of Booster
423
* \param[out] out_results Result pointing to min value
424
* \return R NULL value
425
*/
426
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetLowerBoundValue_R(
427
    SEXP handle,
428
    SEXP out_result
429
430
);

Guolin Ke's avatar
Guolin Ke committed
431
/*!
432
433
434
* \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
435
*/
436
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetEvalNames_R(
437
  SEXP handle
438
);
Guolin Ke's avatar
Guolin Ke committed
439
440
441

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

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

/*!
467
468
* \brief Get prediction for training data and validation data.
*        This can be used to support customized eval function
469
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
470
471
* \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
472
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
473
*/
474
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetPredict_R(
475
  SEXP handle,
476
  SEXP data_idx,
477
  SEXP out_result
478
);
Guolin Ke's avatar
Guolin Ke committed
479
480
481

/*!
* \brief make prediction for file
482
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
483
484
* \param data_filename filename of data file
* \param data_has_header data file has header or not
485
486
487
488
489
490
* \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
491
* \param num_iteration number of iteration for prediction, <= 0 means no limit
492
493
494
* \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
495
*/
496
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForFile_R(
497
  SEXP handle,
498
  SEXP data_filename,
499
500
501
502
503
504
  SEXP data_has_header,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
505
506
  SEXP parameter,
  SEXP result_filename
507
);
Guolin Ke's avatar
Guolin Ke committed
508
509
510

/*!
* \brief Get number of prediction
511
512
513
514
515
516
517
518
* \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
519
* \param num_iteration number of iteration for prediction, <= 0 means no limit
520
* \param out_len length of prediction
521
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
522
*/
523
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCalcNumPredict_R(
524
  SEXP handle,
525
526
527
528
529
530
  SEXP num_row,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
531
  SEXP out_len
532
);
Guolin Ke's avatar
Guolin Ke committed
533
534

/*!
535
* \brief make prediction for a new Dataset
Guolin Ke's avatar
Guolin Ke committed
536
*        Note:  should pre-allocate memory for out_result,
537
*               for normal and raw score: its length is equal to num_class * num_data
Guolin Ke's avatar
Guolin Ke committed
538
*               for leaf index, its length is equal to num_class * num_data * num_iteration
539
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
540
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
541
542
543
* \param indptr pointer to row headers
* \param indices findex
* \param data fvalue
544
* \param num_indptr number of cols in the matrix + 1
545
* \param nelem number of non-zero elements in the matrix
Guolin Ke's avatar
Guolin Ke committed
546
* \param num_row number of rows
547
548
549
550
551
* \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
552
* \param start_iteration start index of the iteration to predict
Guolin Ke's avatar
Guolin Ke committed
553
* \param num_iteration number of iteration for prediction, <= 0 means no limit
554
555
556
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
557
*/
558
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSC_R(
559
  SEXP handle,
560
561
562
  SEXP indptr,
  SEXP indices,
  SEXP data,
563
564
565
566
567
568
569
570
  SEXP num_indptr,
  SEXP nelem,
  SEXP num_row,
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
571
  SEXP parameter,
572
  SEXP out_result
573
);
Guolin Ke's avatar
Guolin Ke committed
574
575

/*!
576
* \brief make prediction for a new Dataset
Guolin Ke's avatar
Guolin Ke committed
577
*        Note:  should pre-allocate memory for out_result,
578
*               for normal and raw score: its length is equal to num_class * num_data
Guolin Ke's avatar
Guolin Ke committed
579
*               for leaf index, its length is equal to num_class * num_data * num_iteration
580
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
581
* \param handle Booster handle
582
583
584
585
* \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
586
587
588
589
590
* \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
591
* \param start_iteration start index of the iteration to predict
Guolin Ke's avatar
Guolin Ke committed
592
* \param num_iteration number of iteration for prediction, <= 0 means no limit
593
594
595
* \param parameter additional parameters
* \param out_result prediction result
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
596
*/
597
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSR_R(
598
  SEXP handle,
599
600
  SEXP indptr,
  SEXP indices,
601
  SEXP data,
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
  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
621
* \param ncols number of columns in the data
622
623
624
625
626
* \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
627
* \param start_iteration start index of the iteration to predict
628
629
630
631
632
633
634
635
636
637
* \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,
638
639
640
641
642
  SEXP is_rawscore,
  SEXP is_leafidx,
  SEXP is_predcontrib,
  SEXP start_iteration,
  SEXP num_iteration,
643
  SEXP parameter,
644
  SEXP out_result
645
);
Guolin Ke's avatar
Guolin Ke committed
646

647
648
649
/*!
* \brief Initialize and return a fast configuration handle to use with ``LGBM_BoosterPredictForCSRSingleRowFast_R``.
* \param handle Booster handle
650
* \param ncols number columns in the data
651
652
653
654
655
* \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
656
* \param start_iteration start index of the iteration to predict
657
658
659
660
661
662
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
* \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
);

691
692
693
694
695
696
697
698
699
/*!
* \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
700
* \param start_iteration start index of the iteration to predict
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
* \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
);

720
721
722
723
724
/*!
* \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
725
*               for feature contributions, its length is equal to num_class * num_data * (num_features + 1)
726
727
728
729
730
731
732
733
734
* \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
735
* \param start_iteration start index of the iteration to predict
736
737
738
739
740
741
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
* \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
768
* \param start_iteration start index of the iteration to predict
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
* \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
789
* \param ncols number columns in the data
790
791
792
793
794
* \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
795
* \param start_iteration start index of the iteration to predict
796
797
798
799
800
801
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
* \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
828
829
/*!
* \brief save model into file
830
* \param handle Booster handle
Guolin Ke's avatar
Guolin Ke committed
831
* \param num_iteration, <= 0 means save all
832
* \param feature_importance_type type of feature importance, 0: split, 1: gain
Guolin Ke's avatar
Guolin Ke committed
833
* \param filename file name
834
* \param start_iteration Starting iteration (0 based)
835
* \return R NULL value
Guolin Ke's avatar
Guolin Ke committed
836
*/
837
LIGHTGBM_C_EXPORT SEXP LGBM_BoosterSaveModel_R(
838
  SEXP handle,
839
840
  SEXP num_iteration,
  SEXP feature_importance_type,
841
842
  SEXP filename,
  SEXP start_iteration
843
);
Guolin Ke's avatar
Guolin Ke committed
844

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

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

875
876
877
878
879
880
/*!
* \brief Dump parameter aliases to JSON
* \return R character vector (length=1) with aliases JSON
*/
LIGHTGBM_C_EXPORT SEXP LGBM_DumpParamAliases_R();

881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
/*!
* \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
);

900
#endif  // LIGHTGBM_R_H_