c_api.h 83.9 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
 */
13
14
#ifndef LIGHTGBM_INCLUDE_LIGHTGBM_C_API_H_
#define LIGHTGBM_INCLUDE_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
 * \param nrow Number of rows
 * \param ncol Number of columns
425
 * \param is_row_major Pointer to the data layouts. 1 for row-major, 0 for column-major
426
427
428
429
 * \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
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMats(int32_t nmat,
                                                 const void** data,
                                                 int data_type,
                                                 int32_t* nrow,
                                                 int32_t ncol,
436
                                                 int* is_row_major,
437
438
439
440
                                                 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
/*!
 * \brief Set vector to a content in info.
 * \note
561
 * - \a group converts input datatype into ``int32``;
562
563
 * - \a label and \a weight convert input datatype into ``float32``;
 * - \a init_score converts input datatype into ``float64``.
564
 * \param handle Handle of dataset
565
 * \param field_name Field name, can be \a label, \a weight, \a init_score, \a group
566
567
568
569
570
571
572
573
574
575
576
 * \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
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetSetFieldFromArrow(DatasetHandle handle,
                                                    const char* field_name,
                                                    int64_t n_chunks,
                                                    const ArrowArray* chunks,
                                                    const ArrowSchema* schema);

Guolin Ke's avatar
Guolin Ke committed
577
/*!
578
579
580
581
582
 * \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
583
 * \param[out] out_type Type of result pointer, can be ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
584
 * \return 0 when succeed, -1 when failure happens
585
 */
586
LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle,
587
588
589
590
                                           const char* field_name,
                                           int* out_len,
                                           const void** out_ptr,
                                           int* out_type);
Guolin Ke's avatar
Guolin Ke committed
591

592
/*!
593
594
595
596
 * \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
597
 */
598
599
LIGHTGBM_C_EXPORT int LGBM_DatasetUpdateParamChecking(const char* old_parameters,
                                                      const char* new_parameters);
600

Guolin Ke's avatar
Guolin Ke committed
601
/*!
602
603
604
605
 * \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
606
 */
607
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle,
608
                                             int* out);
Guolin Ke's avatar
Guolin Ke committed
609
610

/*!
611
612
613
614
 * \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
615
 */
616
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle,
617
                                                int* out);
Guolin Ke's avatar
Guolin Ke committed
618

619
620
621
622
623
624
625
626
627
628
629
/*!
 * \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);

630
/*!
631
 * \brief Add features from ``source`` to ``target``.
632
633
634
 * \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
635
 */
636
637
638
LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target,
                                                  DatasetHandle source);

639
/* --- start Booster interfaces */
Guolin Ke's avatar
Guolin Ke committed
640

641
/*!
642
* \brief Get int representing whether booster is fitting linear trees.
643
644
645
646
* \param handle Handle of booster
* \param[out] out The address to hold linear trees indicator
* \return 0 when succeed, -1 when failure happens
*/
647
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLinear(BoosterHandle handle, int* out);
648

Guolin Ke's avatar
Guolin Ke committed
649
/*!
650
651
 * \brief Create a new boosting learner.
 * \param train_data Training dataset
652
 * \param parameters Parameters in format 'key1=value1 key2=value2'
653
 * \param[out] out Handle of created booster
654
655
 * \return 0 when succeed, -1 when failure happens
 */
656
LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data,
657
658
                                         const char* parameters,
                                         BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
659
660

/*!
661
662
663
664
665
 * \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
666
 */
667
668
669
LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(const char* filename,
                                                      int* out_num_iterations,
                                                      BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
670

671
/*!
672
673
674
675
676
 * \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
677
 */
678
679
680
LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(const char* model_str,
                                                      int* out_num_iterations,
                                                      BoosterHandle* out);
wxchan's avatar
wxchan committed
681

682
683
/*!
 * \brief Get parameters as JSON string.
684
685
686
687
 * \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
688
689
690
691
692
693
694
695
 * \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
696
/*!
697
698
699
 * \brief Free space for booster.
 * \param handle Handle of booster to be freed
 * \return 0 when succeed, -1 when failure happens
700
 */
701
LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle);
Guolin Ke's avatar
Guolin Ke committed
702

703
/*!
704
705
706
707
708
 * \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
709
 */
710
711
712
LIGHTGBM_C_EXPORT int LGBM_BoosterShuffleModels(BoosterHandle handle,
                                                int start_iter,
                                                int end_iter);
713

wxchan's avatar
wxchan committed
714
/*!
715
 * \brief Merge model from ``other_handle`` into ``handle``.
716
717
718
 * \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
719
 */
720
LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle,
721
                                        BoosterHandle other_handle);
wxchan's avatar
wxchan committed
722
723

/*!
724
725
726
727
 * \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
728
 */
729
LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle,
730
                                               const DatasetHandle valid_data);
wxchan's avatar
wxchan committed
731
732

/*!
733
734
735
736
 * \brief Reset training data for booster.
 * \param handle Handle of booster
 * \param train_data Training dataset
 * \return 0 when succeed, -1 when failure happens
737
 */
738
LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle,
739
                                                    const DatasetHandle train_data);
wxchan's avatar
wxchan committed
740
741

/*!
742
743
 * \brief Reset config for booster.
 * \param handle Handle of booster
744
 * \param parameters Parameters in format 'key1=value1 key2=value2'
745
 * \return 0 when succeed, -1 when failure happens
746
 */
747
748
LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle,
                                                 const char* parameters);
wxchan's avatar
wxchan committed
749
750

/*!
751
752
753
754
 * \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
755
 */
756
757
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
758

Guolin Ke's avatar
Guolin Ke committed
759
/*!
760
761
 * \brief Update the model for one iteration.
 * \param handle Handle of booster
762
763
764
765
766
 * \param[out] produced_empty_tree 1 means the tree(s) produced by this iteration did not have any splits.
 *                         This usually means that training is "finished" (calling this function again will not change the model's predictions).
 *                         However, that is not always the case.
 *                         For example, if you have added any randomness (like column sampling by setting ``feature_fraction_bynode < 1.0``),
 *                         it is possible that another call to this function would produce a non-empty tree.
767
 * \return 0 when succeed, -1 when failure happens
768
 */
769
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle,
770
                                                int* produced_empty_tree);
Guolin Ke's avatar
Guolin Ke committed
771

Guolin Ke's avatar
Guolin Ke committed
772
/*!
773
774
775
 * \brief Refit the tree model using the new data (online learning).
 * \param handle Handle of booster
 * \param leaf_preds Pointer to predicted leaf indices
776
777
 * \param nrow Number of rows of ``leaf_preds``
 * \param ncol Number of columns of ``leaf_preds``
778
 * \return 0 when succeed, -1 when failure happens
779
 */
780
781
782
783
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
784

Guolin Ke's avatar
Guolin Ke committed
785
/*!
786
787
 * \brief Update the model by specifying gradient and Hessian directly
 *        (this can be used to support customized loss functions).
788
789
790
 * \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.
791
792
793
 * \param handle Handle of booster
 * \param grad The first order derivative (gradient) statistics
 * \param hess The second order derivative (Hessian) statistics
794
795
796
797
798
 * \param[out] produced_empty_tree 1 means the tree(s) produced by this iteration did not have any splits.
 *                         This usually means that training is "finished" (calling this function again will not change the model's predictions).
 *                         However, that is not always the case.
 *                         For example, if you have added any randomness (like column sampling by setting ``feature_fraction_bynode < 1.0``),
 *                         it is possible that another call to this function would produce a non-empty tree.
799
 * \return 0 when succeed, -1 when failure happens
800
 */
801
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
802
803
                                                      const float* grad,
                                                      const float* hess,
804
                                                      int* produced_empty_tree);
Guolin Ke's avatar
Guolin Ke committed
805
806

/*!
807
808
809
 * \brief Rollback one iteration.
 * \param handle Handle of booster
 * \return 0 when succeed, -1 when failure happens
810
 */
811
LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle);
wxchan's avatar
wxchan committed
812
813

/*!
814
815
816
817
 * \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
818
 */
819
820
LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle,
                                                      int* out_iteration);
Guolin Ke's avatar
Guolin Ke committed
821

822
/*!
823
824
825
826
 * \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
827
 */
828
829
LIGHTGBM_C_EXPORT int LGBM_BoosterNumModelPerIteration(BoosterHandle handle,
                                                       int* out_tree_per_iteration);
830
831

/*!
832
833
834
835
 * \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
836
 */
837
838
LIGHTGBM_C_EXPORT int LGBM_BoosterNumberOfTotalModel(BoosterHandle handle,
                                                     int* out_models);
839

Guolin Ke's avatar
Guolin Ke committed
840
/*!
841
 * \brief Get number of evaluation metrics.
842
 * \param handle Handle of booster
843
 * \param[out] out_len Total number of evaluation metrics
844
 * \return 0 when succeed, -1 when failure happens
845
 */
846
847
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
848
849

/*!
850
 * \brief Get names of evaluation metrics.
851
 * \param handle Handle of booster
852
853
 * \param len Number of ``char*`` pointers stored at ``out_strs``.
 *            If smaller than the max size, only this many strings are copied
854
 * \param[out] out_len Total number of evaluation metrics
855
 * \param buffer_len Size of pre-allocated strings.
856
857
 *                   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
858
 * \param[out] out_strs Names of evaluation metrics, should pre-allocate memory
859
 * \return 0 when succeed, -1 when failure happens
860
 */
861
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle,
862
                                               const int len,
863
                                               int* out_len,
864
865
                                               const size_t buffer_len,
                                               size_t* out_buffer_len,
866
                                               char** out_strs);
wxchan's avatar
wxchan committed
867

wxchan's avatar
wxchan committed
868
/*!
869
870
 * \brief Get names of features.
 * \param handle Handle of booster
871
872
 * \param len Number of ``char*`` pointers stored at ``out_strs``.
 *            If smaller than the max size, only this many strings are copied
873
 * \param[out] out_len Total number of features
874
875
876
 * \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
877
878
 * \param[out] out_strs Names of features, should pre-allocate memory
 * \return 0 when succeed, -1 when failure happens
879
 */
880
LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle,
881
                                                  const int len,
882
                                                  int* out_len,
883
884
                                                  const size_t buffer_len,
                                                  size_t* out_buffer_len,
885
                                                  char** out_strs);
wxchan's avatar
wxchan committed
886

887
888
889
890
891
892
893
894
895
896
897
/*!
 * \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
898
/*!
899
900
901
902
 * \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
903
 */
904
905
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle,
                                                int* out_len);
wxchan's avatar
wxchan committed
906

wxchan's avatar
wxchan committed
907
/*!
908
 * \brief Get evaluation for training data and validation data.
909
 * \note
910
 *   1. You should call ``LGBM_BoosterGetEvalNames`` first to get the names of evaluation metrics.
911
 *   2. You should pre-allocate memory for ``out_results``, you can get its length by ``LGBM_BoosterGetEvalCounts``.
912
913
914
 * \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
915
 * \param[out] out_results Array with evaluation results
916
 * \return 0 when succeed, -1 when failure happens
917
 */
918
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle,
919
920
921
                                          int data_idx,
                                          int* out_len,
                                          double* out_results);
Guolin Ke's avatar
Guolin Ke committed
922
923

/*!
924
925
 * \brief Get number of predictions for training data and validation data
 *        (this can be used to support customized evaluation functions).
926
927
928
929
 * \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
930
 */
931
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle,
932
933
                                                int data_idx,
                                                int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
934

Guolin Ke's avatar
Guolin Ke committed
935
/*!
936
 * \brief Get prediction for training data and validation data.
937
938
 * \note
 * You should pre-allocate memory for ``out_result``, its length is equal to ``num_class * num_data``.
939
940
941
942
943
 * \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
944
 */
945
LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle,
946
947
948
                                             int data_idx,
                                             int64_t* out_len,
                                             double* out_result);
Guolin Ke's avatar
Guolin Ke committed
949

950
/*!
951
952
953
954
955
 * \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
956
957
958
959
 *   - ``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)
960
 * \param start_iteration Start index of the iteration to predict
961
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
962
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
963
964
 * \param result_filename Filename of result file in which predictions will be written
 * \return 0 when succeed, -1 when failure happens
965
 */
966
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle,
967
968
969
                                                 const char* data_filename,
                                                 int data_has_header,
                                                 int predict_type,
970
                                                 int start_iteration,
971
                                                 int num_iteration,
972
                                                 const char* parameter,
973
                                                 const char* result_filename);
974

Guolin Ke's avatar
Guolin Ke committed
975
/*!
976
977
978
979
 * \brief Get number of predictions.
 * \param handle Handle of booster
 * \param num_row Number of rows
 * \param predict_type What should be predicted
980
981
982
983
 *   - ``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)
984
 * \param start_iteration Start index of the iteration to predict
985
986
987
 * \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
988
 */
989
LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle,
990
991
                                                 int num_row,
                                                 int predict_type,
992
                                                 int start_iteration,
993
994
                                                 int num_iteration,
                                                 int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
995

996
997
998
999
1000
1001
1002
1003
/*!
 * \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
1004
/*!
1005
 * \brief Make prediction for a new dataset in CSR format.
1006
1007
1008
1009
1010
 * \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)``.
1011
1012
 * \param handle Handle of booster
 * \param indptr Pointer to row headers
1013
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
1014
1015
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
1016
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1017
1018
 * \param nindptr Number of rows in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
1019
 * \param num_col Number of columns
1020
 * \param predict_type What should be predicted
1021
1022
1023
1024
 *   - ``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)
1025
 * \param start_iteration Start index of the iteration to predict
1026
1027
1028
1029
1030
 * \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
1031
 */
1032
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle,
1033
1034
1035
1036
1037
1038
1039
1040
1041
                                                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,
1042
                                                int start_iteration,
1043
                                                int num_iteration,
1044
                                                const char* parameter,
1045
1046
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
1047

1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
/*!
 * \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``
1061
 * \param nindptr Number of entries in ``indptr``
1062
1063
1064
1065
 * \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)
1066
 * \param start_iteration Start index of the iteration to predict
1067
1068
1069
 * \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``
1070
 * \param[out] out_len Length of output data and output indptr (pointer to an array with two entries where to write them)
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
 * \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,
1086
                                                      int start_iteration,
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
                                                      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);

1106
/*!
1107
 * \brief Make prediction for a new dataset in CSR format. This method re-uses the internal predictor structure
1108
 *        from previous calls and is optimized for single row invocation.
1109
1110
1111
1112
1113
 * \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)``.
1114
1115
 * \param handle Handle of booster
 * \param indptr Pointer to row headers
1116
 * \param indptr_type Type of ``indptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
1117
1118
 * \param indices Pointer to column indices
 * \param data Pointer to the data space
1119
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1120
1121
 * \param nindptr Number of rows in the matrix + 1
 * \param nelem Number of nonzero elements in the matrix
1122
 * \param num_col Number of columns
1123
 * \param predict_type What should be predicted
1124
1125
1126
1127
 *   - ``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)
1128
 * \param start_iteration Start index of the iteration to predict
1129
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
1130
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1131
1132
1133
 * \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
1134
 */
1135
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRow(BoosterHandle handle,
1136
1137
1138
1139
1140
1141
1142
1143
1144
                                                         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,
1145
                                                         int start_iteration,
1146
1147
1148
1149
                                                         int num_iteration,
                                                         const char* parameter,
                                                         int64_t* out_len,
                                                         double* out_result);
1150

1151
1152
1153
1154
1155
1156
/*!
 * \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
1157
1158
1159
1160
1161
 * \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)
1162
 * \param start_iteration Start index of the iteration to predict
1163
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
1164
1165
1166
1167
1168
1169
1170
 * \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,
1171
                                                                 const int predict_type,
1172
                                                                 const int start_iteration,
1173
                                                                 const int num_iteration,
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
                                                                 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,
1212
                                                             const int indptr_type,
1213
1214
                                                             const int32_t* indices,
                                                             const void* data,
1215
1216
                                                             const int64_t nindptr,
                                                             const int64_t nelem,
1217
1218
1219
                                                             int64_t* out_len,
                                                             double* out_result);

Guolin Ke's avatar
Guolin Ke committed
1220
/*!
1221
 * \brief Make prediction for a new dataset in CSC format.
1222
1223
1224
1225
1226
 * \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)``.
1227
1228
 * \param handle Handle of booster
 * \param col_ptr Pointer to column headers
1229
 * \param col_ptr_type Type of ``col_ptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``
1230
1231
 * \param indices Pointer to row indices
 * \param data Pointer to the data space
1232
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1233
1234
1235
1236
 * \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
1237
1238
1239
1240
 *   - ``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)
1241
 * \param start_iteration Start index of the iteration to predict
1242
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
1243
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1244
1245
1246
 * \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
1247
 */
1248
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle,
1249
1250
1251
1252
1253
1254
1255
1256
1257
                                                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,
1258
                                                int start_iteration,
1259
                                                int num_iteration,
1260
                                                const char* parameter,
1261
1262
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
1263
1264

/*!
1265
 * \brief Make prediction for a new dataset.
1266
1267
1268
1269
1270
 * \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)``.
1271
1272
 * \param handle Handle of booster
 * \param data Pointer to the data space
1273
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1274
1275
1276
1277
 * \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
1278
1279
1280
1281
 *   - ``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)
1282
 * \param start_iteration Start index of the iteration to predict
1283
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
1284
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1285
1286
1287
 * \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
1288
 */
1289
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle,
1290
1291
1292
1293
1294
1295
                                                const void* data,
                                                int data_type,
                                                int32_t nrow,
                                                int32_t ncol,
                                                int is_row_major,
                                                int predict_type,
1296
                                                int start_iteration,
1297
                                                int num_iteration,
1298
                                                const char* parameter,
1299
1300
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
1301

1302
/*!
1303
 * \brief Make prediction for a new dataset. This method re-uses the internal predictor structure
1304
 *        from previous calls and is optimized for single row invocation.
1305
1306
1307
1308
1309
 * \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)``.
1310
1311
 * \param handle Handle of booster
 * \param data Pointer to the data space
1312
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1313
 * \param ncol Number columns
1314
 * \param is_row_major 1 for row-major, 0 for column-major
1315
 * \param predict_type What should be predicted
1316
1317
1318
1319
 *   - ``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)
1320
 * \param start_iteration Start index of the iteration to predict
1321
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
1322
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1323
1324
1325
 * \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
1326
 */
1327
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRow(BoosterHandle handle,
1328
1329
1330
1331
1332
                                                         const void* data,
                                                         int data_type,
                                                         int ncol,
                                                         int is_row_major,
                                                         int predict_type,
1333
                                                         int start_iteration,
1334
1335
1336
1337
                                                         int num_iteration,
                                                         const char* parameter,
                                                         int64_t* out_len,
                                                         double* out_result);
1338

1339
1340
1341
1342
1343
1344
/*!
 * \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
1345
1346
1347
1348
1349
 * \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)
1350
 * \param start_iteration Start index of the iteration to predict
1351
 * \param num_iteration Number of iterations for prediction, <= 0 means no limit
1352
1353
1354
1355
1356
1357
1358
 * \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,
1359
                                                                 const int predict_type,
1360
                                                                 const int start_iteration,
1361
1362
1363
                                                                 const int num_iteration,
                                                                 const int data_type,
                                                                 const int32_t ncol,
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
                                                                 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);

1392
1393
/*!
 * \brief Make prediction for a new dataset presented in a form of array of pointers to rows.
1394
1395
1396
1397
1398
 * \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)``.
1399
1400
 * \param handle Handle of booster
 * \param data Pointer to the data space
1401
 * \param data_type Type of ``data`` pointer, can be ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``
1402
1403
1404
 * \param nrow Number of rows
 * \param ncol Number columns
 * \param predict_type What should be predicted
1405
1406
1407
1408
 *   - ``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)
1409
 * \param start_iteration Start index of the iteration to predict
1410
 * \param num_iteration Number of iteration for prediction, <= 0 means no limit
1411
 * \param parameter Other parameters for prediction, e.g. early stopping for prediction
1412
1413
1414
 * \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
1415
 */
1416
1417
1418
1419
1420
1421
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMats(BoosterHandle handle,
                                                 const void** data,
                                                 int data_type,
                                                 int32_t nrow,
                                                 int32_t ncol,
                                                 int predict_type,
1422
                                                 int start_iteration,
1423
1424
1425
1426
                                                 int num_iteration,
                                                 const char* parameter,
                                                 int64_t* out_len,
                                                 double* out_result);
1427

1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
/*!
 * \brief Make prediction for a new dataset.
 * \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 handle Handle of booster
 * \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 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)
 * \param start_iteration Start index of the iteration to predict
 * \param num_iteration Number of iteration 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
 */
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForArrow(BoosterHandle handle,
                                                  int64_t n_chunks,
                                                  const ArrowArray* chunks,
                                                  const ArrowSchema* schema,
                                                  int predict_type,
                                                  int start_iteration,
                                                  int num_iteration,
                                                  const char* parameter,
                                                  int64_t* out_len,
                                                  double* out_result);

Guolin Ke's avatar
Guolin Ke committed
1462
/*!
1463
1464
1465
1466
 * \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
1467
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1468
 * \param filename The name of the file
1469
 * \return 0 when succeed, -1 when failure happens
1470
 */
1471
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle,
1472
                                            int start_iteration,
1473
                                            int num_iteration,
1474
                                            int feature_importance_type,
1475
                                            const char* filename);
Guolin Ke's avatar
Guolin Ke committed
1476

1477
/*!
1478
1479
1480
1481
 * \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
1482
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1483
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
1484
1485
1486
 * \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
1487
 */
1488
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle,
1489
                                                    int start_iteration,
1490
                                                    int num_iteration,
1491
                                                    int feature_importance_type,
1492
1493
                                                    int64_t buffer_len,
                                                    int64_t* out_len,
1494
                                                    char* out_str);
1495

wxchan's avatar
wxchan committed
1496
/*!
1497
1498
1499
 * \brief Dump model to JSON.
 * \param handle Handle of booster
 * \param start_iteration Start index of the iteration that should be dumped
1500
 * \param num_iteration Index of the iteration that should be dumped, <= 0 means dump all
1501
 * \param feature_importance_type Type of feature importance, can be ``C_API_FEATURE_IMPORTANCE_SPLIT`` or ``C_API_FEATURE_IMPORTANCE_GAIN``
1502
 * \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer
1503
1504
1505
 * \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
1506
 */
1507
LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle,
1508
                                            int start_iteration,
1509
                                            int num_iteration,
1510
                                            int feature_importance_type,
1511
1512
                                            int64_t buffer_len,
                                            int64_t* out_len,
1513
                                            char* out_str);
1514

Guolin Ke's avatar
Guolin Ke committed
1515
/*!
1516
1517
1518
1519
1520
1521
 * \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
1522
 */
1523
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle,
1524
1525
1526
                                               int tree_idx,
                                               int leaf_idx,
                                               double* out_val);
Guolin Ke's avatar
Guolin Ke committed
1527
1528

/*!
1529
1530
1531
1532
1533
1534
 * \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
1535
 */
1536
LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle,
1537
1538
1539
                                               int tree_idx,
                                               int leaf_idx,
                                               double val);
1540

1541
/*!
1542
1543
1544
1545
 * \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:
1546
1547
 *   - ``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
1548
1549
 * \param[out] out_results Result array with feature importance
 * \return 0 when succeed, -1 when failure happens
1550
 */
1551
1552
1553
1554
1555
LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle,
                                                    int num_iteration,
                                                    int importance_type,
                                                    double* out_results);

1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
/*!
 * \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);

1574
/*!
1575
1576
1577
1578
1579
1580
 * \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
1581
 */
1582
1583
1584
1585
1586
1587
LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines,
                                       int local_listen_port,
                                       int listen_time_out,
                                       int num_machines);

/*!
1588
1589
 * \brief Finalize the network.
 * \return 0 when succeed, -1 when failure happens
1590
 */
1591
1592
LIGHTGBM_C_EXPORT int LGBM_NetworkFree();

1593
1594
1595
1596
1597
1598
1599
/*!
 * \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
1600
1601
1602
 */
LIGHTGBM_C_EXPORT int LGBM_NetworkInitWithFunctions(int num_machines,
                                                    int rank,
1603
                                                    void* reduce_scatter_ext_fun,
1604
                                                    void* allgather_ext_fun);
1605

1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
/*!
 * \brief Set maximum number of threads used by LightGBM routines in this process.
 * \param num_threads maximum number of threads used by LightGBM. -1 means defaulting to omp_get_num_threads().
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_SetMaxThreads(int num_threads);

/*!
 * \brief Get current maximum number of threads used by LightGBM routines in this process.
 * \param[out] out current maximum number of threads used by LightGBM. -1 means defaulting to omp_get_num_threads().
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_GetMaxThreads(int* out);

1620
#if !defined(__cplusplus) && (!defined(__STDC__) || (__STDC_VERSION__ < 199901L))
1621
1622
/*! \brief Inline specifier no-op in C using standards before C99. */
#define INLINE_FUNCTION
1623
#else
1624
1625
/*! \brief Inline specifier. */
#define INLINE_FUNCTION inline
1626
1627
1628
#endif

#if !defined(__cplusplus) && (!defined(__STDC__) || (__STDC_VERSION__ < 201112L))
1629
1630
/*! \brief Thread local specifier no-op in C using standards before C11. */
#define THREAD_LOCAL
1631
#elif !defined(__cplusplus)
1632
1633
/*! \brief Thread local specifier. */
#define THREAD_LOCAL _Thread_local
1634
#elif defined(_MSC_VER)
1635
1636
/*! \brief Thread local specifier. */
#define THREAD_LOCAL __declspec(thread)
Guolin Ke's avatar
Guolin Ke committed
1637
#else
1638
1639
/*! \brief Thread local specifier. */
#define THREAD_LOCAL thread_local
Guolin Ke's avatar
Guolin Ke committed
1640
#endif
1641
1642
1643
1644
1645

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

1648
1649
1650
#ifdef _MSC_VER
  #pragma warning(disable : 4996)
#endif
1651
1652
/*!
 * \brief Set string message of the last error.
1653
1654
 * \note
 * This will call unsafe ``sprintf`` when compiled using C standards before C99.
1655
1656
 * \param msg Error message
 */
1657
INLINE_FUNCTION void LGBM_SetLastError(const char* msg) {
1658
1659
1660
#if !defined(__cplusplus) && (!defined(__STDC__) || (__STDC_VERSION__ < 199901L))
  sprintf(LastErrorMsg(), "%s", msg);  /* NOLINT(runtime/printf) */
#else
1661
1662
  const int err_buf_len = 512;
  snprintf(LastErrorMsg(), err_buf_len, "%s", msg);
1663
#endif
1664
1665
}

1666
#endif  /* LIGHTGBM_INCLUDE_LIGHTGBM_C_API_H_ */