c_api.h 79.4 KB
Newer Older
1
/*!
2
3
4
5
6
7
 * \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:
8
9
10
 * 1. gradient and Hessian;
 * 2. current score for training and validation data.
 * .
11
 * 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
#include <LightGBM/arrow.h>
17
18
#include <LightGBM/export.h>

19
#ifdef __cplusplus
20
#include <cstdint>
21
#include <cstdio>
wxchan's avatar
wxchan committed
22
#include <cstring>
23
24
25
26
27
#else
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#endif
wxchan's avatar
wxchan committed
28

29

30
31
typedef void* DatasetHandle;  /*!< \brief Handle of dataset. */
typedef void* BoosterHandle;  /*!< \brief Handle of booster. */
32
typedef void* FastConfigHandle; /*!< \brief Handle of FastConfig. */
33
typedef void* ByteBufferHandle; /*!< \brief Handle of ByteBuffer. */
Guolin Ke's avatar
Guolin Ke committed
34

35
36
37
38
#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
39

40
41
42
43
#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). */
44

45
46
47
#define C_API_MATRIX_TYPE_CSR (0)  /*!< \brief CSR sparse matrix type. */
#define C_API_MATRIX_TYPE_CSC (1)  /*!< \brief CSC sparse matrix type. */

48
49
50
#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
51
/*!
52
 * \brief Get string message of the last error.
53
54
 * \return Error information
 */
55
LIGHTGBM_C_EXPORT const char* LGBM_GetLastError();
Guolin Ke's avatar
Guolin Ke committed
56

57
58
59
60
61
62
63
64
65
66
67
/*!
 * \brief Dump all parameter names with their aliases to JSON.
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
 * \param[out] out_len Actual output length
 * \param[out] out_str JSON format string of parameters, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DumpParamAliases(int64_t buffer_len,
                                            int64_t* out_len,
                                            char* out_str);

68
/*!
69
 * \brief Register a callback function for log redirecting.
70
71
72
73
74
 * \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*));

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
/*!
 * \brief Get number of samples based on parameters and total number of rows of data.
 * \param num_total_row Number of total rows
 * \param parameters Additional parameters, namely, ``bin_construct_sample_cnt`` is used to calculate returned value
 * \param[out] out Number of samples. This value is used to pre-allocate memory to hold sample indices when calling ``LGBM_SampleIndices``
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_GetSampleCount(int32_t num_total_row,
                                          const char* parameters,
                                          int* out);

/*!
 * \brief Create sample indices for total number of rows.
 * \note
 * You should pre-allocate memory for ``out``, you can get its length by ``LGBM_GetSampleCount``.
 * \param num_total_row Number of total rows
 * \param parameters Additional parameters, namely, ``bin_construct_sample_cnt`` and ``data_random_seed`` are used to produce the output
 * \param[out] out Created indices, type is int32_t
93
 * \param[out] out_len Number of indices
94
95
96
97
98
99
100
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_SampleIndices(int32_t num_total_row,
                                         const char* parameters,
                                         void* out,
                                         int32_t* out_len);

101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
/*!
 * \brief Get a ByteBuffer value at an index.
 * \param handle Handle of byte buffer to be read
 * \param index Index of value to return
 * \param[out] out_val Byte value at index to return
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_ByteBufferGetAt(ByteBufferHandle handle, int32_t index, uint8_t* out_val);

/*!
 * \brief Free space for byte buffer.
 * \param handle Handle of byte buffer to be freed
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_ByteBufferFree(ByteBufferHandle handle);

117
/* --- start Dataset interface */
Guolin Ke's avatar
Guolin Ke committed
118
119

/*!
120
121
122
123
124
125
 * \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
126
 */
127
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename,
128
129
130
                                                 const char* parameters,
                                                 const DatasetHandle reference,
                                                 DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
131

132
/*!
133
134
 * \brief Allocate the space for dataset and bucket feature bins according to sampled data.
 * \param sample_data Sampled data, grouped by the column
135
136
137
138
 * \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
139
140
 * \param num_local_row Total number of rows local to machine
 * \param num_dist_row Number of total distributed rows
141
142
143
 * \param parameters Additional parameters
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
144
 */
145
146
147
148
149
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,
150
151
                                                          int32_t num_local_row,
                                                          int64_t num_dist_row,
152
153
                                                          const char* parameters,
                                                          DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
154
155

/*!
156
 * \brief Allocate the space for dataset and bucket feature bins according to reference dataset.
157
158
159
160
 * \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
161
 */
Guolin Ke's avatar
Guolin Ke committed
162
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateByReference(const DatasetHandle reference,
163
164
                                                    int64_t num_total_row,
                                                    DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
165

166
167
168
169
170
171
172
173
/*!
 * \brief Initialize the Dataset for streaming.
 * \param dataset Handle of dataset
 * \param has_weights Whether the dataset has Metadata weights
 * \param has_init_scores Whether the dataset has Metadata initial scores
 * \param has_queries Whether the dataset has Metadata queries/groups
 * \param nclasses Number of initial score classes
 * \param nthreads Number of external threads that will use the PushRows APIs
174
 * \param omp_max_threads Maximum number of OpenMP threads (-1 for default)
175
176
177
178
179
180
181
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetInitStreaming(DatasetHandle dataset,
                                                int32_t has_weights,
                                                int32_t has_init_scores,
                                                int32_t has_queries,
                                                int32_t nclasses,
182
183
                                                int32_t nthreads,
                                                int32_t omp_max_threads);
184

185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
/*!
 * \brief Allocate the space for dataset and bucket feature bins according to serialized reference dataset.
 * \param ref_buffer A binary representation of the dataset schema (feature groups, bins, etc.)
 * \param ref_buffer_size The size of the reference array in bytes
 * \param num_row Number of total rows the dataset will contain
 * \param num_classes Number of classes (will be used only in case of multiclass and specifying initial scores)
 * \param parameters Additional parameters
 * \param[out] out Created dataset
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSerializedReference(const void* ref_buffer,
                                                                int32_t ref_buffer_size,
                                                                int64_t num_row,
                                                                int32_t num_classes,
                                                                const char* parameters,
                                                                DatasetHandle* out);

Guolin Ke's avatar
Guolin Ke committed
202
/*!
203
 * \brief Push data to existing dataset, if ``nrow + start_row == num_total_row``, will call ``dataset->FinishLoad``.
204
205
 * \param dataset Handle of dataset
 * \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
 * \param nrow Number of rows
 * \param ncol Number of columns
 * \param start_row Row start index
 * \return 0 when succeed, -1 when failure happens
211
 */
Guolin Ke's avatar
Guolin Ke committed
212
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset,
213
214
215
216
217
                                           const void* data,
                                           int data_type,
                                           int32_t nrow,
                                           int32_t ncol,
                                           int32_t start_row);
Guolin Ke's avatar
Guolin Ke committed
218

219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
/*!
 * \brief Push data to existing dataset.
 *        The general flow for a streaming scenario is:
 *        1. create Dataset "schema" (e.g. ``LGBM_DatasetCreateFromSampledColumn``)
 *        2. init them for thread-safe streaming (``LGBM_DatasetInitStreaming``)
 *        3. push data (``LGBM_DatasetPushRowsWithMetadata`` or ``LGBM_DatasetPushRowsByCSRWithMetadata``)
 *        4. call ``LGBM_DatasetMarkFinished``
 * \param dataset Handle of dataset
 * \param data Pointer to the data space
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
 * \param nrow Number of rows
 * \param ncol Number of feature columns
 * \param start_row Row start index, i.e., the index at which to start inserting data
 * \param label Pointer to array with nrow labels
 * \param weight Optional pointer to array with nrow weights
 * \param init_score Optional pointer to array with nrow*nclasses initial scores, in column format
 * \param query Optional pointer to array with nrow query values
 * \param tid The id of the calling thread, from 0...N-1 threads
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsWithMetadata(DatasetHandle dataset,
                                                       const void* data,
                                                       int data_type,
                                                       int32_t nrow,
                                                       int32_t ncol,
                                                       int32_t start_row,
                                                       const float* label,
                                                       const float* weight,
                                                       const double* init_score,
                                                       const int32_t* query,
                                                       int32_t tid);

Guolin Ke's avatar
Guolin Ke committed
251
/*!
252
 * \brief Push data to existing dataset, if ``nrow + start_row == num_total_row``, will call ``dataset->FinishLoad``.
253
254
 * \param dataset Handle of dataset
 * \param indptr Pointer to row headers
255
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
256
257
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
258
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
259
260
261
262
263
 * \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
264
 */
Guolin Ke's avatar
Guolin Ke committed
265
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset,
266
267
268
269
270
271
272
273
274
                                                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
275

276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
/*!
 * \brief Push CSR data to existing dataset. (See ``LGBM_DatasetPushRowsWithMetadata`` for more details.)
 * \param dataset Handle of dataset
 * \param indptr Pointer to row headers
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
 * \param indices Pointer to column indices
 * \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 start_row Row start index
 * \param label Pointer to array with nindptr-1 labels
 * \param weight Optional pointer to array with nindptr-1 weights
 * \param init_score Optional pointer to array with (nindptr-1)*nclasses initial scores, in column format
 * \param query Optional pointer to array with nindptr-1 query values
 * \param tid The id of the calling thread, from 0...N-1 threads
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSRWithMetadata(DatasetHandle dataset,
                                                            const void* indptr,
                                                            int indptr_type,
                                                            const int32_t* indices,
                                                            const void* data,
                                                            int data_type,
                                                            int64_t nindptr,
                                                            int64_t nelem,
                                                            int64_t start_row,
                                                            const float* label,
                                                            const float* weight,
                                                            const double* init_score,
                                                            const int32_t* query,
                                                            int32_t tid);

/*!
 * \brief Set whether or not the Dataset waits for a manual MarkFinished call or calls FinishLoad on itself automatically.
 *        Set to 1 for streaming scenario, and use ``LGBM_DatasetMarkFinished`` to manually finish the Dataset.
 * \param dataset Handle of dataset
 * \param wait Whether to wait or not (1 or 0)
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetSetWaitForManualFinish(DatasetHandle dataset, int wait);

/*!
 * \brief Mark the Dataset as complete by calling ``dataset->FinishLoad``.
 * \param dataset Handle of dataset
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetMarkFinished(DatasetHandle dataset);

Guolin Ke's avatar
Guolin Ke committed
325
/*!
326
327
 * \brief Create a dataset from CSR format.
 * \param indptr Pointer to row headers
328
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
329
330
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
331
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
332
333
334
335
336
337
338
 * \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
339
 */
340
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr,
341
342
343
344
345
346
347
348
349
350
                                                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
351

352
/*!
353
 * \brief Create a dataset from CSR format through callbacks.
354
355
 * \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``)
356
357
358
359
360
361
 * \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
362
 */
363
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSRFunc(void* get_row_funptr,
364
365
366
367
368
                                                    int num_rows,
                                                    int64_t num_col,
                                                    const char* parameters,
                                                    const DatasetHandle reference,
                                                    DatasetHandle* out);
369

Guolin Ke's avatar
Guolin Ke committed
370
/*!
371
372
 * \brief Create a dataset from CSC format.
 * \param col_ptr Pointer to column headers
373
 * \param col_ptr_type Type of ``col_ptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
374
375
 * \param indices Pointer to row indices
 * \param data Pointer to the data space
376
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
377
378
379
380
381
382
383
 * \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
384
 */
385
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr,
386
387
388
389
390
391
392
393
394
395
                                                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
396
397

/*!
398
399
 * \brief Create dataset from dense matrix.
 * \param data Pointer to the data space
400
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
401
402
403
404
405
406
407
 * \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
408
 */
409
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data,
410
411
412
413
414
415
416
                                                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
417

418
/*!
419
420
421
 * \brief Create dataset from array of dense matrices.
 * \param nmat Number of dense matrices
 * \param data Pointer to the data space
422
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
423
424
425
426
427
428
429
 * \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
430
 */
431
432
433
434
435
436
437
438
439
440
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);

441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
/*!
 * \brief Create dataset from Arrow.
 * \param n_chunks The number of Arrow arrays passed to this function
 * \param chunks Pointer to the list of Arrow arrays
 * \param schema Pointer to the schema of all Arrow arrays
 * \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
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromArrow(int64_t n_chunks,
                                                  const ArrowArray* chunks,
                                                  const ArrowSchema* schema,
                                                  const char* parameters,
                                                  const DatasetHandle reference,
                                                  DatasetHandle *out);

wxchan's avatar
wxchan committed
458
/*!
459
460
461
 * \brief Create subset of a data.
 * \param handle Handle of full dataset
 * \param used_row_indices Indices used in subset
462
 * \param num_used_row_indices Length of ``used_row_indices``
463
464
465
 * \param parameters Additional parameters
 * \param[out] out Subset of data
 * \return 0 when succeed, -1 when failure happens
466
 */
467
468
469
470
471
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
472

Guolin Ke's avatar
Guolin Ke committed
473
/*!
474
475
476
477
478
 * \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
479
 */
480
481
482
LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(DatasetHandle handle,
                                                  const char** feature_names,
                                                  int num_feature_names);
Guolin Ke's avatar
Guolin Ke committed
483

484
/*!
485
486
 * \brief Get feature names of dataset.
 * \param handle Handle of dataset
487
488
 * \param len Number of ``char*`` pointers stored at ``out_strs``.
 *            If smaller than the max size, only this many strings are copied
489
 * \param[out] num_feature_names Number of feature names
490
491
492
493
 * \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
494
 * \return 0 when succeed, -1 when failure happens
495
 */
496
LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(DatasetHandle handle,
497
498
499
500
501
                                                  const int len,
                                                  int* num_feature_names,
                                                  const size_t buffer_len,
                                                  size_t* out_buffer_len,
                                                  char** feature_names);
502

Guolin Ke's avatar
Guolin Ke committed
503
/*!
504
505
506
 * \brief Free space for dataset.
 * \param handle Handle of dataset to be freed
 * \return 0 when succeed, -1 when failure happens
507
 */
508
LIGHTGBM_C_EXPORT int LGBM_DatasetFree(DatasetHandle handle);
Guolin Ke's avatar
Guolin Ke committed
509
510

/*!
511
512
 * \brief Save dataset to binary file.
 * \param handle Handle of dataset
513
 * \param filename The name of the file
514
 * \return 0 when succeed, -1 when failure happens
515
 */
516
LIGHTGBM_C_EXPORT int LGBM_DatasetSaveBinary(DatasetHandle handle,
517
                                             const char* filename);
Guolin Ke's avatar
Guolin Ke committed
518

519
520
521
522
523
524
525
526
527
528
529
/*!
 * \brief Create a dataset schema representation as a binary byte array (excluding data).
 * \param handle Handle of dataset
 * \param[out] out The output byte array
 * \param[out] out_len The length of the output byte array (returned for convenience)
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetSerializeReferenceToBinary(DatasetHandle handle,
                                                             ByteBufferHandle* out,
                                                             int32_t* out_len);

530
/*!
531
532
 * \brief Save dataset to text file, intended for debugging use only.
 * \param handle Handle of dataset
533
 * \param filename The name of the file
534
 * \return 0 when succeed, -1 when failure happens
535
 */
536
537
538
LIGHTGBM_C_EXPORT int LGBM_DatasetDumpText(DatasetHandle handle,
                                           const char* filename);

Guolin Ke's avatar
Guolin Ke committed
539
/*!
540
 * \brief Set vector to a content in info.
541
542
543
 * \note
 * - \a group only works for ``C_API_DTYPE_INT32``;
 * - \a label and \a weight only work for ``C_API_DTYPE_FLOAT32``;
544
 * - \a init_score only works for ``C_API_DTYPE_FLOAT64``.
545
 * \param handle Handle of dataset
546
 * \param field_name Field name, can be \a label, \a weight, \a init_score, \a group
547
 * \param field_data Pointer to data vector
548
 * \param num_element Number of elements in ``field_data``
549
 * \param type Type of ``field_data`` pointer, can be ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
550
 * \return 0 when succeed, -1 when failure happens
551
 */
552
LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle,
553
554
555
556
                                           const char* field_name,
                                           const void* field_data,
                                           int num_element,
                                           int type);
Guolin Ke's avatar
Guolin Ke committed
557
558

/*!
559
560
561
562
563
 * \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
564
 * \param[out] out_type Type of result pointer, can be ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
565
 * \return 0 when succeed, -1 when failure happens
566
 */
567
LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle,
568
569
570
571
                                           const char* field_name,
                                           int* out_len,
                                           const void** out_ptr,
                                           int* out_type);
Guolin Ke's avatar
Guolin Ke committed
572

573
/*!
574
575
576
577
 * \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
578
 */
579
580
LIGHTGBM_C_EXPORT int LGBM_DatasetUpdateParamChecking(const char* old_parameters,
                                                      const char* new_parameters);
581

Guolin Ke's avatar
Guolin Ke committed
582
/*!
583
584
585
586
 * \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
587
 */
588
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle,
589
                                             int* out);
Guolin Ke's avatar
Guolin Ke committed
590
591

/*!
592
593
594
595
 * \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
596
 */
597
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle,
598
                                                int* out);
Guolin Ke's avatar
Guolin Ke committed
599

600
601
602
603
604
605
606
607
608
609
610
/*!
 * \brief Get number of bins for feature.
 * \param handle Handle of dataset
 * \param feature Index of the feature
 * \param[out] out The address to hold number of bins
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNumBin(DatasetHandle handle,
                                                   int feature,
                                                   int* out);

611
/*!
612
 * \brief Add features from ``source`` to ``target``.
613
614
615
 * \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
616
 */
617
618
619
LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target,
                                                  DatasetHandle source);

620
/* --- start Booster interfaces */
Guolin Ke's avatar
Guolin Ke committed
621

622
/*!
623
* \brief Get int representing whether booster is fitting linear trees.
624
625
626
627
* \param handle Handle of booster
* \param[out] out The address to hold linear trees indicator
* \return 0 when succeed, -1 when failure happens
*/
628
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLinear(BoosterHandle handle, int* out);
629

Guolin Ke's avatar
Guolin Ke committed
630
/*!
631
632
 * \brief Create a new boosting learner.
 * \param train_data Training dataset
633
 * \param parameters Parameters in format 'key1=value1 key2=value2'
634
 * \param[out] out Handle of created booster
635
636
 * \return 0 when succeed, -1 when failure happens
 */
637
LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data,
638
639
                                         const char* parameters,
                                         BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
640
641

/*!
642
643
644
645
646
 * \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
647
 */
648
649
650
LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(const char* filename,
                                                      int* out_num_iterations,
                                                      BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
651

652
/*!
653
654
655
656
657
 * \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
658
 */
659
660
661
LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(const char* model_str,
                                                      int* out_num_iterations,
                                                      BoosterHandle* out);
wxchan's avatar
wxchan committed
662

663
664
/*!
 * \brief Get parameters as JSON string.
665
666
667
668
 * \param handle Handle of booster
 * \param buffer_len Allocated space for string
 * \param[out] out_len Actual size of string
 * \param[out] out_str JSON string containing parameters
669
670
671
672
673
674
675
676
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLoadedParam(BoosterHandle handle,
                                                 int64_t buffer_len,
                                                 int64_t* out_len,
                                                 char* out_str);


Guolin Ke's avatar
Guolin Ke committed
677
/*!
678
679
680
 * \brief Free space for booster.
 * \param handle Handle of booster to be freed
 * \return 0 when succeed, -1 when failure happens
681
 */
682
LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle);
Guolin Ke's avatar
Guolin Ke committed
683

684
/*!
685
686
687
688
689
 * \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
690
 */
691
692
693
LIGHTGBM_C_EXPORT int LGBM_BoosterShuffleModels(BoosterHandle handle,
                                                int start_iter,
                                                int end_iter);
694

wxchan's avatar
wxchan committed
695
/*!
696
 * \brief Merge model from ``other_handle`` into ``handle``.
697
698
699
 * \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
700
 */
701
LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle,
702
                                        BoosterHandle other_handle);
wxchan's avatar
wxchan committed
703
704

/*!
705
706
707
708
 * \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
709
 */
710
LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle,
711
                                               const DatasetHandle valid_data);
wxchan's avatar
wxchan committed
712
713

/*!
714
715
716
717
 * \brief Reset training data for booster.
 * \param handle Handle of booster
 * \param train_data Training dataset
 * \return 0 when succeed, -1 when failure happens
718
 */
719
LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle,
720
                                                    const DatasetHandle train_data);
wxchan's avatar
wxchan committed
721
722

/*!
723
724
 * \brief Reset config for booster.
 * \param handle Handle of booster
725
 * \param parameters Parameters in format 'key1=value1 key2=value2'
726
 * \return 0 when succeed, -1 when failure happens
727
 */
728
729
LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle,
                                                 const char* parameters);
wxchan's avatar
wxchan committed
730
731

/*!
732
733
734
735
 * \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
736
 */
737
738
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
739

Guolin Ke's avatar
Guolin Ke committed
740
/*!
741
742
 * \brief Update the model for one iteration.
 * \param handle Handle of booster
743
 * \param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure
744
 * \return 0 when succeed, -1 when failure happens
745
 */
746
747
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle,
                                                int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
748

Guolin Ke's avatar
Guolin Ke committed
749
/*!
750
751
752
 * \brief Refit the tree model using the new data (online learning).
 * \param handle Handle of booster
 * \param leaf_preds Pointer to predicted leaf indices
753
754
 * \param nrow Number of rows of ``leaf_preds``
 * \param ncol Number of columns of ``leaf_preds``
755
 * \return 0 when succeed, -1 when failure happens
756
 */
757
758
759
760
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
761

Guolin Ke's avatar
Guolin Ke committed
762
/*!
763
764
 * \brief Update the model by specifying gradient and Hessian directly
 *        (this can be used to support customized loss functions).
765
766
767
 * \note
 * The length of the arrays referenced by ``grad`` and ``hess`` must be equal to
 * ``num_class * num_train_data``, this is not verified by the library, the caller must ensure this.
768
769
770
 * \param handle Handle of booster
 * \param grad The first order derivative (gradient) statistics
 * \param hess The second order derivative (Hessian) statistics
771
 * \param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure
772
 * \return 0 when succeed, -1 when failure happens
773
 */
774
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
775
776
777
                                                      const float* grad,
                                                      const float* hess,
                                                      int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
778
779

/*!
780
781
782
 * \brief Rollback one iteration.
 * \param handle Handle of booster
 * \return 0 when succeed, -1 when failure happens
783
 */
784
LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle);
wxchan's avatar
wxchan committed
785
786

/*!
787
788
789
790
 * \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
791
 */
792
793
LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle,
                                                      int* out_iteration);
Guolin Ke's avatar
Guolin Ke committed
794

795
/*!
796
797
798
799
 * \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
800
 */
801
802
LIGHTGBM_C_EXPORT int LGBM_BoosterNumModelPerIteration(BoosterHandle handle,
                                                       int* out_tree_per_iteration);
803
804

/*!
805
806
807
808
 * \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
809
 */
810
811
LIGHTGBM_C_EXPORT int LGBM_BoosterNumberOfTotalModel(BoosterHandle handle,
                                                     int* out_models);
812

Guolin Ke's avatar
Guolin Ke committed
813
/*!
814
 * \brief Get number of evaluation metrics.
815
 * \param handle Handle of booster
816
 * \param[out] out_len Total number of evaluation metrics
817
 * \return 0 when succeed, -1 when failure happens
818
 */
819
820
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
821
822

/*!
823
 * \brief Get names of evaluation metrics.
824
 * \param handle Handle of booster
825
826
 * \param len Number of ``char*`` pointers stored at ``out_strs``.
 *            If smaller than the max size, only this many strings are copied
827
 * \param[out] out_len Total number of evaluation metrics
828
 * \param buffer_len Size of pre-allocated strings.
829
830
 *                   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
831
 * \param[out] out_strs Names of evaluation metrics, should pre-allocate memory
832
 * \return 0 when succeed, -1 when failure happens
833
 */
834
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle,
835
                                               const int len,
836
                                               int* out_len,
837
838
                                               const size_t buffer_len,
                                               size_t* out_buffer_len,
839
                                               char** out_strs);
wxchan's avatar
wxchan committed
840

wxchan's avatar
wxchan committed
841
/*!
842
843
 * \brief Get names of features.
 * \param handle Handle of booster
844
845
 * \param len Number of ``char*`` pointers stored at ``out_strs``.
 *            If smaller than the max size, only this many strings are copied
846
 * \param[out] out_len Total number of features
847
848
849
 * \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
850
851
 * \param[out] out_strs Names of features, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
852
 */
853
LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle,
854
                                                  const int len,
855
                                                  int* out_len,
856
857
                                                  const size_t buffer_len,
                                                  size_t* out_buffer_len,
858
                                                  char** out_strs);
wxchan's avatar
wxchan committed
859

860
861
862
863
864
865
866
867
868
869
870
/*!
 * \brief Check that the feature names of the data match the ones used to train the booster.
 * \param handle Handle of booster
 * \param data_names Array with the feature names in the data
 * \param data_num_features Number of features in the data
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterValidateFeatureNames(BoosterHandle handle,
                                                       const char** data_names,
                                                       int data_num_features);

wxchan's avatar
wxchan committed
871
/*!
872
873
874
875
 * \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
876
 */
877
878
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
879

wxchan's avatar
wxchan committed
880
/*!
881
 * \brief Get evaluation for training data and validation data.
882
 * \note
883
 *   1. You should call ``LGBM_BoosterGetEvalNames`` first to get the names of evaluation metrics.
884
 *   2. You should pre-allocate memory for ``out_results``, you can get its length by ``LGBM_BoosterGetEvalCounts``.
885
886
887
 * \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
888
 * \param[out] out_results Array with evaluation results
889
 * \return 0 when succeed, -1 when failure happens
890
 */
891
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle,
892
893
894
                                          int data_idx,
                                          int* out_len,
                                          double* out_results);
Guolin Ke's avatar
Guolin Ke committed
895
896

/*!
897
898
 * \brief Get number of predictions for training data and validation data
 *        (this can be used to support customized evaluation functions).
899
900
901
902
 * \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
903
 */
904
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle,
905
906
                                                int data_idx,
                                                int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
907

Guolin Ke's avatar
Guolin Ke committed
908
/*!
909
 * \brief Get prediction for training data and validation data.
910
911
 * \note
 * You should pre-allocate memory for ``out_result``, its length is equal to ``num_class * num_data``.
912
913
914
915
916
 * \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
917
 */
918
LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle,
919
920
921
                                             int data_idx,
                                             int64_t* out_len,
                                             double* out_result);
Guolin Ke's avatar
Guolin Ke committed
922

923
/*!
924
925
926
927
928
 * \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
929
930
931
932
 *   - ``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)
933
 * \param start_iteration Start index of the iteration to predict
934
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
935
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
936
937
 * \param result_filename Filename of result file in which predictions will be written
 * \return 0 when succeed, -1 when failure happens
938
 */
939
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle,
940
941
942
                                                 const char* data_filename,
                                                 int data_has_header,
                                                 int predict_type,
943
                                                 int start_iteration,
944
                                                 int num_iteration,
945
                                                 const char* parameter,
946
                                                 const char* result_filename);
947

Guolin Ke's avatar
Guolin Ke committed
948
/*!
949
950
951
952
 * \brief Get number of predictions.
 * \param handle Handle of booster
 * \param num_row Number of rows
 * \param predict_type What should be predicted
953
954
955
956
 *   - ``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)
957
 * \param start_iteration Start index of the iteration to predict
958
959
960
 * \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
961
 */
962
LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle,
963
964
                                                 int num_row,
                                                 int predict_type,
965
                                                 int start_iteration,
966
967
                                                 int num_iteration,
                                                 int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
968

969
970
971
972
973
974
975
976
/*!
 * \brief Release FastConfig object.
 *
 * \param fastConfig Handle to the FastConfig object acquired with a ``*FastInit()`` method.
 * \return 0 when it succeeds, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_FastConfigFree(FastConfigHandle fastConfig);

Guolin Ke's avatar
Guolin Ke committed
977
/*!
978
 * \brief Make prediction for a new dataset in CSR format.
979
980
981
982
983
 * \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)``.
984
985
 * \param handle Handle of booster
 * \param indptr Pointer to row headers
986
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
987
988
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
989
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
990
991
 * \param nindptr Number of rows in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
992
 * \param num_col Number of columns
993
 * \param predict_type What should be predicted
994
995
996
997
 *   - ``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)
998
 * \param start_iteration Start index of the iteration to predict
999
1000
1001
1002
1003
 * \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
1004
 */
1005
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle,
1006
1007
1008
1009
1010
1011
1012
1013
1014
                                                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,
1015
                                                int start_iteration,
1016
                                                int num_iteration,
1017
                                                const char* parameter,
1018
1019
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
1020

1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
/*!
 * \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``
1034
 * \param nindptr Number of entries in ``indptr``
1035
1036
1037
1038
 * \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)
1039
 * \param start_iteration Start index of the iteration to predict
1040
1041
1042
 * \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``
1043
 * \param[out] out_len Length of output data and output indptr (pointer to an array with two entries where to write them)
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
 * \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,
1059
                                                      int start_iteration,
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
                                                      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);

1079
/*!
1080
 * \brief Make prediction for a new dataset in CSR format. This method re-uses the internal predictor structure
1081
 *        from previous calls and is optimized for single row invocation.
1082
1083
1084
1085
1086
 * \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)``.
1087
1088
 * \param handle Handle of booster
 * \param indptr Pointer to row headers
1089
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
1090
1091
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
1092
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1093
1094
 * \param nindptr Number of rows in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
1095
 * \param num_col Number of columns
1096
 * \param predict_type What should be predicted
1097
1098
1099
1100
 *   - ``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)
1101
 * \param start_iteration Start index of the iteration to predict
1102
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
1103
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1104
1105
1106
 * \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
1107
 */
1108
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRow(BoosterHandle handle,
1109
1110
1111
1112
1113
1114
1115
1116
1117
                                                         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,
1118
                                                         int start_iteration,
1119
1120
1121
1122
                                                         int num_iteration,
                                                         const char* parameter,
                                                         int64_t* out_len,
                                                         double* out_result);
1123

1124
1125
1126
1127
1128
1129
/*!
 * \brief Initialize and return a ``FastConfigHandle`` for use with ``LGBM_BoosterPredictForCSRSingleRowFast``.
 *
 * Release the ``FastConfig`` by passing its handle to ``LGBM_FastConfigFree`` when no longer needed.
 *
 * \param handle Booster handle
1130
1131
1132
1133
1134
 * \param predict_type What should be predicted
 *   - ``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)
1135
 * \param start_iteration Start index of the iteration to predict
1136
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
1137
1138
1139
1140
1141
1142
1143
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
 * \param num_col Number of columns
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
 * \param[out] out_fastConfig FastConfig object with which you can call ``LGBM_BoosterPredictForCSRSingleRowFast``
 * \return 0 when it succeeds, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRowFastInit(BoosterHandle handle,
1144
                                                                 const int predict_type,
1145
                                                                 const int start_iteration,
1146
                                                                 const int num_iteration,
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
                                                                 const int data_type,
                                                                 const int64_t num_col,
                                                                 const char* parameter,
                                                                 FastConfigHandle *out_fastConfig);

/*!
 * \brief Faster variant of ``LGBM_BoosterPredictForCSRSingleRow``.
 *
 * Score single rows after setup with ``LGBM_BoosterPredictForCSRSingleRowFastInit``.
 *
 * By removing the setup steps from this call extra optimizations can be made like
 * initializing the config only once, instead of once per call.
 *
 * \note
 *   Setting up the number of threads is only done once at ``LGBM_BoosterPredictForCSRSingleRowFastInit``
 *   instead of at each prediction.
 *   If you use a different number of threads in other calls, you need to start the setup process over,
 *   or that number of threads will be used for these calls as well.
 *
 * \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)``.
 *
 * \param fastConfig_handle FastConfig object handle returned by ``LGBM_BoosterPredictForCSRSingleRowFastInit``
 * \param indptr Pointer to row headers
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
 * \param nindptr Number of rows in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
 * \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
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRowFast(FastConfigHandle fastConfig_handle,
                                                             const void* indptr,
1185
                                                             const int indptr_type,
1186
1187
                                                             const int32_t* indices,
                                                             const void* data,
1188
1189
                                                             const int64_t nindptr,
                                                             const int64_t nelem,
1190
1191
1192
                                                             int64_t* out_len,
                                                             double* out_result);

Guolin Ke's avatar
Guolin Ke committed
1193
/*!
1194
 * \brief Make prediction for a new dataset in CSC format.
1195
1196
1197
1198
1199
 * \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)``.
1200
1201
 * \param handle Handle of booster
 * \param col_ptr Pointer to column headers
1202
 * \param col_ptr_type Type of ``col_ptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
1203
1204
 * \param indices Pointer to row indices
 * \param data Pointer to the data space
1205
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1206
1207
1208
1209
 * \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
1210
1211
1212
1213
 *   - ``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)
1214
 * \param start_iteration Start index of the iteration to predict
1215
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
1216
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1217
1218
1219
 * \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
1220
 */
1221
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle,
1222
1223
1224
1225
1226
1227
1228
1229
1230
                                                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,
1231
                                                int start_iteration,
1232
                                                int num_iteration,
1233
                                                const char* parameter,
1234
1235
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
1236
1237

/*!
1238
 * \brief Make prediction for a new dataset.
1239
1240
1241
1242
1243
 * \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)``.
1244
1245
 * \param handle Handle of booster
 * \param data Pointer to the data space
1246
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1247
1248
1249
1250
 * \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
1251
1252
1253
1254
 *   - ``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)
1255
 * \param start_iteration Start index of the iteration to predict
1256
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
1257
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1258
1259
1260
 * \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
1261
 */
1262
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle,
1263
1264
1265
1266
1267
1268
                                                const void* data,
                                                int data_type,
                                                int32_t nrow,
                                                int32_t ncol,
                                                int is_row_major,
                                                int predict_type,
1269
                                                int start_iteration,
1270
                                                int num_iteration,
1271
                                                const char* parameter,
1272
1273
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
1274

1275
/*!
1276
 * \brief Make prediction for a new dataset. This method re-uses the internal predictor structure
1277
 *        from previous calls and is optimized for single row invocation.
1278
1279
1280
1281
1282
 * \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)``.
1283
1284
 * \param handle Handle of booster
 * \param data Pointer to the data space
1285
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1286
 * \param ncol Number columns
1287
 * \param is_row_major 1 for row-major, 0 for column-major
1288
 * \param predict_type What should be predicted
1289
1290
1291
1292
 *   - ``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)
1293
 * \param start_iteration Start index of the iteration to predict
1294
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
1295
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1296
1297
1298
 * \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
1299
 */
1300
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRow(BoosterHandle handle,
1301
1302
1303
1304
1305
                                                         const void* data,
                                                         int data_type,
                                                         int ncol,
                                                         int is_row_major,
                                                         int predict_type,
1306
                                                         int start_iteration,
1307
1308
1309
1310
                                                         int num_iteration,
                                                         const char* parameter,
                                                         int64_t* out_len,
                                                         double* out_result);
1311

1312
1313
1314
1315
1316
1317
/*!
 * \brief Initialize and return a ``FastConfigHandle`` for use with ``LGBM_BoosterPredictForMatSingleRowFast``.
 *
 * Release the ``FastConfig`` by passing its handle to ``LGBM_FastConfigFree`` when no longer needed.
 *
 * \param handle Booster handle
1318
1319
1320
1321
1322
 * \param predict_type What should be predicted
 *   - ``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)
1323
 * \param start_iteration Start index of the iteration to predict
1324
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
1325
1326
1327
1328
1329
1330
1331
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
 * \param ncol Number of columns
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
 * \param[out] out_fastConfig FastConfig object with which you can call ``LGBM_BoosterPredictForMatSingleRowFast``
 * \return 0 when it succeeds, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRowFastInit(BoosterHandle handle,
1332
                                                                 const int predict_type,
1333
                                                                 const int start_iteration,
1334
1335
1336
                                                                 const int num_iteration,
                                                                 const int data_type,
                                                                 const int32_t ncol,
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
                                                                 const char* parameter,
                                                                 FastConfigHandle *out_fastConfig);

/*!
 * \brief Faster variant of ``LGBM_BoosterPredictForMatSingleRow``.
 *
 * Score a single row after setup with ``LGBM_BoosterPredictForMatSingleRowFastInit``.
 *
 * By removing the setup steps from this call extra optimizations can be made like
 * initializing the config only once, instead of once per call.
 *
 * \note
 *   Setting up the number of threads is only done once at ``LGBM_BoosterPredictForMatSingleRowFastInit``
 *   instead of at each prediction.
 *   If you use a different number of threads in other calls, you need to start the setup process over,
 *   or that number of threads will be used for these calls as well.
 *
 * \param fastConfig_handle FastConfig object handle returned by ``LGBM_BoosterPredictForMatSingleRowFastInit``
 * \param data Single-row array data (no other way than row-major form).
 * \param[out] out_len Length of output result
 * \param[out] out_result Pointer to array with predictions
 * \return 0 when it succeeds, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRowFast(FastConfigHandle fastConfig_handle,
                                                             const void* data,
                                                             int64_t* out_len,
                                                             double* out_result);

1365
1366
/*!
 * \brief Make prediction for a new dataset presented in a form of array of pointers to rows.
1367
1368
1369
1370
1371
 * \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)``.
1372
1373
 * \param handle Handle of booster
 * \param data Pointer to the data space
1374
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1375
1376
1377
 * \param nrow Number of rows
 * \param ncol Number columns
 * \param predict_type What should be predicted
1378
1379
1380
1381
 *   - ``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)
1382
 * \param start_iteration Start index of the iteration to predict
1383
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
1384
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1385
1386
1387
 * \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
1388
 */
1389
1390
1391
1392
1393
1394
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMats(BoosterHandle handle,
                                                 const void** data,
                                                 int data_type,
                                                 int32_t nrow,
                                                 int32_t ncol,
                                                 int predict_type,
1395
                                                 int start_iteration,
1396
1397
1398
1399
                                                 int num_iteration,
                                                 const char* parameter,
                                                 int64_t* out_len,
                                                 double* out_result);
1400

Guolin Ke's avatar
Guolin Ke committed
1401
/*!
1402
1403
1404
1405
 * \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
1406
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1407
 * \param filename The name of the file
1408
 * \return 0 when succeed, -1 when failure happens
1409
 */
1410
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle,
1411
                                            int start_iteration,
1412
                                            int num_iteration,
1413
                                            int feature_importance_type,
1414
                                            const char* filename);
Guolin Ke's avatar
Guolin Ke committed
1415

1416
/*!
1417
1418
1419
1420
 * \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
1421
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1422
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
1423
1424
1425
 * \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
1426
 */
1427
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle,
1428
                                                    int start_iteration,
1429
                                                    int num_iteration,
1430
                                                    int feature_importance_type,
1431
1432
                                                    int64_t buffer_len,
                                                    int64_t* out_len,
1433
                                                    char* out_str);
1434

wxchan's avatar
wxchan committed
1435
/*!
1436
1437
1438
 * \brief Dump model to JSON.
 * \param handle Handle of booster
 * \param start_iteration Start index of the iteration that should be dumped
1439
 * \param num_iteration Index of the iteration that should be dumped, <= 0 means dump all
1440
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1441
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
1442
1443
1444
 * \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
1445
 */
1446
LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle,
1447
                                            int start_iteration,
1448
                                            int num_iteration,
1449
                                            int feature_importance_type,
1450
1451
                                            int64_t buffer_len,
                                            int64_t* out_len,
1452
                                            char* out_str);
1453

Guolin Ke's avatar
Guolin Ke committed
1454
/*!
1455
1456
1457
1458
1459
1460
 * \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
1461
 */
1462
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle,
1463
1464
1465
                                               int tree_idx,
                                               int leaf_idx,
                                               double* out_val);
Guolin Ke's avatar
Guolin Ke committed
1466
1467

/*!
1468
1469
1470
1471
1472
1473
 * \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
1474
 */
1475
LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle,
1476
1477
1478
                                               int tree_idx,
                                               int leaf_idx,
                                               double val);
1479

1480
/*!
1481
1482
1483
1484
 * \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:
1485
1486
 *   - ``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
1487
1488
 * \param[out] out_results Result array with feature importance
 * \return 0 when succeed, -1 when failure happens
1489
 */
1490
1491
1492
1493
1494
LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle,
                                                    int num_iteration,
                                                    int importance_type,
                                                    double* out_results);

1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
/*!
 * \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);

1513
/*!
1514
1515
1516
1517
1518
1519
 * \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
1520
 */
1521
1522
1523
1524
1525
1526
LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines,
                                       int local_listen_port,
                                       int listen_time_out,
                                       int num_machines);

/*!
1527
1528
 * \brief Finalize the network.
 * \return 0 when succeed, -1 when failure happens
1529
 */
1530
1531
LIGHTGBM_C_EXPORT int LGBM_NetworkFree();

1532
1533
1534
1535
1536
1537
1538
/*!
 * \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
1539
1540
1541
 */
LIGHTGBM_C_EXPORT int LGBM_NetworkInitWithFunctions(int num_machines,
                                                    int rank,
1542
                                                    void* reduce_scatter_ext_fun,
1543
                                                    void* allgather_ext_fun);
1544

1545
#if !defined(__cplusplus) && (!defined(__STDC__) || (__STDC_VERSION__ < 199901L))
1546
1547
/*! \brief Inline specifier no-op in C using standards before C99. */
#define INLINE_FUNCTION
1548
#else
1549
1550
/*! \brief Inline specifier. */
#define INLINE_FUNCTION inline
1551
1552
1553
#endif

#if !defined(__cplusplus) && (!defined(__STDC__) || (__STDC_VERSION__ < 201112L))
1554
1555
/*! \brief Thread local specifier no-op in C using standards before C11. */
#define THREAD_LOCAL
1556
#elif !defined(__cplusplus)
1557
1558
/*! \brief Thread local specifier. */
#define THREAD_LOCAL _Thread_local
1559
#elif defined(_MSC_VER)
1560
1561
/*! \brief Thread local specifier. */
#define THREAD_LOCAL __declspec(thread)
Guolin Ke's avatar
Guolin Ke committed
1562
#else
1563
1564
/*! \brief Thread local specifier. */
#define THREAD_LOCAL thread_local
Guolin Ke's avatar
Guolin Ke committed
1565
#endif
1566
1567
1568
1569
1570

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

1573
1574
1575
#ifdef _MSC_VER
  #pragma warning(disable : 4996)
#endif
1576
1577
/*!
 * \brief Set string message of the last error.
1578
1579
 * \note
 * This will call unsafe ``sprintf`` when compiled using C standards before C99.
1580
1581
 * \param msg Error message
 */
1582
INLINE_FUNCTION void LGBM_SetLastError(const char* msg) {
1583
1584
1585
#if !defined(__cplusplus) && (!defined(__STDC__) || (__STDC_VERSION__ < 199901L))
  sprintf(LastErrorMsg(), "%s", msg);  /* NOLINT(runtime/printf) */
#else
1586
1587
  const int err_buf_len = 512;
  snprintf(LastErrorMsg(), err_buf_len, "%s", msg);
1588
#endif
1589
1590
}

1591
#endif  /* LIGHTGBM_C_API_H_ */