c_api.h 32.2 KB
Newer Older
Guolin Ke's avatar
Guolin Ke committed
1
2
#ifndef LIGHTGBM_C_API_H_
#define LIGHTGBM_C_API_H_
3
4
5
#include <cstdint>
#include <exception>
#include <stdexcept>
wxchan's avatar
wxchan committed
6
#include <cstring>
7
#include <string>
wxchan's avatar
wxchan committed
8

9
10
11
/*!
* To avoid type conversion on large data, most of our expose interface support both for float_32 and float_64.
* Except following:
wxchan's avatar
wxchan committed
12
* 1. gradients and hessians.
13
* 2. Get current score for training data and validation
wxchan's avatar
wxchan committed
14
* The reason is because they are called frequently, the type-conversion on them maybe time cost.
15
16
*/

17
#include <LightGBM/export.h>
Guolin Ke's avatar
Guolin Ke committed
18

Guolin Ke's avatar
typo  
Guolin Ke committed
19
typedef void* DatasetHandle;
Guolin Ke's avatar
Guolin Ke committed
20
21
typedef void* BoosterHandle;

Guolin Ke's avatar
Guolin Ke committed
22
23
24
25
26
27
28
29
#define C_API_DTYPE_FLOAT32 (0)
#define C_API_DTYPE_FLOAT64 (1)
#define C_API_DTYPE_INT32   (2)
#define C_API_DTYPE_INT64   (3)

#define C_API_PREDICT_NORMAL     (0)
#define C_API_PREDICT_RAW_SCORE  (1)
#define C_API_PREDICT_LEAF_INDEX (2)
30

Guolin Ke's avatar
Guolin Ke committed
31
32
/*!
* \brief get string message of the last error
wxchan's avatar
wxchan committed
33
*  all function in this file will return 0 when succeed
Guolin Ke's avatar
Guolin Ke committed
34
35
36
*  and -1 when an error occured,
* \return const char* error inforomation
*/
37
LIGHTGBM_C_EXPORT const char* LGBM_GetLastError();
Guolin Ke's avatar
Guolin Ke committed
38
39


Guolin Ke's avatar
Guolin Ke committed
40
// --- start Dataset interface
Guolin Ke's avatar
Guolin Ke committed
41
42
43
44

/*!
* \brief load data set from file like the command_line LightGBM do
* \param filename the name of the file
Guolin Ke's avatar
Guolin Ke committed
45
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
46
47
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out a loaded dataset
wxchan's avatar
wxchan committed
48
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
49
*/
50
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename,
51
52
53
                                                 const char* parameters,
                                                 const DatasetHandle reference,
                                                 DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
54

55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
/*!
* \brief create a empty dataset by sampling matrix, if num_sample_row == num_total_row, will construct this dataset.
*        Need call LGBM_DatasetPushRows/LGBM_DatasetPushRowsByCSR after calling this function.
* \param data pointer to the data space
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param num_sample_row number of rows
* \param ncol number columns
* \param num_total_row number of total rows
* \param parameters additional parameters
* \param out created dataset
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledMat(const void* data,
                                                       int data_type,
                                                       int32_t num_sample_row,
                                                       int32_t ncol,
                                                       int32_t num_total_row,
                                                       const char* parameters,
                                                       DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
74
75

/*!
76
77
* \brief create a empty dataset by sampling CSR data, if num_sample_row == num_total_row, will construct this dataset.
*        Need call LGBM_DatasetPushRows/LGBM_DatasetPushRowsByCSR after calling this function.
Guolin Ke's avatar
Guolin Ke committed
78
79
80
81
82
83
84
85
86
87
88
89
90
91
* \param indptr pointer to row headers
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
* \param indices findex
* \param data fvalue
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nindptr number of rows in the matrix + 1
* \param n_sample_elem number of nonzero elements in the matrix
* \param num_col number of columns
* \param num_total_row number of total rows
* \param parameters additional parameters
* \param out created dataset
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledCSR(const void* indptr,
92
93
94
95
96
97
98
99
100
101
                                                       int indptr_type,
                                                       const int32_t* indices,
                                                       const void* data,
                                                       int data_type,
                                                       int64_t nindptr,
                                                       int64_t n_sample_elem,
                                                       int64_t num_col,
                                                       int64_t num_total_row,
                                                       const char* parameters,
                                                       DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
102
103
104
105
106
107
108
109
110

/*!
* \brief create a empty dataset by reference Dataset
* \param reference used to align bin mapper
* \param num_total_row number of total rows
* \param out created dataset
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateByReference(const DatasetHandle reference,
111
112
                                                    int64_t num_total_row,
                                                    DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
113
114
115
116
117
118
119
120
121
122
123
124

/*!
* \brief push data to existing dataset, if nrow + start_row == num_total_row, will call dataset->FinishLoad
* \param dataset handle of dataset
* \param data pointer to the data space
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nrow number of rows
* \param ncol number columns
* \param start_row row start index
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset,
125
126
127
128
129
                                           const void* data,
                                           int data_type,
                                           int32_t nrow,
                                           int32_t ncol,
                                           int32_t start_row);
Guolin Ke's avatar
Guolin Ke committed
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

/*!
* \brief push data to existing dataset, if nrow + start_row == num_total_row, will call dataset->FinishLoad
* \param dataset handle of dataset
* \param indptr pointer to row headers
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
* \param indices findex
* \param data fvalue
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nindptr number of rows in the matrix + 1
* \param nelem number of nonzero elements in the matrix
* \param num_col number of columns
* \param start_row row start index
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset,
146
147
148
149
150
151
152
153
154
                                                const void* indptr,
                                                int indptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t nindptr,
                                                int64_t nelem,
                                                int64_t num_col,
                                                int64_t start_row);
Guolin Ke's avatar
Guolin Ke committed
155

Guolin Ke's avatar
Guolin Ke committed
156
157
158
/*!
* \brief create a dataset from CSR format
* \param indptr pointer to row headers
wxchan's avatar
wxchan committed
159
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
Guolin Ke's avatar
Guolin Ke committed
160
161
* \param indices findex
* \param data fvalue
wxchan's avatar
wxchan committed
162
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
Guolin Ke's avatar
Guolin Ke committed
163
* \param nindptr number of rows in the matrix + 1
Guolin Ke's avatar
Guolin Ke committed
164
* \param nelem number of nonzero elements in the matrix
wxchan's avatar
wxchan committed
165
* \param num_col number of columns
Guolin Ke's avatar
Guolin Ke committed
166
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
167
168
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
wxchan's avatar
wxchan committed
169
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
170
*/
171
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr,
172
173
174
175
176
177
178
179
180
181
                                                int indptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t nindptr,
                                                int64_t nelem,
                                                int64_t num_col,
                                                const char* parameters,
                                                const DatasetHandle reference,
                                                DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
182
183
184
185

/*!
* \brief create a dataset from CSC format
* \param col_ptr pointer to col headers
wxchan's avatar
wxchan committed
186
* \param col_ptr_type type of col_ptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
Guolin Ke's avatar
Guolin Ke committed
187
188
* \param indices findex
* \param data fvalue
wxchan's avatar
wxchan committed
189
190
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param ncol_ptr number of cols in the matrix + 1
Guolin Ke's avatar
Guolin Ke committed
191
* \param nelem number of nonzero elements in the matrix
wxchan's avatar
wxchan committed
192
* \param num_row number of rows
Guolin Ke's avatar
Guolin Ke committed
193
194
195
* \param parameters additional parameters
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
wxchan's avatar
wxchan committed
196
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
197
*/
198
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr,
199
200
201
202
203
204
205
206
207
208
                                                int col_ptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t ncol_ptr,
                                                int64_t nelem,
                                                int64_t num_row,
                                                const char* parameters,
                                                const DatasetHandle reference,
                                                DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
209
210
211
212

/*!
* \brief create dataset from dense matrix
* \param data pointer to the data space
wxchan's avatar
wxchan committed
213
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
Guolin Ke's avatar
Guolin Ke committed
214
215
* \param nrow number of rows
* \param ncol number columns
216
* \param is_row_major 1 for row major, 0 for column major
Guolin Ke's avatar
Guolin Ke committed
217
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
218
219
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
wxchan's avatar
wxchan committed
220
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
221
*/
222
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data,
223
224
225
226
227
228
229
                                                int data_type,
                                                int32_t nrow,
                                                int32_t ncol,
                                                int is_row_major,
                                                const char* parameters,
                                                const DatasetHandle reference,
                                                DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
230

wxchan's avatar
wxchan committed
231
232
233
234
235
236
237
238
239
/*!
* \brief Create subset of a data
* \param handle handle of full dataset
* \param used_row_indices Indices used in subset
* \param num_used_row_indices len of used_row_indices
* \param parameters additional parameters
* \param out subset of data
* \return 0 when succeed, -1 when failure happens
*/
240
LIGHTGBM_C_EXPORT int LGBM_DatasetGetSubset(
241
  const DatasetHandle handle,
wxchan's avatar
wxchan committed
242
243
244
  const int32_t* used_row_indices,
  int32_t num_used_row_indices,
  const char* parameters,
Guolin Ke's avatar
typo  
Guolin Ke committed
245
  DatasetHandle* out);
wxchan's avatar
wxchan committed
246

Guolin Ke's avatar
Guolin Ke committed
247
248
249
250
251
252
253
/*!
* \brief save feature names to Dataset
* \param handle handle
* \param feature_names feature names
* \param num_feature_names number of feature names
* \return 0 when succeed, -1 when failure happens
*/
254
LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(
Guolin Ke's avatar
typo  
Guolin Ke committed
255
  DatasetHandle handle,
Guolin Ke's avatar
Guolin Ke committed
256
  const char** feature_names,
Guolin Ke's avatar
Guolin Ke committed
257
  int num_feature_names);
Guolin Ke's avatar
Guolin Ke committed
258

259
260
261
262
263
264
265
266

/*!
* \brief get feature names of Dataset
* \param handle handle
* \param feature_names feature names, should pre-allocate memory
* \param num_feature_names number of feature names
* \return 0 when succeed, -1 when failure happens
*/
267
LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(
268
269
  DatasetHandle handle,
  char** feature_names,
Guolin Ke's avatar
Guolin Ke committed
270
  int* num_feature_names);
271
272


Guolin Ke's avatar
Guolin Ke committed
273
274
/*!
* \brief free space for dataset
wxchan's avatar
wxchan committed
275
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
276
*/
277
LIGHTGBM_C_EXPORT int LGBM_DatasetFree(DatasetHandle handle);
Guolin Ke's avatar
Guolin Ke committed
278
279
280
281
282

/*!
* \brief save dateset to binary file
* \param handle a instance of dataset
* \param filename file name
wxchan's avatar
wxchan committed
283
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
284
*/
285
LIGHTGBM_C_EXPORT int LGBM_DatasetSaveBinary(DatasetHandle handle,
286
                                             const char* filename);
Guolin Ke's avatar
Guolin Ke committed
287
288
289

/*!
* \brief set vector to a content in info
wxchan's avatar
wxchan committed
290
291
*        Note: group and group only work for C_API_DTYPE_INT32
*              label and weight only work for C_API_DTYPE_FLOAT32
Guolin Ke's avatar
Guolin Ke committed
292
* \param handle a instance of dataset
wxchan's avatar
wxchan committed
293
* \param field_name field name, can be label, weight, group, group_id
294
* \param field_data pointer to vector
Guolin Ke's avatar
Guolin Ke committed
295
* \param num_element number of element in field_data
wxchan's avatar
wxchan committed
296
297
* \param type C_API_DTYPE_FLOAT32 or C_API_DTYPE_INT32
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
298
*/
299
LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle,
300
301
302
303
                                           const char* field_name,
                                           const void* field_data,
                                           int num_element,
                                           int type);
Guolin Ke's avatar
Guolin Ke committed
304
305

/*!
306
* \brief get info vector from dataset
Guolin Ke's avatar
Guolin Ke committed
307
308
309
310
* \param handle a instance of data matrix
* \param field_name field name
* \param out_len used to set result length
* \param out_ptr pointer to the result
wxchan's avatar
wxchan committed
311
312
* \param out_type  C_API_DTYPE_FLOAT32 or C_API_DTYPE_INT32
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
313
*/
314
LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle,
315
316
317
318
                                           const char* field_name,
                                           int* out_len,
                                           const void** out_ptr,
                                           int* out_type);
Guolin Ke's avatar
Guolin Ke committed
319
320
321
322
323

/*!
* \brief get number of data.
* \param handle the handle to the dataset
* \param out The address to hold number of data
wxchan's avatar
wxchan committed
324
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
325
*/
326
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle,
327
                                             int* out);
Guolin Ke's avatar
Guolin Ke committed
328
329
330
331
332

/*!
* \brief get number of features
* \param handle the handle to the dataset
* \param out The output of number of features
wxchan's avatar
wxchan committed
333
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
334
*/
335
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle,
336
                                                int* out);
Guolin Ke's avatar
Guolin Ke committed
337
338
339
340
341

// --- start Booster interfaces

/*!
* \brief create an new boosting learner
Guolin Ke's avatar
Guolin Ke committed
342
* \param train_data training data set
Guolin Ke's avatar
Guolin Ke committed
343
344
* \param parameters format: 'key1=value1 key2=value2'
* \prama out handle of created Booster
wxchan's avatar
wxchan committed
345
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
346
*/
347
LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data,
348
349
                                         const char* parameters,
                                         BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
350
351

/*!
Guolin Ke's avatar
Guolin Ke committed
352
* \brief load an existing boosting from model file
Guolin Ke's avatar
Guolin Ke committed
353
* \param filename filename of model
wxchan's avatar
wxchan committed
354
* \param out_num_iterations number of iterations of this booster
Guolin Ke's avatar
Guolin Ke committed
355
* \param out handle of created Booster
wxchan's avatar
wxchan committed
356
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
357
*/
358
LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(
Guolin Ke's avatar
Guolin Ke committed
359
  const char* filename,
Guolin Ke's avatar
Guolin Ke committed
360
  int* out_num_iterations,
Guolin Ke's avatar
Guolin Ke committed
361
362
  BoosterHandle* out);

363
364
365
366
367
368
369
370
371
372
373
/*!
* \brief load an existing boosting from string
* \param model_str model string
* \param out_num_iterations number of iterations of this booster
* \param out handle of created Booster
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(
  const char* model_str,
  int* out_num_iterations,
  BoosterHandle* out);
wxchan's avatar
wxchan committed
374

Guolin Ke's avatar
Guolin Ke committed
375
376
377
/*!
* \brief free obj in handle
* \param handle handle to be freed
wxchan's avatar
wxchan committed
378
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
379
*/
380
LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle);
Guolin Ke's avatar
Guolin Ke committed
381

wxchan's avatar
wxchan committed
382
383
384
385
386
387
/*!
* \brief Merge model in two booster to first handle
* \param handle handle, will merge other handle to this
* \param other_handle
* \return 0 when succeed, -1 when failure happens
*/
388
LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle,
389
                                        BoosterHandle other_handle);
wxchan's avatar
wxchan committed
390
391
392
393
394
395
396

/*!
* \brief Add new validation to booster
* \param handle handle
* \param valid_data validation data set
* \return 0 when succeed, -1 when failure happens
*/
397
LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle,
398
                                               const DatasetHandle valid_data);
wxchan's avatar
wxchan committed
399
400
401
402
403
404
405

/*!
* \brief Reset training data for booster
* \param handle handle
* \param train_data training data set
* \return 0 when succeed, -1 when failure happens
*/
406
LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle,
407
                                                    const DatasetHandle train_data);
wxchan's avatar
wxchan committed
408
409
410
411
412
413
414

/*!
* \brief Reset config for current booster
* \param handle handle
* \param parameters format: 'key1=value1 key2=value2'
* \return 0 when succeed, -1 when failure happens
*/
415
LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle, const char* parameters);
wxchan's avatar
wxchan committed
416
417

/*!
Guolin Ke's avatar
Guolin Ke committed
418
* \brief Get number of class
wxchan's avatar
wxchan committed
419
420
421
422
* \param handle handle
* \param out_len number of class
* \return 0 when succeed, -1 when failure happens
*/
423
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle, int* out_len);
wxchan's avatar
wxchan committed
424

Guolin Ke's avatar
Guolin Ke committed
425
426
427
/*!
* \brief update the model in one round
* \param handle handle
Guolin Ke's avatar
Guolin Ke committed
428
* \param is_finished 1 means finised(cannot split any more)
wxchan's avatar
wxchan committed
429
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
430
*/
431
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle, int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
432
433
434
435
436
437
438

/*!
* \brief update the model, by directly specify gradient and second order gradient,
*       this can be used to support customized loss function
* \param handle handle
* \param grad gradient statistics
* \param hess second order gradient statistics
Guolin Ke's avatar
Guolin Ke committed
439
* \param is_finished 1 means finised(cannot split any more)
wxchan's avatar
wxchan committed
440
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
441
*/
442
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
443
444
445
                                                      const float* grad,
                                                      const float* hess,
                                                      int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
446
447

/*!
wxchan's avatar
wxchan committed
448
* \brief Rollback one iteration
Guolin Ke's avatar
Guolin Ke committed
449
* \param handle handle
wxchan's avatar
wxchan committed
450
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
451
*/
452
LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle);
wxchan's avatar
wxchan committed
453
454
455
456
457
458

/*!
* \brief Get iteration of current boosting rounds
* \param out_iteration iteration of boosting rounds
* \return 0 when succeed, -1 when failure happens
*/
459
LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle, int* out_iteration);
Guolin Ke's avatar
Guolin Ke committed
460

Guolin Ke's avatar
Guolin Ke committed
461
/*!
Guolin Ke's avatar
Guolin Ke committed
462
* \brief Get number of eval
wxchan's avatar
wxchan committed
463
464
465
* \param out_len total number of eval results
* \return 0 when succeed, -1 when failure happens
*/
466
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle, int* out_len);
wxchan's avatar
wxchan committed
467
468

/*!
wxchan's avatar
wxchan committed
469
* \brief Get name of eval
wxchan's avatar
wxchan committed
470
* \param out_len total number of eval results
Guolin Ke's avatar
typo  
Guolin Ke committed
471
* \param out_strs names of eval result, need to pre-allocate memory before call this
wxchan's avatar
wxchan committed
472
473
* \return 0 when succeed, -1 when failure happens
*/
474
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle, int* out_len, char** out_strs);
wxchan's avatar
wxchan committed
475

wxchan's avatar
wxchan committed
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
/*!
* \brief Get name of features
* \param out_len total number of features
* \param out_strs names of features, need to pre-allocate memory before call this
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle, int* out_len, char** out_strs);

/*!
* \brief Get number of features
* \param out_len total number of features
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle, int* out_len);

wxchan's avatar
wxchan committed
491
492
/*!
* \brief get evaluation for training data and validation data
Guolin Ke's avatar
Guolin Ke committed
493
494
Note: 1. you should call LGBM_BoosterGetEvalNames first to get the name of evaluation results
2. should pre-allocate memory for out_results, you can get its length by LGBM_BoosterGetEvalCounts
Guolin Ke's avatar
Guolin Ke committed
495
* \param handle handle
wxchan's avatar
wxchan committed
496
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
Guolin Ke's avatar
Guolin Ke committed
497
* \param out_len len of output result
wxchan's avatar
wxchan committed
498
499
* \param out_result float arrary contains result
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
500
*/
501
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle,
502
503
504
                                          int data_idx,
                                          int* out_len,
                                          double* out_results);
Guolin Ke's avatar
Guolin Ke committed
505
506
507
508
509
510
511
512
513
514

/*!
* \brief Get number of predict for inner dataset
this can be used to support customized eval function
Note:  should pre-allocate memory for out_result, its length is equal to num_class * num_data
* \param handle handle
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
* \param out_len len of output result
* \return 0 when succeed, -1 when failure happens
*/
515
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle,
516
517
                                                int data_idx,
                                                int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
518

Guolin Ke's avatar
Guolin Ke committed
519
/*!
Guolin Ke's avatar
Guolin Ke committed
520
* \brief Get prediction for training data and validation data
Guolin Ke's avatar
Guolin Ke committed
521
522
this can be used to support customized eval function
Note:  should pre-allocate memory for out_result, its length is equal to num_class * num_data
Guolin Ke's avatar
Guolin Ke committed
523
* \param handle handle
wxchan's avatar
wxchan committed
524
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
Guolin Ke's avatar
Guolin Ke committed
525
* \param out_len len of output result
Guolin Ke's avatar
Guolin Ke committed
526
* \param out_result used to set a pointer to array, should allocate memory before call this function
wxchan's avatar
wxchan committed
527
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
528
*/
529
LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle,
530
531
532
                                             int data_idx,
                                             int64_t* out_len,
                                             double* out_result);
Guolin Ke's avatar
Guolin Ke committed
533

534
535
536
537
/*!
* \brief make prediction for file
* \param handle handle
* \param data_filename filename of data file
wxchan's avatar
wxchan committed
538
539
540
541
542
543
* \param data_has_header data file has header or not
* \param predict_type
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
544
* \param result_filename filename of result file
wxchan's avatar
wxchan committed
545
* \return 0 when succeed, -1 when failure happens
546
*/
547
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle,
548
549
550
551
552
                                                 const char* data_filename,
                                                 int data_has_header,
                                                 int predict_type,
                                                 int num_iteration,
                                                 const char* result_filename);
553

Guolin Ke's avatar
Guolin Ke committed
554
555
556
/*!
* \brief Get number of prediction
* \param handle handle
Guolin Ke's avatar
Guolin Ke committed
557
* \param num_row
Guolin Ke's avatar
Guolin Ke committed
558
559
560
561
562
* \param predict_type
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
563
* \param out_len length of prediction
Guolin Ke's avatar
Guolin Ke committed
564
565
* \return 0 when succeed, -1 when failure happens
*/
566
LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle,
567
568
569
570
                                                 int num_row,
                                                 int predict_type,
                                                 int num_iteration,
                                                 int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
571

Guolin Ke's avatar
Guolin Ke committed
572
573
/*!
* \brief make prediction for an new data set
Guolin Ke's avatar
Guolin Ke committed
574
*        Note:  should pre-allocate memory for out_result,
wxchan's avatar
wxchan committed
575
576
*               for noraml 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
Guolin Ke's avatar
Guolin Ke committed
577
578
* \param handle handle
* \param indptr pointer to row headers
wxchan's avatar
wxchan committed
579
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
Guolin Ke's avatar
Guolin Ke committed
580
581
* \param indices findex
* \param data fvalue
wxchan's avatar
wxchan committed
582
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
Guolin Ke's avatar
Guolin Ke committed
583
* \param nindptr number of rows in the matrix + 1
Guolin Ke's avatar
Guolin Ke committed
584
585
586
* \param nelem number of nonzero elements in the matrix
* \param num_col number of columns; when it's set to 0, then guess from data
* \param predict_type
wxchan's avatar
wxchan committed
587
588
589
590
591
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param out_len len of output result
Guolin Ke's avatar
Guolin Ke committed
592
* \param out_result used to set a pointer to array, should allocate memory before call this function
wxchan's avatar
wxchan committed
593
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
594
*/
595
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle,
596
597
598
599
600
601
602
603
604
605
606
607
                                                const void* indptr,
                                                int indptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t nindptr,
                                                int64_t nelem,
                                                int64_t num_col,
                                                int predict_type,
                                                int num_iteration,
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631

/*!
* \brief make prediction for an new data set
*        Note:  should pre-allocate memory for out_result,
*               for noraml 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
* \param handle handle
* \param col_ptr pointer to col headers
* \param col_ptr_type type of col_ptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
* \param indices findex
* \param data fvalue
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param ncol_ptr number of cols in the matrix + 1
* \param nelem number of nonzero elements in the matrix
* \param num_row number of rows
* \param predict_type
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param out_len len of output result
* \param out_result used to set a pointer to array, should allocate memory before call this function
* \return 0 when succeed, -1 when failure happens
*/
632
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle,
633
634
635
636
637
638
639
640
641
642
643
644
                                                const void* col_ptr,
                                                int col_ptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t ncol_ptr,
                                                int64_t nelem,
                                                int64_t num_row,
                                                int predict_type,
                                                int num_iteration,
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
645
646
647

/*!
* \brief make prediction for an new data set
wxchan's avatar
wxchan committed
648
649
650
*        Note:  should pre-allocate memory for out_result,
*               for noraml 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
Guolin Ke's avatar
Guolin Ke committed
651
652
* \param handle handle
* \param data pointer to the data space
wxchan's avatar
wxchan committed
653
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
Guolin Ke's avatar
Guolin Ke committed
654
655
* \param nrow number of rows
* \param ncol number columns
Guolin Ke's avatar
Guolin Ke committed
656
* \param is_row_major 1 for row major, 0 for column major
Guolin Ke's avatar
Guolin Ke committed
657
* \param predict_type
wxchan's avatar
wxchan committed
658
659
660
661
662
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
* \param out_len len of output result
Guolin Ke's avatar
Guolin Ke committed
663
* \param out_result used to set a pointer to array, should allocate memory before call this function
wxchan's avatar
wxchan committed
664
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
665
*/
666
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle,
667
668
669
670
671
672
673
674
675
                                                const void* data,
                                                int data_type,
                                                int32_t nrow,
                                                int32_t ncol,
                                                int is_row_major,
                                                int predict_type,
                                                int num_iteration,
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
676
677
678
679

/*!
* \brief save model into file
* \param handle handle
wxchan's avatar
wxchan committed
680
* \param num_iteration, <= 0 means save all
Guolin Ke's avatar
Guolin Ke committed
681
* \param filename file name
wxchan's avatar
wxchan committed
682
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
683
*/
684
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle,
685
686
                                            int num_iteration,
                                            const char* filename);
Guolin Ke's avatar
Guolin Ke committed
687

688
689
690
691
692
693
694
695
696
697
/*!
* \brief save model to string
* \param handle handle
* \param num_iteration, <= 0 means save all
* \param buffer_len string buffer length, if buffer_len < out_len, re-allocate buffer
* \param out_len actual output length
* \param out_str string of model, need to pre-allocate memory before call this
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle,
698
699
700
701
                                                    int num_iteration,
                                                    int buffer_len,
                                                    int* out_len,
                                                    char* out_str);
702

wxchan's avatar
wxchan committed
703
704
705
/*!
* \brief dump model to json
* \param handle handle
706
* \param num_iteration, <= 0 means save all
wxchan's avatar
wxchan committed
707
708
* \param buffer_len string buffer length, if buffer_len < out_len, re-allocate buffer
* \param out_len actual output length
Guolin Ke's avatar
typo  
Guolin Ke committed
709
* \param out_str json format string of model, need to pre-allocate memory before call this
wxchan's avatar
wxchan committed
710
711
* \return 0 when succeed, -1 when failure happens
*/
712
LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle,
713
714
715
716
                                            int num_iteration,
                                            int buffer_len,
                                            int* out_len,
                                            char* out_str);
717

Guolin Ke's avatar
Guolin Ke committed
718
/*!
Guolin Ke's avatar
Guolin Ke committed
719
* \brief Get leaf value
Guolin Ke's avatar
Guolin Ke committed
720
721
722
723
724
725
* \param handle handle
* \param tree_idx index of tree
* \param leaf_idx index of leaf
* \param out_val out result
* \return 0 when succeed, -1 when failure happens
*/
726
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle,
727
728
729
                                               int tree_idx,
                                               int leaf_idx,
                                               double* out_val);
Guolin Ke's avatar
Guolin Ke committed
730
731
732
733
734
735
736
737
738

/*!
* \brief Set leaf value
* \param handle handle
* \param tree_idx index of tree
* \param leaf_idx index of leaf
* \param val leaf value
* \return 0 when succeed, -1 when failure happens
*/
739
LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle,
740
741
742
                                               int tree_idx,
                                               int leaf_idx,
                                               double val);
743

wxchan's avatar
wxchan committed
744
#if defined(_MSC_VER)
745
// exception handle and error msg
wxchan's avatar
wxchan committed
746
747
748
749
static char* LastErrorMsg() { static __declspec(thread) char err_msg[512] = "Everything is fine"; return err_msg; }
#else
static char* LastErrorMsg() { static thread_local char err_msg[512] = "Everything is fine"; return err_msg; }
#endif
750
751

inline void LGBM_SetLastError(const char* msg) {
wxchan's avatar
wxchan committed
752
  std::strcpy(LastErrorMsg(), msg);
753
754
755
756
757
758
759
760
761
762
763
}

inline int LGBM_APIHandleException(const std::exception& ex) {
  LGBM_SetLastError(ex.what());
  return -1;
}
inline int LGBM_APIHandleException(const std::string& ex) {
  LGBM_SetLastError(ex.c_str());
  return -1;
}

764
#define API_BEGIN() Log::ResetUseException(true); try {
765
766
767
768
769

#define API_END() } \
catch(std::exception& ex) { return LGBM_APIHandleException(ex); } \
catch(std::string& ex) { return LGBM_APIHandleException(ex); } \
catch(...) { return LGBM_APIHandleException("unknown exception"); } \
wxchan's avatar
wxchan committed
770
return 0;
771

Guolin Ke's avatar
Guolin Ke committed
772
#endif // LIGHTGBM_C_API_H_