c_api.h 49.6 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>
wxchan's avatar
wxchan committed
19
20
#include <cstring>

21

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

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. */
#define C_API_DTYPE_INT8    (4)  /*!< \brief int8. */
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

Guolin Ke's avatar
Guolin Ke committed
36
/*!
37
 * \brief Get string message of the last error.
38
39
 * \return Error information
 */
40
LIGHTGBM_C_EXPORT const char* LGBM_GetLastError();
Guolin Ke's avatar
Guolin Ke committed
41

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

/*!
45
46
47
48
49
50
 * \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
51
 */
52
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename,
53
54
55
                                                 const char* parameters,
                                                 const DatasetHandle reference,
                                                 DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
56

57
/*!
58
59
 * \brief Allocate the space for dataset and bucket feature bins according to sampled data.
 * \param sample_data Sampled data, grouped by the column
60
61
62
63
64
65
66
67
 * \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
68
 */
69
70
71
72
73
74
75
76
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
77
78

/*!
79
 * \brief Allocate the space for dataset and bucket feature bins according to reference dataset.
80
81
82
83
 * \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
84
 */
Guolin Ke's avatar
Guolin Ke committed
85
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateByReference(const DatasetHandle reference,
86
87
                                                    int64_t num_total_row,
                                                    DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
88
89

/*!
90
 * \brief Push data to existing dataset, if ``nrow + start_row == num_total_row``, will call ``dataset->FinishLoad``.
91
92
 * \param dataset Handle of dataset
 * \param data Pointer to the data space
93
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
94
95
96
97
 * \param nrow Number of rows
 * \param ncol Number of columns
 * \param start_row Row start index
 * \return 0 when succeed, -1 when failure happens
98
 */
Guolin Ke's avatar
Guolin Ke committed
99
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset,
100
101
102
103
104
                                           const void* data,
                                           int data_type,
                                           int32_t nrow,
                                           int32_t ncol,
                                           int32_t start_row);
Guolin Ke's avatar
Guolin Ke committed
105
106

/*!
107
 * \brief Push data to existing dataset, if ``nrow + start_row == num_total_row``, will call ``dataset->FinishLoad``.
108
109
 * \param dataset Handle of dataset
 * \param indptr Pointer to row headers
110
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
111
112
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
113
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
114
115
116
117
118
 * \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
119
 */
Guolin Ke's avatar
Guolin Ke committed
120
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset,
121
122
123
124
125
126
127
128
129
                                                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
130

Guolin Ke's avatar
Guolin Ke committed
131
/*!
132
133
 * \brief Create a dataset from CSR format.
 * \param indptr Pointer to row headers
134
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
135
136
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
137
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
138
139
140
141
142
143
144
 * \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
145
 */
146
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr,
147
148
149
150
151
152
153
154
155
156
                                                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
157

158
/*!
159
 * \brief Create a dataset from CSR format through callbacks.
160
161
 * \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``)
162
163
164
165
166
167
 * \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
168
 */
169
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSRFunc(void* get_row_funptr,
170
171
172
173
174
                                                    int num_rows,
                                                    int64_t num_col,
                                                    const char* parameters,
                                                    const DatasetHandle reference,
                                                    DatasetHandle* out);
175

Guolin Ke's avatar
Guolin Ke committed
176
/*!
177
178
 * \brief Create a dataset from CSC format.
 * \param col_ptr Pointer to column headers
179
 * \param col_ptr_type Type of ``col_ptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
180
181
 * \param indices Pointer to row indices
 * \param data Pointer to the data space
182
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
183
184
185
186
187
188
189
 * \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
190
 */
191
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr,
192
193
194
195
196
197
198
199
200
201
                                                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
202
203

/*!
204
205
 * \brief Create dataset from dense matrix.
 * \param data Pointer to the data space
206
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
207
208
209
210
211
212
213
 * \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
214
 */
215
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data,
216
217
218
219
220
221
222
                                                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
223

224
/*!
225
226
227
 * \brief Create dataset from array of dense matrices.
 * \param nmat Number of dense matrices
 * \param data Pointer to the data space
228
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
229
230
231
232
233
234
235
 * \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
236
 */
237
238
239
240
241
242
243
244
245
246
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
247
/*!
248
249
250
 * \brief Create subset of a data.
 * \param handle Handle of full dataset
 * \param used_row_indices Indices used in subset
251
 * \param num_used_row_indices Length of ``used_row_indices``
252
253
254
 * \param parameters Additional parameters
 * \param[out] out Subset of data
 * \return 0 when succeed, -1 when failure happens
255
 */
256
257
258
259
260
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
261

Guolin Ke's avatar
Guolin Ke committed
262
/*!
263
264
265
266
267
 * \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
268
 */
269
270
271
LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(DatasetHandle handle,
                                                  const char** feature_names,
                                                  int num_feature_names);
Guolin Ke's avatar
Guolin Ke committed
272

273
/*!
274
275
276
277
278
 * \brief Get feature names of dataset.
 * \param handle Handle of dataset
 * \param[out] feature_names Feature names, should pre-allocate memory
 * \param[out] num_feature_names Number of feature names
 * \return 0 when succeed, -1 when failure happens
279
 */
280
281
282
LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(DatasetHandle handle,
                                                  char** feature_names,
                                                  int* num_feature_names);
283

Guolin Ke's avatar
Guolin Ke committed
284
/*!
285
286
287
 * \brief Free space for dataset.
 * \param handle Handle of dataset to be freed
 * \return 0 when succeed, -1 when failure happens
288
 */
289
LIGHTGBM_C_EXPORT int LGBM_DatasetFree(DatasetHandle handle);
Guolin Ke's avatar
Guolin Ke committed
290
291

/*!
292
293
 * \brief Save dataset to binary file.
 * \param handle Handle of dataset
294
 * \param filename The name of the file
295
 * \return 0 when succeed, -1 when failure happens
296
 */
297
LIGHTGBM_C_EXPORT int LGBM_DatasetSaveBinary(DatasetHandle handle,
298
                                             const char* filename);
Guolin Ke's avatar
Guolin Ke committed
299

300
/*!
301
302
 * \brief Save dataset to text file, intended for debugging use only.
 * \param handle Handle of dataset
303
 * \param filename The name of the file
304
 * \return 0 when succeed, -1 when failure happens
305
 */
306
307
308
LIGHTGBM_C_EXPORT int LGBM_DatasetDumpText(DatasetHandle handle,
                                           const char* filename);

Guolin Ke's avatar
Guolin Ke committed
309
/*!
310
 * \brief Set vector to a content in info.
311
312
313
314
315
 * \note
 * - \a monotone_constraints only works for ``C_API_DTYPE_INT8``;
 * - \a group only works for ``C_API_DTYPE_INT32``;
 * - \a label and \a weight only work for ``C_API_DTYPE_FLOAT32``;
 * - \a init_score and \a feature_penalty only work for ``C_API_DTYPE_FLOAT64``.
316
 * \param handle Handle of dataset
317
 * \param field_name Field name, can be \a label, \a weight, \a init_score, \a group, \a feature_penalty, \a monotone_constraints
318
 * \param field_data Pointer to data vector
319
320
 * \param num_element Number of elements in ``field_data``
 * \param type Type of ``field_data`` pointer, can be ``C_API_DTYPE_INT8``, ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
321
 * \return 0 when succeed, -1 when failure happens
322
 */
323
LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle,
324
325
326
327
                                           const char* field_name,
                                           const void* field_data,
                                           int num_element,
                                           int type);
Guolin Ke's avatar
Guolin Ke committed
328
329

/*!
330
331
332
333
334
 * \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
335
 * \param[out] out_type Type of result pointer, can be ``C_API_DTYPE_INT8``, ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
336
 * \return 0 when succeed, -1 when failure happens
337
 */
338
LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle,
339
340
341
342
                                           const char* field_name,
                                           int* out_len,
                                           const void** out_ptr,
                                           int* out_type);
Guolin Ke's avatar
Guolin Ke committed
343

344
/*!
345
346
347
 * \brief Update parameters for a dataset.
 * \param handle Handle of dataset
 * \param parameters Parameters
348
 */
349
350
LIGHTGBM_C_EXPORT int LGBM_DatasetUpdateParam(DatasetHandle handle,
                                              const char* parameters);
351

Guolin Ke's avatar
Guolin Ke committed
352
/*!
353
354
355
356
 * \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
357
 */
358
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle,
359
                                             int* out);
Guolin Ke's avatar
Guolin Ke committed
360
361

/*!
362
363
364
365
 * \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
366
 */
367
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle,
368
                                                int* out);
Guolin Ke's avatar
Guolin Ke committed
369

370
/*!
371
 * \brief Add features from ``source`` to ``target``.
372
373
374
 * \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
375
 */
376
377
378
LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target,
                                                  DatasetHandle source);

Guolin Ke's avatar
Guolin Ke committed
379
380
381
// --- start Booster interfaces

/*!
382
383
 * \brief Create a new boosting learner.
 * \param train_data Training dataset
384
 * \param parameters Parameters in format 'key1=value1 key2=value2'
385
 * \param[out] out Handle of created booster
386
387
 * \return 0 when succeed, -1 when failure happens
 */
388
LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data,
389
390
                                         const char* parameters,
                                         BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
391
392

/*!
393
394
395
396
397
 * \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
398
 */
399
400
401
LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(const char* filename,
                                                      int* out_num_iterations,
                                                      BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
402

403
/*!
404
405
406
407
408
 * \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
409
 */
410
411
412
LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(const char* model_str,
                                                      int* out_num_iterations,
                                                      BoosterHandle* out);
wxchan's avatar
wxchan committed
413

Guolin Ke's avatar
Guolin Ke committed
414
/*!
415
416
417
 * \brief Free space for booster.
 * \param handle Handle of booster to be freed
 * \return 0 when succeed, -1 when failure happens
418
 */
419
LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle);
Guolin Ke's avatar
Guolin Ke committed
420

421
/*!
422
423
424
425
426
 * \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
427
 */
428
429
430
LIGHTGBM_C_EXPORT int LGBM_BoosterShuffleModels(BoosterHandle handle,
                                                int start_iter,
                                                int end_iter);
431

wxchan's avatar
wxchan committed
432
/*!
433
 * \brief Merge model from ``other_handle`` into ``handle``.
434
435
436
 * \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
437
 */
438
LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle,
439
                                        BoosterHandle other_handle);
wxchan's avatar
wxchan committed
440
441

/*!
442
443
444
445
 * \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
446
 */
447
LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle,
448
                                               const DatasetHandle valid_data);
wxchan's avatar
wxchan committed
449
450

/*!
451
452
453
454
 * \brief Reset training data for booster.
 * \param handle Handle of booster
 * \param train_data Training dataset
 * \return 0 when succeed, -1 when failure happens
455
 */
456
LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle,
457
                                                    const DatasetHandle train_data);
wxchan's avatar
wxchan committed
458
459

/*!
460
461
 * \brief Reset config for booster.
 * \param handle Handle of booster
462
 * \param parameters Parameters in format 'key1=value1 key2=value2'
463
 * \return 0 when succeed, -1 when failure happens
464
 */
465
466
LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle,
                                                 const char* parameters);
wxchan's avatar
wxchan committed
467
468

/*!
469
470
471
472
 * \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
473
 */
474
475
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
476

Guolin Ke's avatar
Guolin Ke committed
477
/*!
478
479
 * \brief Update the model for one iteration.
 * \param handle Handle of booster
480
 * \param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure
481
 * \return 0 when succeed, -1 when failure happens
482
 */
483
484
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle,
                                                int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
485

Guolin Ke's avatar
Guolin Ke committed
486
/*!
487
488
489
 * \brief Refit the tree model using the new data (online learning).
 * \param handle Handle of booster
 * \param leaf_preds Pointer to predicted leaf indices
490
491
 * \param nrow Number of rows of ``leaf_preds``
 * \param ncol Number of columns of ``leaf_preds``
492
 * \return 0 when succeed, -1 when failure happens
493
 */
494
495
496
497
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
498

Guolin Ke's avatar
Guolin Ke committed
499
/*!
500
501
502
503
504
 * \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
505
 * \param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure
506
 * \return 0 when succeed, -1 when failure happens
507
 */
508
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
509
510
511
                                                      const float* grad,
                                                      const float* hess,
                                                      int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
512
513

/*!
514
515
516
 * \brief Rollback one iteration.
 * \param handle Handle of booster
 * \return 0 when succeed, -1 when failure happens
517
 */
518
LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle);
wxchan's avatar
wxchan committed
519
520

/*!
521
522
523
524
 * \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
525
 */
526
527
LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle,
                                                      int* out_iteration);
Guolin Ke's avatar
Guolin Ke committed
528

529
/*!
530
531
532
533
 * \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
534
 */
535
536
LIGHTGBM_C_EXPORT int LGBM_BoosterNumModelPerIteration(BoosterHandle handle,
                                                       int* out_tree_per_iteration);
537
538

/*!
539
540
541
542
 * \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
543
 */
544
545
LIGHTGBM_C_EXPORT int LGBM_BoosterNumberOfTotalModel(BoosterHandle handle,
                                                     int* out_models);
546

Guolin Ke's avatar
Guolin Ke committed
547
/*!
548
549
550
551
 * \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
552
 */
553
554
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
555
556

/*!
557
558
559
560
561
 * \brief Get names of evaluation datasets.
 * \param handle Handle of booster
 * \param[out] out_len Total number of evaluation datasets
 * \param[out] out_strs Names of evaluation datasets, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
562
 */
563
564
565
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle,
                                               int* out_len,
                                               char** out_strs);
wxchan's avatar
wxchan committed
566

wxchan's avatar
wxchan committed
567
/*!
568
569
570
571
572
 * \brief Get names of features.
 * \param handle Handle of booster
 * \param[out] out_len Total number of features
 * \param[out] out_strs Names of features, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
573
 */
574
575
576
LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle,
                                                  int* out_len,
                                                  char** out_strs);
wxchan's avatar
wxchan committed
577
578

/*!
579
580
581
582
 * \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
583
 */
584
585
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
586

wxchan's avatar
wxchan committed
587
/*!
588
 * \brief Get evaluation for training data and validation data.
589
590
591
 * \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``.
592
593
594
 * \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
595
 * \param[out] out_results Array with evaluation results
596
 * \return 0 when succeed, -1 when failure happens
597
 */
598
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle,
599
600
601
                                          int data_idx,
                                          int* out_len,
                                          double* out_results);
Guolin Ke's avatar
Guolin Ke committed
602
603

/*!
604
605
 * \brief Get number of predictions for training data and validation data
 *        (this can be used to support customized evaluation functions).
606
607
608
609
 * \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
610
 */
611
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle,
612
613
                                                int data_idx,
                                                int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
614

Guolin Ke's avatar
Guolin Ke committed
615
/*!
616
 * \brief Get prediction for training data and validation data.
617
618
 * \note
 * You should pre-allocate memory for ``out_result``, its length is equal to ``num_class * num_data``.
619
620
621
622
623
 * \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
624
 */
625
LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle,
626
627
628
                                             int data_idx,
                                             int64_t* out_len,
                                             double* out_result);
Guolin Ke's avatar
Guolin Ke committed
629

630
/*!
631
632
633
634
635
 * \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
636
637
638
639
 *   - ``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)
640
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
641
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
642
643
 * \param result_filename Filename of result file in which predictions will be written
 * \return 0 when succeed, -1 when failure happens
644
 */
645
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle,
646
647
648
649
                                                 const char* data_filename,
                                                 int data_has_header,
                                                 int predict_type,
                                                 int num_iteration,
650
                                                 const char* parameter,
651
                                                 const char* result_filename);
652

Guolin Ke's avatar
Guolin Ke committed
653
/*!
654
655
656
657
 * \brief Get number of predictions.
 * \param handle Handle of booster
 * \param num_row Number of rows
 * \param predict_type What should be predicted
658
659
660
661
 *   - ``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)
662
663
664
 * \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
665
 */
666
LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle,
667
668
669
670
                                                 int num_row,
                                                 int predict_type,
                                                 int num_iteration,
                                                 int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
671

Guolin Ke's avatar
Guolin Ke committed
672
/*!
673
 * \brief Make prediction for a new dataset in CSR format.
674
675
676
677
678
 * \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)``.
679
680
 * \param handle Handle of booster
 * \param indptr Pointer to row headers
681
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
682
683
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
684
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
685
686
687
688
 * \param nindptr Number of rows in the matrix + 1
 * \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 What should be predicted
689
690
691
692
 *   - ``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)
693
694
695
696
697
 * \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
698
 */
699
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle,
700
701
702
703
704
705
706
707
708
709
                                                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,
710
                                                const char* parameter,
711
712
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
713

714
/*!
715
 * \brief Make prediction for a new dataset in CSR format. This method re-uses the internal predictor structure
716
 *        from previous calls and is optimized for single row invocation.
717
718
719
720
721
 * \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)``.
722
723
 * \param handle Handle of booster
 * \param indptr Pointer to row headers
724
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
725
726
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
727
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
728
729
730
731
 * \param nindptr Number of rows in the matrix + 1
 * \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 What should be predicted
732
733
734
735
 *   - ``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)
736
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
737
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
738
739
740
 * \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
741
 */
742
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRow(BoosterHandle handle,
743
744
745
746
747
748
749
750
751
752
753
754
755
                                                         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);
756

Guolin Ke's avatar
Guolin Ke committed
757
/*!
758
 * \brief Make prediction for a new dataset in CSC format.
759
760
761
762
763
 * \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)``.
764
765
 * \param handle Handle of booster
 * \param col_ptr Pointer to column headers
766
 * \param col_ptr_type Type of ``col_ptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
767
768
 * \param indices Pointer to row indices
 * \param data Pointer to the data space
769
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
770
771
772
773
 * \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
774
775
776
777
 *   - ``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)
778
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
779
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
780
781
782
 * \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
783
 */
784
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle,
785
786
787
788
789
790
791
792
793
794
                                                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,
795
                                                const char* parameter,
796
797
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
798
799

/*!
800
 * \brief Make prediction for a new dataset.
801
802
803
804
805
 * \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)``.
806
807
 * \param handle Handle of booster
 * \param data Pointer to the data space
808
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
809
810
811
812
 * \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
813
814
815
816
 *   - ``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)
817
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
818
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
819
820
821
 * \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
822
 */
823
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle,
824
825
826
827
828
829
830
                                                const void* data,
                                                int data_type,
                                                int32_t nrow,
                                                int32_t ncol,
                                                int is_row_major,
                                                int predict_type,
                                                int num_iteration,
831
                                                const char* parameter,
832
833
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
834

835
/*!
836
 * \brief Make prediction for an new dataset. This method re-uses the internal predictor structure
837
 *        from previous calls and is optimized for single row invocation.
838
839
840
841
842
 * \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)``.
843
844
 * \param handle Handle of booster
 * \param data Pointer to the data space
845
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
846
 * \param ncol Number columns
847
 * \param is_row_major 1 for row-major, 0 for column-major
848
 * \param predict_type What should be predicted
849
850
851
852
 *   - ``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)
853
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
854
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
855
856
857
 * \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
858
 */
859
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRow(BoosterHandle handle,
860
861
862
863
864
865
866
867
868
                                                         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);
869
870
871

/*!
 * \brief Make prediction for a new dataset presented in a form of array of pointers to rows.
872
873
874
875
876
 * \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)``.
877
878
 * \param handle Handle of booster
 * \param data Pointer to the data space
879
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
880
881
882
 * \param nrow Number of rows
 * \param ncol Number columns
 * \param predict_type What should be predicted
883
884
885
886
 *   - ``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)
887
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
888
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
889
890
891
 * \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
892
 */
893
894
895
896
897
898
899
900
901
902
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);
903

Guolin Ke's avatar
Guolin Ke committed
904
/*!
905
906
907
908
 * \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
909
 * \param filename The name of the file
910
 * \return 0 when succeed, -1 when failure happens
911
 */
912
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle,
913
                                            int start_iteration,
914
915
                                            int num_iteration,
                                            const char* filename);
Guolin Ke's avatar
Guolin Ke committed
916

917
/*!
918
919
920
921
 * \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
922
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
923
924
925
 * \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
926
 */
927
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle,
928
                                                    int start_iteration,
929
                                                    int num_iteration,
930
931
                                                    int64_t buffer_len,
                                                    int64_t* out_len,
932
                                                    char* out_str);
933

wxchan's avatar
wxchan committed
934
/*!
935
936
937
 * \brief Dump model to JSON.
 * \param handle Handle of booster
 * \param start_iteration Start index of the iteration that should be dumped
938
939
 * \param num_iteration Index of the iteration that should be dumped, <= 0 means dump all
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
940
941
942
 * \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
943
 */
944
LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle,
945
                                            int start_iteration,
946
                                            int num_iteration,
947
948
                                            int64_t buffer_len,
                                            int64_t* out_len,
949
                                            char* out_str);
950

Guolin Ke's avatar
Guolin Ke committed
951
/*!
952
953
954
955
956
957
 * \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
958
 */
959
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle,
960
961
962
                                               int tree_idx,
                                               int leaf_idx,
                                               double* out_val);
Guolin Ke's avatar
Guolin Ke committed
963
964

/*!
965
966
967
968
969
970
 * \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
971
 */
972
LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle,
973
974
975
                                               int tree_idx,
                                               int leaf_idx,
                                               double val);
976

977
/*!
978
979
980
981
 * \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:
982
983
 *   - 0 for split, result contains numbers of times the feature is used in a model;
 *   - 1 for gain, result contains total gains of splits which use the feature
984
985
 * \param[out] out_results Result array with feature importance
 * \return 0 when succeed, -1 when failure happens
986
 */
987
988
989
990
991
LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle,
                                                    int num_iteration,
                                                    int importance_type,
                                                    double* out_results);

992
/*!
993
994
995
996
997
998
 * \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
999
 */
1000
1001
1002
1003
1004
1005
LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines,
                                       int local_listen_port,
                                       int listen_time_out,
                                       int num_machines);

/*!
1006
1007
 * \brief Finalize the network.
 * \return 0 when succeed, -1 when failure happens
1008
 */
1009
1010
LIGHTGBM_C_EXPORT int LGBM_NetworkFree();

1011
1012
1013
1014
1015
1016
1017
/*!
 * \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
1018
1019
1020
 */
LIGHTGBM_C_EXPORT int LGBM_NetworkInitWithFunctions(int num_machines,
                                                    int rank,
1021
                                                    void* reduce_scatter_ext_fun,
1022
                                                    void* allgather_ext_fun);
1023

Guolin Ke's avatar
Guolin Ke committed
1024
#if defined(_MSC_VER)
1025
#define THREAD_LOCAL __declspec(thread)  /*!< \brief Thread local specifier. */
Guolin Ke's avatar
Guolin Ke committed
1026
#else
1027
#define THREAD_LOCAL thread_local  /*!< \brief Thread local specifier. */
Guolin Ke's avatar
Guolin Ke committed
1028
#endif
1029
1030
1031
1032
1033

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

1036
#pragma warning(disable : 4996)
1037
1038
1039
1040
/*!
 * \brief Set string message of the last error.
 * \param msg Error message
 */
1041
inline void LGBM_SetLastError(const char* msg) {
wxchan's avatar
wxchan committed
1042
  std::strcpy(LastErrorMsg(), msg);
1043
1044
}

1045
#endif  // LIGHTGBM_C_API_H_