c_api.h 56.9 KB
Newer Older
1
/*!
2
3
4
5
6
7
8
9
10
11
 * \file c_api.h
 * \copyright Copyright (c) 2016 Microsoft Corporation. All rights reserved.
 *            Licensed under the MIT License. See LICENSE file in the project root for license information.
 * \note
 * To avoid type conversion on large data, the most of our exposed interface supports both float32 and float64,
 * except the following:
 *   1. gradient and Hessian;
 *   2. current score for training and validation data.
 *   .
 * The reason is that they are called frequently, and the type conversion on them may be time-cost.
12
 */
Guolin Ke's avatar
Guolin Ke committed
13
14
#ifndef LIGHTGBM_C_API_H_
#define LIGHTGBM_C_API_H_
ww's avatar
ww committed
15

16
17
#include <LightGBM/export.h>

18
#include <cstdint>
19
#include <cstdio>
wxchan's avatar
wxchan committed
20
21
#include <cstring>

22

23
24
typedef void* DatasetHandle;  /*!< \brief Handle of dataset. */
typedef void* BoosterHandle;  /*!< \brief Handle of booster. */
Guolin Ke's avatar
Guolin Ke committed
25

26
27
28
29
#define C_API_DTYPE_FLOAT32 (0)  /*!< \brief float32 (single precision float). */
#define C_API_DTYPE_FLOAT64 (1)  /*!< \brief float64 (double precision float). */
#define C_API_DTYPE_INT32   (2)  /*!< \brief int32. */
#define C_API_DTYPE_INT64   (3)  /*!< \brief int64. */
Guolin Ke's avatar
Guolin Ke committed
30

31
32
33
34
#define C_API_PREDICT_NORMAL     (0)  /*!< \brief Normal prediction, with transform (if needed). */
#define C_API_PREDICT_RAW_SCORE  (1)  /*!< \brief Predict raw score. */
#define C_API_PREDICT_LEAF_INDEX (2)  /*!< \brief Predict leaf index. */
#define C_API_PREDICT_CONTRIB    (3)  /*!< \brief Predict feature contributions (SHAP values). */
35

36
37
38
#define C_API_MATRIX_TYPE_CSR (0)  /*!< \brief CSR sparse matrix type. */
#define C_API_MATRIX_TYPE_CSC (1)  /*!< \brief CSC sparse matrix type. */

39
40
41
#define C_API_FEATURE_IMPORTANCE_SPLIT (0)  /*!< \brief Split type of feature importance. */
#define C_API_FEATURE_IMPORTANCE_GAIN  (1)  /*!< \brief Gain type of feature importance. */

Guolin Ke's avatar
Guolin Ke committed
42
/*!
43
 * \brief Get string message of the last error.
44
45
 * \return Error information
 */
46
LIGHTGBM_C_EXPORT const char* LGBM_GetLastError();
Guolin Ke's avatar
Guolin Ke committed
47

48
49
50
51
52
53
54
/*!
 * \brief Register a callback function for log redirecting. 
 * \param callback The callback function to register
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_RegisterLogCallback(void (*callback)(const char*));

Guolin Ke's avatar
Guolin Ke committed
55
// --- start Dataset interface
Guolin Ke's avatar
Guolin Ke committed
56
57

/*!
58
59
60
61
62
63
 * \brief Load dataset from file (like LightGBM CLI version does).
 * \param filename The name of the file
 * \param parameters Additional parameters
 * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
 * \param[out] out A loaded dataset
 * \return 0 when succeed, -1 when failure happens
64
 */
65
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename,
66
67
68
                                                 const char* parameters,
                                                 const DatasetHandle reference,
                                                 DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
69

70
/*!
71
72
 * \brief Allocate the space for dataset and bucket feature bins according to sampled data.
 * \param sample_data Sampled data, grouped by the column
73
74
75
76
77
78
79
80
 * \param sample_indices Indices of sampled data
 * \param ncol Number of columns
 * \param num_per_col Size of each sampling column
 * \param num_sample_row Number of sampled rows
 * \param num_total_row Number of total rows
 * \param parameters Additional parameters
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
81
 */
82
83
84
85
86
87
88
89
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledColumn(double** sample_data,
                                                          int** sample_indices,
                                                          int32_t ncol,
                                                          const int* num_per_col,
                                                          int32_t num_sample_row,
                                                          int32_t num_total_row,
                                                          const char* parameters,
                                                          DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
90
91

/*!
92
 * \brief Allocate the space for dataset and bucket feature bins according to reference dataset.
93
94
95
96
 * \param reference Used to align bin mapper with other dataset
 * \param num_total_row Number of total rows
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
97
 */
Guolin Ke's avatar
Guolin Ke committed
98
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateByReference(const DatasetHandle reference,
99
100
                                                    int64_t num_total_row,
                                                    DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
101
102

/*!
103
 * \brief Push data to existing dataset, if ``nrow + start_row == num_total_row``, will call ``dataset->FinishLoad``.
104
105
 * \param dataset Handle of dataset
 * \param data Pointer to the data space
106
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
107
108
109
110
 * \param nrow Number of rows
 * \param ncol Number of columns
 * \param start_row Row start index
 * \return 0 when succeed, -1 when failure happens
111
 */
Guolin Ke's avatar
Guolin Ke committed
112
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset,
113
114
115
116
117
                                           const void* data,
                                           int data_type,
                                           int32_t nrow,
                                           int32_t ncol,
                                           int32_t start_row);
Guolin Ke's avatar
Guolin Ke committed
118
119

/*!
120
 * \brief Push data to existing dataset, if ``nrow + start_row == num_total_row``, will call ``dataset->FinishLoad``.
121
122
 * \param dataset Handle of dataset
 * \param indptr Pointer to row headers
123
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
124
125
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
126
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
127
128
129
130
131
 * \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
132
 */
Guolin Ke's avatar
Guolin Ke committed
133
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset,
134
135
136
137
138
139
140
141
142
                                                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
143

Guolin Ke's avatar
Guolin Ke committed
144
/*!
145
146
 * \brief Create a dataset from CSR format.
 * \param indptr Pointer to row headers
147
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
148
149
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
150
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
151
152
153
154
155
156
157
 * \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 parameters Additional parameters
 * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
158
 */
159
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr,
160
161
162
163
164
165
166
167
168
169
                                                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
170

171
/*!
172
 * \brief Create a dataset from CSR format through callbacks.
173
174
 * \param get_row_funptr Pointer to ``std::function<void(int idx, std::vector<std::pair<int, double>>& ret)>``
 *                       (called for every row and expected to clear and fill ``ret``)
175
176
177
178
179
180
 * \param num_rows Number of rows
 * \param num_col Number of columns
 * \param parameters Additional parameters
 * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
181
 */
182
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSRFunc(void* get_row_funptr,
183
184
185
186
187
                                                    int num_rows,
                                                    int64_t num_col,
                                                    const char* parameters,
                                                    const DatasetHandle reference,
                                                    DatasetHandle* out);
188

Guolin Ke's avatar
Guolin Ke committed
189
/*!
190
191
 * \brief Create a dataset from CSC format.
 * \param col_ptr Pointer to column headers
192
 * \param col_ptr_type Type of ``col_ptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
193
194
 * \param indices Pointer to row indices
 * \param data Pointer to the data space
195
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
196
197
198
199
200
201
202
 * \param ncol_ptr Number of columns in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
 * \param num_row Number of rows
 * \param parameters Additional parameters
 * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
203
 */
204
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr,
205
206
207
208
209
210
211
212
213
214
                                                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
215
216

/*!
217
218
 * \brief Create dataset from dense matrix.
 * \param data Pointer to the data space
219
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
220
221
222
223
224
225
226
 * \param nrow Number of rows
 * \param ncol Number of columns
 * \param is_row_major 1 for row-major, 0 for column-major
 * \param parameters Additional parameters
 * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
227
 */
228
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data,
229
230
231
232
233
234
235
                                                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
236

237
/*!
238
239
240
 * \brief Create dataset from array of dense matrices.
 * \param nmat Number of dense matrices
 * \param data Pointer to the data space
241
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
242
243
244
245
246
247
248
 * \param nrow Number of rows
 * \param ncol Number of columns
 * \param is_row_major 1 for row-major, 0 for column-major
 * \param parameters Additional parameters
 * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
249
 */
250
251
252
253
254
255
256
257
258
259
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMats(int32_t nmat,
                                                 const void** data,
                                                 int data_type,
                                                 int32_t* nrow,
                                                 int32_t ncol,
                                                 int is_row_major,
                                                 const char* parameters,
                                                 const DatasetHandle reference,
                                                 DatasetHandle* out);

wxchan's avatar
wxchan committed
260
/*!
261
262
263
 * \brief Create subset of a data.
 * \param handle Handle of full dataset
 * \param used_row_indices Indices used in subset
264
 * \param num_used_row_indices Length of ``used_row_indices``
265
266
267
 * \param parameters Additional parameters
 * \param[out] out Subset of data
 * \return 0 when succeed, -1 when failure happens
268
 */
269
270
271
272
273
LIGHTGBM_C_EXPORT int LGBM_DatasetGetSubset(const DatasetHandle handle,
                                            const int32_t* used_row_indices,
                                            int32_t num_used_row_indices,
                                            const char* parameters,
                                            DatasetHandle* out);
wxchan's avatar
wxchan committed
274

Guolin Ke's avatar
Guolin Ke committed
275
/*!
276
277
278
279
280
 * \brief Save feature names to dataset.
 * \param handle Handle of dataset
 * \param feature_names Feature names
 * \param num_feature_names Number of feature names
 * \return 0 when succeed, -1 when failure happens
281
 */
282
283
284
LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(DatasetHandle handle,
                                                  const char** feature_names,
                                                  int num_feature_names);
Guolin Ke's avatar
Guolin Ke committed
285

286
/*!
287
288
 * \brief Get feature names of dataset.
 * \param handle Handle of dataset
289
290
 * \param len Number of ``char*`` pointers stored at ``out_strs``.
 *            If smaller than the max size, only this many strings are copied
291
 * \param[out] num_feature_names Number of feature names
292
293
294
295
 * \param buffer_len Size of pre-allocated strings.
 *                   Content is copied up to ``buffer_len - 1`` and null-terminated
 * \param[out] out_buffer_len String sizes required to do the full string copies
 * \param[out] feature_names Feature names, should pre-allocate memory
296
 * \return 0 when succeed, -1 when failure happens
297
 */
298
LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(DatasetHandle handle,
299
300
301
302
303
                                                  const int len,
                                                  int* num_feature_names,
                                                  const size_t buffer_len,
                                                  size_t* out_buffer_len,
                                                  char** feature_names);
304

Guolin Ke's avatar
Guolin Ke committed
305
/*!
306
307
308
 * \brief Free space for dataset.
 * \param handle Handle of dataset to be freed
 * \return 0 when succeed, -1 when failure happens
309
 */
310
LIGHTGBM_C_EXPORT int LGBM_DatasetFree(DatasetHandle handle);
Guolin Ke's avatar
Guolin Ke committed
311
312

/*!
313
314
 * \brief Save dataset to binary file.
 * \param handle Handle of dataset
315
 * \param filename The name of the file
316
 * \return 0 when succeed, -1 when failure happens
317
 */
318
LIGHTGBM_C_EXPORT int LGBM_DatasetSaveBinary(DatasetHandle handle,
319
                                             const char* filename);
Guolin Ke's avatar
Guolin Ke committed
320

321
/*!
322
323
 * \brief Save dataset to text file, intended for debugging use only.
 * \param handle Handle of dataset
324
 * \param filename The name of the file
325
 * \return 0 when succeed, -1 when failure happens
326
 */
327
328
329
LIGHTGBM_C_EXPORT int LGBM_DatasetDumpText(DatasetHandle handle,
                                           const char* filename);

Guolin Ke's avatar
Guolin Ke committed
330
/*!
331
 * \brief Set vector to a content in info.
332
333
334
 * \note
 * - \a group only works for ``C_API_DTYPE_INT32``;
 * - \a label and \a weight only work for ``C_API_DTYPE_FLOAT32``;
335
 * - \a init_score only works for ``C_API_DTYPE_FLOAT64``.
336
 * \param handle Handle of dataset
337
 * \param field_name Field name, can be \a label, \a weight, \a init_score, \a group
338
 * \param field_data Pointer to data vector
339
 * \param num_element Number of elements in ``field_data``
340
 * \param type Type of ``field_data`` pointer, can be ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
341
 * \return 0 when succeed, -1 when failure happens
342
 */
343
LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle,
344
345
346
347
                                           const char* field_name,
                                           const void* field_data,
                                           int num_element,
                                           int type);
Guolin Ke's avatar
Guolin Ke committed
348
349

/*!
350
351
352
353
354
 * \brief Get info vector from dataset.
 * \param handle Handle of dataset
 * \param field_name Field name
 * \param[out] out_len Used to set result length
 * \param[out] out_ptr Pointer to the result
355
 * \param[out] out_type Type of result pointer, can be ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
356
 * \return 0 when succeed, -1 when failure happens
357
 */
358
LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle,
359
360
361
362
                                           const char* field_name,
                                           int* out_len,
                                           const void** out_ptr,
                                           int* out_type);
Guolin Ke's avatar
Guolin Ke committed
363

364
/*!
365
366
367
368
 * \brief Raise errors for attempts to update dataset parameters.
 * \param old_parameters Current dataset parameters
 * \param new_parameters New dataset parameters
 * \return 0 when succeed, -1 when failure happens
369
 */
370
371
LIGHTGBM_C_EXPORT int LGBM_DatasetUpdateParamChecking(const char* old_parameters,
                                                      const char* new_parameters);
372

Guolin Ke's avatar
Guolin Ke committed
373
/*!
374
375
376
377
 * \brief Get number of data points.
 * \param handle Handle of dataset
 * \param[out] out The address to hold number of data points
 * \return 0 when succeed, -1 when failure happens
378
 */
379
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle,
380
                                             int* out);
Guolin Ke's avatar
Guolin Ke committed
381
382

/*!
383
384
385
386
 * \brief Get number of features.
 * \param handle Handle of dataset
 * \param[out] out The address to hold number of features
 * \return 0 when succeed, -1 when failure happens
387
 */
388
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle,
389
                                                int* out);
Guolin Ke's avatar
Guolin Ke committed
390

391
/*!
392
 * \brief Add features from ``source`` to ``target``.
393
394
395
 * \param target The handle of the dataset to add features to
 * \param source The handle of the dataset to take features from
 * \return 0 when succeed, -1 when failure happens
396
 */
397
398
399
LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target,
                                                  DatasetHandle source);

Guolin Ke's avatar
Guolin Ke committed
400
401
402
// --- start Booster interfaces

/*!
403
404
 * \brief Create a new boosting learner.
 * \param train_data Training dataset
405
 * \param parameters Parameters in format 'key1=value1 key2=value2'
406
 * \param[out] out Handle of created booster
407
408
 * \return 0 when succeed, -1 when failure happens
 */
409
LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data,
410
411
                                         const char* parameters,
                                         BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
412
413

/*!
414
415
416
417
418
 * \brief Load an existing booster from model file.
 * \param filename Filename of model
 * \param[out] out_num_iterations Number of iterations of this booster
 * \param[out] out Handle of created booster
 * \return 0 when succeed, -1 when failure happens
419
 */
420
421
422
LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(const char* filename,
                                                      int* out_num_iterations,
                                                      BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
423

424
/*!
425
426
427
428
429
 * \brief Load an existing booster from string.
 * \param model_str Model string
 * \param[out] out_num_iterations Number of iterations of this booster
 * \param[out] out Handle of created booster
 * \return 0 when succeed, -1 when failure happens
430
 */
431
432
433
LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(const char* model_str,
                                                      int* out_num_iterations,
                                                      BoosterHandle* out);
wxchan's avatar
wxchan committed
434

Guolin Ke's avatar
Guolin Ke committed
435
/*!
436
437
438
 * \brief Free space for booster.
 * \param handle Handle of booster to be freed
 * \return 0 when succeed, -1 when failure happens
439
 */
440
LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle);
Guolin Ke's avatar
Guolin Ke committed
441

442
/*!
443
444
445
446
447
 * \brief Shuffle models.
 * \param handle Handle of booster
 * \param start_iter The first iteration that will be shuffled
 * \param end_iter The last iteration that will be shuffled
 * \return 0 when succeed, -1 when failure happens
448
 */
449
450
451
LIGHTGBM_C_EXPORT int LGBM_BoosterShuffleModels(BoosterHandle handle,
                                                int start_iter,
                                                int end_iter);
452

wxchan's avatar
wxchan committed
453
/*!
454
 * \brief Merge model from ``other_handle`` into ``handle``.
455
456
457
 * \param handle Handle of booster, will merge another booster into this one
 * \param other_handle Other handle of booster
 * \return 0 when succeed, -1 when failure happens
458
 */
459
LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle,
460
                                        BoosterHandle other_handle);
wxchan's avatar
wxchan committed
461
462

/*!
463
464
465
466
 * \brief Add new validation data to booster.
 * \param handle Handle of booster
 * \param valid_data Validation dataset
 * \return 0 when succeed, -1 when failure happens
467
 */
468
LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle,
469
                                               const DatasetHandle valid_data);
wxchan's avatar
wxchan committed
470
471

/*!
472
473
474
475
 * \brief Reset training data for booster.
 * \param handle Handle of booster
 * \param train_data Training dataset
 * \return 0 when succeed, -1 when failure happens
476
 */
477
LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle,
478
                                                    const DatasetHandle train_data);
wxchan's avatar
wxchan committed
479
480

/*!
481
482
 * \brief Reset config for booster.
 * \param handle Handle of booster
483
 * \param parameters Parameters in format 'key1=value1 key2=value2'
484
 * \return 0 when succeed, -1 when failure happens
485
 */
486
487
LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle,
                                                 const char* parameters);
wxchan's avatar
wxchan committed
488
489

/*!
490
491
492
493
 * \brief Get number of classes.
 * \param handle Handle of booster
 * \param[out] out_len Number of classes
 * \return 0 when succeed, -1 when failure happens
494
 */
495
496
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
497

Guolin Ke's avatar
Guolin Ke committed
498
/*!
499
500
 * \brief Update the model for one iteration.
 * \param handle Handle of booster
501
 * \param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure
502
 * \return 0 when succeed, -1 when failure happens
503
 */
504
505
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle,
                                                int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
506

Guolin Ke's avatar
Guolin Ke committed
507
/*!
508
509
510
 * \brief Refit the tree model using the new data (online learning).
 * \param handle Handle of booster
 * \param leaf_preds Pointer to predicted leaf indices
511
512
 * \param nrow Number of rows of ``leaf_preds``
 * \param ncol Number of columns of ``leaf_preds``
513
 * \return 0 when succeed, -1 when failure happens
514
 */
515
516
517
518
LIGHTGBM_C_EXPORT int LGBM_BoosterRefit(BoosterHandle handle,
                                        const int32_t* leaf_preds,
                                        int32_t nrow,
                                        int32_t ncol);
Guolin Ke's avatar
Guolin Ke committed
519

Guolin Ke's avatar
Guolin Ke committed
520
/*!
521
522
523
524
525
 * \brief Update the model by specifying gradient and Hessian directly
 *        (this can be used to support customized loss functions).
 * \param handle Handle of booster
 * \param grad The first order derivative (gradient) statistics
 * \param hess The second order derivative (Hessian) statistics
526
 * \param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure
527
 * \return 0 when succeed, -1 when failure happens
528
 */
529
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
530
531
532
                                                      const float* grad,
                                                      const float* hess,
                                                      int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
533
534

/*!
535
536
537
 * \brief Rollback one iteration.
 * \param handle Handle of booster
 * \return 0 when succeed, -1 when failure happens
538
 */
539
LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle);
wxchan's avatar
wxchan committed
540
541

/*!
542
543
544
545
 * \brief Get index of the current boosting iteration.
 * \param handle Handle of booster
 * \param[out] out_iteration Index of the current boosting iteration
 * \return 0 when succeed, -1 when failure happens
546
 */
547
548
LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle,
                                                      int* out_iteration);
Guolin Ke's avatar
Guolin Ke committed
549

550
/*!
551
552
553
554
 * \brief Get number of trees per iteration.
 * \param handle Handle of booster
 * \param[out] out_tree_per_iteration Number of trees per iteration
 * \return 0 when succeed, -1 when failure happens
555
 */
556
557
LIGHTGBM_C_EXPORT int LGBM_BoosterNumModelPerIteration(BoosterHandle handle,
                                                       int* out_tree_per_iteration);
558
559

/*!
560
561
562
563
 * \brief Get number of weak sub-models.
 * \param handle Handle of booster
 * \param[out] out_models Number of weak sub-models
 * \return 0 when succeed, -1 when failure happens
564
 */
565
566
LIGHTGBM_C_EXPORT int LGBM_BoosterNumberOfTotalModel(BoosterHandle handle,
                                                     int* out_models);
567

Guolin Ke's avatar
Guolin Ke committed
568
/*!
569
570
571
572
 * \brief Get number of evaluation datasets.
 * \param handle Handle of booster
 * \param[out] out_len Total number of evaluation datasets
 * \return 0 when succeed, -1 when failure happens
573
 */
574
575
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
576
577

/*!
578
579
 * \brief Get names of evaluation datasets.
 * \param handle Handle of booster
580
581
 * \param len Number of ``char*`` pointers stored at ``out_strs``.
 *            If smaller than the max size, only this many strings are copied
582
 * \param[out] out_len Total number of evaluation datasets
583
584
585
 * \param buffer_len Size of pre-allocated strings. 
 *                   Content is copied up to ``buffer_len - 1`` and null-terminated
 * \param[out] out_buffer_len String sizes required to do the full string copies
586
587
 * \param[out] out_strs Names of evaluation datasets, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
588
 */
589
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle,
590
                                               const int len,
591
                                               int* out_len,
592
593
                                               const size_t buffer_len,
                                               size_t* out_buffer_len,
594
                                               char** out_strs);
wxchan's avatar
wxchan committed
595

wxchan's avatar
wxchan committed
596
/*!
597
598
 * \brief Get names of features.
 * \param handle Handle of booster
599
600
 * \param len Number of ``char*`` pointers stored at ``out_strs``.
 *            If smaller than the max size, only this many strings are copied
601
 * \param[out] out_len Total number of features
602
603
604
 * \param buffer_len Size of pre-allocated strings.
 *                   Content is copied up to ``buffer_len - 1`` and null-terminated
 * \param[out] out_buffer_len String sizes required to do the full string copies
605
606
 * \param[out] out_strs Names of features, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
607
 */
608
LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle,
609
                                                  const int len,
610
                                                  int* out_len,
611
612
                                                  const size_t buffer_len,
                                                  size_t* out_buffer_len,
613
                                                  char** out_strs);
wxchan's avatar
wxchan committed
614
615

/*!
616
617
618
619
 * \brief Get number of features.
 * \param handle Handle of booster
 * \param[out] out_len Total number of features
 * \return 0 when succeed, -1 when failure happens
620
 */
621
622
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
623

wxchan's avatar
wxchan committed
624
/*!
625
 * \brief Get evaluation for training data and validation data.
626
627
628
 * \note
 *   1. You should call ``LGBM_BoosterGetEvalNames`` first to get the names of evaluation datasets.
 *   2. You should pre-allocate memory for ``out_results``, you can get its length by ``LGBM_BoosterGetEvalCounts``.
629
630
631
 * \param handle Handle of booster
 * \param data_idx Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on
 * \param[out] out_len Length of output result
632
 * \param[out] out_results Array with evaluation results
633
 * \return 0 when succeed, -1 when failure happens
634
 */
635
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle,
636
637
638
                                          int data_idx,
                                          int* out_len,
                                          double* out_results);
Guolin Ke's avatar
Guolin Ke committed
639
640

/*!
641
642
 * \brief Get number of predictions for training data and validation data
 *        (this can be used to support customized evaluation functions).
643
644
645
646
 * \param handle Handle of booster
 * \param data_idx Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on
 * \param[out] out_len Number of predictions
 * \return 0 when succeed, -1 when failure happens
647
 */
648
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle,
649
650
                                                int data_idx,
                                                int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
651

Guolin Ke's avatar
Guolin Ke committed
652
/*!
653
 * \brief Get prediction for training data and validation data.
654
655
 * \note
 * You should pre-allocate memory for ``out_result``, its length is equal to ``num_class * num_data``.
656
657
658
659
660
 * \param handle Handle of booster
 * \param data_idx Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on
 * \param[out] out_len Length of output result
 * \param[out] out_result Pointer to array with predictions
 * \return 0 when succeed, -1 when failure happens
661
 */
662
LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle,
663
664
665
                                             int data_idx,
                                             int64_t* out_len,
                                             double* out_result);
Guolin Ke's avatar
Guolin Ke committed
666

667
/*!
668
669
670
671
672
 * \brief Make prediction for file.
 * \param handle Handle of booster
 * \param data_filename Filename of file with data
 * \param data_has_header Whether file has header or not
 * \param predict_type What should be predicted
673
674
675
676
 *   - ``C_API_PREDICT_NORMAL``: normal prediction, with transform (if needed);
 *   - ``C_API_PREDICT_RAW_SCORE``: raw score;
 *   - ``C_API_PREDICT_LEAF_INDEX``: leaf index;
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
677
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
678
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
679
680
 * \param result_filename Filename of result file in which predictions will be written
 * \return 0 when succeed, -1 when failure happens
681
 */
682
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle,
683
684
685
686
                                                 const char* data_filename,
                                                 int data_has_header,
                                                 int predict_type,
                                                 int num_iteration,
687
                                                 const char* parameter,
688
                                                 const char* result_filename);
689

Guolin Ke's avatar
Guolin Ke committed
690
/*!
691
692
693
694
 * \brief Get number of predictions.
 * \param handle Handle of booster
 * \param num_row Number of rows
 * \param predict_type What should be predicted
695
696
697
698
 *   - ``C_API_PREDICT_NORMAL``: normal prediction, with transform (if needed);
 *   - ``C_API_PREDICT_RAW_SCORE``: raw score;
 *   - ``C_API_PREDICT_LEAF_INDEX``: leaf index;
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
699
700
701
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
 * \param[out] out_len Length of prediction
 * \return 0 when succeed, -1 when failure happens
702
 */
703
LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle,
704
705
706
707
                                                 int num_row,
                                                 int predict_type,
                                                 int num_iteration,
                                                 int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
708

Guolin Ke's avatar
Guolin Ke committed
709
/*!
710
 * \brief Make prediction for a new dataset in CSR format.
711
712
713
714
715
 * \note
 * You 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``;
 *   - for feature contributions, its length is equal to ``num_class * num_data * (num_feature + 1)``.
716
717
 * \param handle Handle of booster
 * \param indptr Pointer to row headers
718
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
719
720
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
721
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
722
723
 * \param nindptr Number of rows in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
724
 * \param num_col Number of columns
725
 * \param predict_type What should be predicted
726
727
728
729
 *   - ``C_API_PREDICT_NORMAL``: normal prediction, with transform (if needed);
 *   - ``C_API_PREDICT_RAW_SCORE``: raw score;
 *   - ``C_API_PREDICT_LEAF_INDEX``: leaf index;
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
730
731
732
733
734
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
 * \param[out] out_len Length of output result
 * \param[out] out_result Pointer to array with predictions
 * \return 0 when succeed, -1 when failure happens
735
 */
736
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle,
737
738
739
740
741
742
743
744
745
746
                                                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,
747
                                                const char* parameter,
748
749
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
750

751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
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
806
/*!
 * \brief Make sparse prediction for a new dataset in CSR or CSC format. Currently only used for feature contributions.
 * \note
 * The outputs are pre-allocated, as they can vary for each invocation, but the shape should be the same:
 *   - for feature contributions, the shape of sparse matrix will be ``num_class * num_data * (num_feature + 1)``.
 * The output indptr_type for the sparse matrix will be the same as the given input indptr_type.
 * Call ``LGBM_BoosterFreePredictSparse`` to deallocate resources.
 * \param handle Handle of booster
 * \param indptr Pointer to row headers for CSR or column headers for CSC
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
 * \param indices Pointer to column indices for CSR or row indices for CSC
 * \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 nindptr Number of rows in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
 * \param num_col_or_row Number of columns for CSR or number of rows for CSC
 * \param predict_type What should be predicted, only feature contributions supported currently
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
 * \param matrix_type Type of matrix input and output, can be ``C_API_MATRIX_TYPE_CSR`` or ``C_API_MATRIX_TYPE_CSC``
 * \param[out] out_len Length of output indices and data
 * \param[out] out_indptr Pointer to output row headers for CSR or column headers for CSC
 * \param[out] out_indices Pointer to sparse column indices for CSR or row indices for CSC
 * \param[out] out_data Pointer to sparse data space
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictSparseOutput(BoosterHandle handle,
                                                      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_or_row,
                                                      int predict_type,
                                                      int num_iteration,
                                                      const char* parameter,
                                                      int matrix_type,
                                                      int64_t* out_len,
                                                      void** out_indptr,
                                                      int32_t** out_indices,
                                                      void** out_data);

/*!
 * \brief Method corresponding to ``LGBM_BoosterPredictSparseOutput`` to free the allocated data.
 * \param indptr Pointer to output row headers or column headers to be deallocated
 * \param indices Pointer to sparse indices to be deallocated
 * \param data Pointer to sparse data space to be deallocated
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterFreePredictSparse(void* indptr, int32_t* indices, void* data, int indptr_type, int data_type);

807
/*!
808
 * \brief Make prediction for a new dataset in CSR format. This method re-uses the internal predictor structure
809
 *        from previous calls and is optimized for single row invocation.
810
811
812
813
814
 * \note
 * You 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``;
 *   - for feature contributions, its length is equal to ``num_class * num_data * (num_feature + 1)``.
815
816
 * \param handle Handle of booster
 * \param indptr Pointer to row headers
817
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
818
819
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
820
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
821
822
 * \param nindptr Number of rows in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
823
 * \param num_col Number of columns
824
 * \param predict_type What should be predicted
825
826
827
828
 *   - ``C_API_PREDICT_NORMAL``: normal prediction, with transform (if needed);
 *   - ``C_API_PREDICT_RAW_SCORE``: raw score;
 *   - ``C_API_PREDICT_LEAF_INDEX``: leaf index;
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
829
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
830
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
831
832
833
 * \param[out] out_len Length of output result
 * \param[out] out_result Pointer to array with predictions
 * \return 0 when succeed, -1 when failure happens
834
 */
835
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRow(BoosterHandle handle,
836
837
838
839
840
841
842
843
844
845
846
847
848
                                                         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,
                                                         const char* parameter,
                                                         int64_t* out_len,
                                                         double* out_result);
849

Guolin Ke's avatar
Guolin Ke committed
850
/*!
851
 * \brief Make prediction for a new dataset in CSC format.
852
853
854
855
856
 * \note
 * You 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``;
 *   - for feature contributions, its length is equal to ``num_class * num_data * (num_feature + 1)``.
857
858
 * \param handle Handle of booster
 * \param col_ptr Pointer to column headers
859
 * \param col_ptr_type Type of ``col_ptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
860
861
 * \param indices Pointer to row indices
 * \param data Pointer to the data space
862
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
863
864
865
866
 * \param ncol_ptr Number of columns in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
 * \param num_row Number of rows
 * \param predict_type What should be predicted
867
868
869
870
 *   - ``C_API_PREDICT_NORMAL``: normal prediction, with transform (if needed);
 *   - ``C_API_PREDICT_RAW_SCORE``: raw score;
 *   - ``C_API_PREDICT_LEAF_INDEX``: leaf index;
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
871
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
872
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
873
874
875
 * \param[out] out_len Length of output result
 * \param[out] out_result Pointer to array with predictions
 * \return 0 when succeed, -1 when failure happens
876
 */
877
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle,
878
879
880
881
882
883
884
885
886
887
                                                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,
888
                                                const char* parameter,
889
890
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
891
892

/*!
893
 * \brief Make prediction for a new dataset.
894
895
896
897
898
 * \note
 * You 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``;
 *   - for feature contributions, its length is equal to ``num_class * num_data * (num_feature + 1)``.
899
900
 * \param handle Handle of booster
 * \param data Pointer to the data space
901
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
902
903
904
905
 * \param nrow Number of rows
 * \param ncol Number of columns
 * \param is_row_major 1 for row-major, 0 for column-major
 * \param predict_type What should be predicted
906
907
908
909
 *   - ``C_API_PREDICT_NORMAL``: normal prediction, with transform (if needed);
 *   - ``C_API_PREDICT_RAW_SCORE``: raw score;
 *   - ``C_API_PREDICT_LEAF_INDEX``: leaf index;
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
910
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
911
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
912
913
914
 * \param[out] out_len Length of output result
 * \param[out] out_result Pointer to array with predictions
 * \return 0 when succeed, -1 when failure happens
915
 */
916
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle,
917
918
919
920
921
922
923
                                                const void* data,
                                                int data_type,
                                                int32_t nrow,
                                                int32_t ncol,
                                                int is_row_major,
                                                int predict_type,
                                                int num_iteration,
924
                                                const char* parameter,
925
926
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
927

928
/*!
929
 * \brief Make prediction for a new dataset. This method re-uses the internal predictor structure
930
 *        from previous calls and is optimized for single row invocation.
931
932
933
934
935
 * \note
 * You 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``;
 *   - for feature contributions, its length is equal to ``num_class * num_data * (num_feature + 1)``.
936
937
 * \param handle Handle of booster
 * \param data Pointer to the data space
938
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
939
 * \param ncol Number columns
940
 * \param is_row_major 1 for row-major, 0 for column-major
941
 * \param predict_type What should be predicted
942
943
944
945
 *   - ``C_API_PREDICT_NORMAL``: normal prediction, with transform (if needed);
 *   - ``C_API_PREDICT_RAW_SCORE``: raw score;
 *   - ``C_API_PREDICT_LEAF_INDEX``: leaf index;
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
946
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
947
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
948
949
950
 * \param[out] out_len Length of output result
 * \param[out] out_result Pointer to array with predictions
 * \return 0 when succeed, -1 when failure happens
951
 */
952
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRow(BoosterHandle handle,
953
954
955
956
957
958
959
960
961
                                                         const void* data,
                                                         int data_type,
                                                         int ncol,
                                                         int is_row_major,
                                                         int predict_type,
                                                         int num_iteration,
                                                         const char* parameter,
                                                         int64_t* out_len,
                                                         double* out_result);
962
963
964

/*!
 * \brief Make prediction for a new dataset presented in a form of array of pointers to rows.
965
966
967
968
969
 * \note
 * You 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``;
 *   - for feature contributions, its length is equal to ``num_class * num_data * (num_feature + 1)``.
970
971
 * \param handle Handle of booster
 * \param data Pointer to the data space
972
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
973
974
975
 * \param nrow Number of rows
 * \param ncol Number columns
 * \param predict_type What should be predicted
976
977
978
979
 *   - ``C_API_PREDICT_NORMAL``: normal prediction, with transform (if needed);
 *   - ``C_API_PREDICT_RAW_SCORE``: raw score;
 *   - ``C_API_PREDICT_LEAF_INDEX``: leaf index;
 *   - ``C_API_PREDICT_CONTRIB``: feature contributions (SHAP values)
980
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
981
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
982
983
984
 * \param[out] out_len Length of output result
 * \param[out] out_result Pointer to array with predictions
 * \return 0 when succeed, -1 when failure happens
985
 */
986
987
988
989
990
991
992
993
994
995
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMats(BoosterHandle handle,
                                                 const void** data,
                                                 int data_type,
                                                 int32_t nrow,
                                                 int32_t ncol,
                                                 int predict_type,
                                                 int num_iteration,
                                                 const char* parameter,
                                                 int64_t* out_len,
                                                 double* out_result);
996

Guolin Ke's avatar
Guolin Ke committed
997
/*!
998
999
1000
1001
 * \brief Save model into file.
 * \param handle Handle of booster
 * \param start_iteration Start index of the iteration that should be saved
 * \param num_iteration Index of the iteration that should be saved, <= 0 means save all
1002
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1003
 * \param filename The name of the file
1004
 * \return 0 when succeed, -1 when failure happens
1005
 */
1006
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle,
1007
                                            int start_iteration,
1008
                                            int num_iteration,
1009
                                            int feature_importance_type,
1010
                                            const char* filename);
Guolin Ke's avatar
Guolin Ke committed
1011

1012
/*!
1013
1014
1015
1016
 * \brief Save model to string.
 * \param handle Handle of booster
 * \param start_iteration Start index of the iteration that should be saved
 * \param num_iteration Index of the iteration that should be saved, <= 0 means save all
1017
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1018
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
1019
1020
1021
 * \param[out] out_len Actual output length
 * \param[out] out_str String of model, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
1022
 */
1023
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle,
1024
                                                    int start_iteration,
1025
                                                    int num_iteration,
1026
                                                    int feature_importance_type,
1027
1028
                                                    int64_t buffer_len,
                                                    int64_t* out_len,
1029
                                                    char* out_str);
1030

wxchan's avatar
wxchan committed
1031
/*!
1032
1033
1034
 * \brief Dump model to JSON.
 * \param handle Handle of booster
 * \param start_iteration Start index of the iteration that should be dumped
1035
 * \param num_iteration Index of the iteration that should be dumped, <= 0 means dump all
1036
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1037
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
1038
1039
1040
 * \param[out] out_len Actual output length
 * \param[out] out_str JSON format string of model, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
1041
 */
1042
LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle,
1043
                                            int start_iteration,
1044
                                            int num_iteration,
1045
                                            int feature_importance_type,
1046
1047
                                            int64_t buffer_len,
                                            int64_t* out_len,
1048
                                            char* out_str);
1049

Guolin Ke's avatar
Guolin Ke committed
1050
/*!
1051
1052
1053
1054
1055
1056
 * \brief Get leaf value.
 * \param handle Handle of booster
 * \param tree_idx Index of tree
 * \param leaf_idx Index of leaf
 * \param[out] out_val Output result from the specified leaf
 * \return 0 when succeed, -1 when failure happens
1057
 */
1058
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle,
1059
1060
1061
                                               int tree_idx,
                                               int leaf_idx,
                                               double* out_val);
Guolin Ke's avatar
Guolin Ke committed
1062
1063

/*!
1064
1065
1066
1067
1068
1069
 * \brief Set leaf value.
 * \param handle Handle of booster
 * \param tree_idx Index of tree
 * \param leaf_idx Index of leaf
 * \param val Leaf value
 * \return 0 when succeed, -1 when failure happens
1070
 */
1071
LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle,
1072
1073
1074
                                               int tree_idx,
                                               int leaf_idx,
                                               double val);
1075

1076
/*!
1077
1078
1079
1080
 * \brief Get model feature importance.
 * \param handle Handle of booster
 * \param num_iteration Number of iterations for which feature importance is calculated, <= 0 means use all
 * \param importance_type Method of importance calculation:
1081
1082
 *   - ``C_API_FEATURE_IMPORTANCE_SPLIT``: result contains numbers of times the feature is used in a model;
 *   - ``C_API_FEATURE_IMPORTANCE_GAIN``: result contains total gains of splits which use the feature
1083
1084
 * \param[out] out_results Result array with feature importance
 * \return 0 when succeed, -1 when failure happens
1085
 */
1086
1087
1088
1089
1090
LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle,
                                                    int num_iteration,
                                                    int importance_type,
                                                    double* out_results);

1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
/*!
 * \brief Get model upper bound value.
 * \param handle Handle of booster
 * \param[out] out_results Result pointing to max value
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetUpperBoundValue(BoosterHandle handle,
                                                     double* out_results);

/*!
 * \brief Get model lower bound value.
 * \param handle Handle of booster
 * \param[out] out_results Result pointing to min value
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLowerBoundValue(BoosterHandle handle,
                                                     double* out_results);

1109
/*!
1110
1111
1112
1113
1114
1115
 * \brief Initialize the network.
 * \param machines List of machines in format 'ip1:port1,ip2:port2'
 * \param local_listen_port TCP listen port for local machines
 * \param listen_time_out Socket time-out in minutes
 * \param num_machines Total number of machines
 * \return 0 when succeed, -1 when failure happens
1116
 */
1117
1118
1119
1120
1121
1122
LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines,
                                       int local_listen_port,
                                       int listen_time_out,
                                       int num_machines);

/*!
1123
1124
 * \brief Finalize the network.
 * \return 0 when succeed, -1 when failure happens
1125
 */
1126
1127
LIGHTGBM_C_EXPORT int LGBM_NetworkFree();

1128
1129
1130
1131
1132
1133
1134
/*!
 * \brief Initialize the network with external collective functions.
 * \param num_machines Total number of machines
 * \param rank Rank of local machine
 * \param reduce_scatter_ext_fun The external reduce-scatter function
 * \param allgather_ext_fun The external allgather function
 * \return 0 when succeed, -1 when failure happens
1135
1136
1137
 */
LIGHTGBM_C_EXPORT int LGBM_NetworkInitWithFunctions(int num_machines,
                                                    int rank,
1138
                                                    void* reduce_scatter_ext_fun,
1139
                                                    void* allgather_ext_fun);
1140

Guolin Ke's avatar
Guolin Ke committed
1141
#if defined(_MSC_VER)
1142
#define THREAD_LOCAL __declspec(thread)  /*!< \brief Thread local specifier. */
Guolin Ke's avatar
Guolin Ke committed
1143
#else
1144
#define THREAD_LOCAL thread_local  /*!< \brief Thread local specifier. */
Guolin Ke's avatar
Guolin Ke committed
1145
#endif
1146
1147
1148
1149
1150

/*!
 * \brief Handle of error message.
 * \return Error message
 */
1151
static char* LastErrorMsg() { static THREAD_LOCAL char err_msg[512] = "Everything is fine"; return err_msg; }
1152

1153
1154
1155
#ifdef _MSC_VER
  #pragma warning(disable : 4996)
#endif
1156
1157
1158
1159
/*!
 * \brief Set string message of the last error.
 * \param msg Error message
 */
1160
inline void LGBM_SetLastError(const char* msg) {
1161
1162
  const int err_buf_len = 512;
  snprintf(LastErrorMsg(), err_buf_len, "%s", msg);
1163
1164
}

1165
#endif  // LIGHTGBM_C_API_H_