Skip to content

GitLab

Commit 19de2be0 authored by nabokovas's avatar nabokovas Committed by Nikita Titov
Browse files

[ci][docs] refine C API docs (#2076) 

* [ci] for autogenerating docs

* resolved comments

* resolved comments 2

* update to 36c89134
parent fc789e04
Hide whitespace changes
Inline Side-by-side
Showing with 569 additions and 476 deletions
include/LightGBM/c_api.h
View file @ 19de2be0
...@@ -33,22 +33,23 @@ typedef void* BoosterHandle; ...@@ -33,22 +33,23 @@ typedef void* BoosterHandle;
#define C_API_PREDICT_CONTRIB (3) #define C_API_PREDICT_CONTRIB (3)
/*! /*!
* \brief get string message of the last error * \fn LGBM_GetLastError
* all function in this file will return 0 when succeed * \headerfile <LightGBM/export.h>
* and -1 when an error occured, * \brief Get string message of the last error.
* \return const char* error inforomation * \return error information
*/ */
LIGHTGBM_C_EXPORT const char* LGBM_GetLastError(); LIGHTGBM_C_EXPORT const char* LGBM_GetLastError();
// --- start Dataset interface // --- start Dataset interface
/*! /*!
* \brief load data set from file like the command_line LightGBM do * \fn LGBM_DatasetCreateFromFile
* \param filename the name of the file * \brief Load dataset from file (like LightGBM CLI version does).
* \param parameters additional parameters * \param filename The name of the file
* \param reference used to align bin mapper with other dataset, nullptr means don't used * \param parameters Additional parameters
* \param out a loaded dataset * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
* \return 0 when succeed, -1 when failure happens * \param[out] out A loaded dataset
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename, LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename,
const char* parameters, const char* parameters,
...@@ -56,16 +57,16 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename, ...@@ -56,16 +57,16 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief create a empty dataset by sampling data. * \fn LGBM_DatasetCreateFromSampledColumn
* \param sample_data sampled data, grouped by the column. * \brief Create an empty dataset by sampling data.
* \param sample_indices indices of sampled data. * \param sample_indices Indices of sampled data
* \param ncol number columns * \param ncol Number of columns
* \param num_per_col Size of each sampling column * \param num_per_col Size of each sampling column
* \param num_sample_row Number of sampled rows * \param num_sample_row Number of sampled rows
* \param num_total_row number of total rows * \param num_total_row Number of total rows
* \param parameters additional parameters * \param parameters Additional parameters
* \param out created dataset * \param[out] out Created dataset
* \return 0 when succeed, -1 when failure happens * \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledColumn(double** sample_data, LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledColumn(double** sample_data,
int** sample_indices, int** sample_indices,
...@@ -77,25 +78,27 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledColumn(double** sample_data, ...@@ -77,25 +78,27 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledColumn(double** sample_data,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief create a empty dataset by reference Dataset * \fn LGBM_DatasetCreateByReference
* \param reference used to align bin mapper * \brief Create an empty dataset by reference Dataset.
* \param num_total_row number of total rows * \param reference Used to align bin mapper with other dataset
* \param out created dataset * \param num_total_row Number of total rows
* \return 0 when succeed, -1 when failure happens * \param[out] out Created dataset
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateByReference(const DatasetHandle reference, LIGHTGBM_C_EXPORT int LGBM_DatasetCreateByReference(const DatasetHandle reference,
int64_t num_total_row, int64_t num_total_row,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief push data to existing dataset, if nrow + start_row == num_total_row, will call dataset->FinishLoad * \fn LGBM_DatasetPushRows
* \param dataset handle of dataset * \brief Push data to existing dataset, if nrow + start_row == num_total_row, will call dataset->FinishLoad.
* \param data pointer to the data space * \param dataset Handle of dataset
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * \param data Pointer to the data space
* \param nrow number of rows * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64)
* \param ncol number columns * \param nrow Number of rows
* \param start_row row start index * \param ncol Number of columns
* \return 0 when succeed, -1 when failure happens * \param start_row Row start index
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset, LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset,
const void* data, const void* data,
...@@ -105,18 +108,19 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset, ...@@ -105,18 +108,19 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset,
int32_t start_row); int32_t start_row);
/*! /*!
* \brief push data to existing dataset, if nrow + start_row == num_total_row, will call dataset->FinishLoad * \fn LGBM_DatasetPushRowsByCSR
* \param dataset handle of dataset * \brief Push data to existing dataset, if nrow + start_row == num_total_row, will call dataset->FinishLoad.
* \param indptr pointer to row headers * \param dataset Handle of dataset
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64 * \param indptr Pointer to row headers
* \param indices findex * \param indptr_type Type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
* \param data fvalue * \param indices Pointer to column indices
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * \param data Pointer to the data space
* \param nindptr number of rows in the matrix + 1 * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nelem number of nonzero elements in the matrix * \param nindptr Number of rows in the matrix + 1
* \param num_col number of columns * \param nelem Number of nonzero elements in the matrix
* \param start_row row start index * \param num_col Number of columns
* \return 0 when succeed, -1 when failure happens * \param start_row Row start index
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset, LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset,
const void* indptr, const void* indptr,
...@@ -130,19 +134,20 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset, ...@@ -130,19 +134,20 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset,
int64_t start_row); int64_t start_row);
/*! /*!
* \brief create a dataset from CSR format * \fn LGBM_DatasetCreateFromCSR
* \param indptr pointer to row headers * \brief Create a dataset from CSR format.
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64 * \param indptr Pointer to row headers
* \param indices findex * \param indptr_type Type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
* \param data fvalue * \param indices Pointer to column indices
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * \param data Pointer to the data space
* \param nindptr number of rows in the matrix + 1 * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nelem number of nonzero elements in the matrix * \param nindptr Number of rows in the matrix + 1
* \param num_col number of columns * \param nelem Number of nonzero elements in the matrix
* \param parameters additional parameters * \param num_col Number of columns
* \param reference used to align bin mapper with other dataset, nullptr means don't used * \param parameters Additional parameters
* \param out created dataset * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
* \return 0 when succeed, -1 when failure happens * \param[out] out Created dataset
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr, LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr,
int indptr_type, int indptr_type,
...@@ -156,16 +161,17 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr, ...@@ -156,16 +161,17 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr,
const DatasetHandle reference, const DatasetHandle reference,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief create a dataset from CSR format through callbacks * \fn LGBM_DatasetCreateFromCSRFunc
* \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 * \brief Create a dataset from CSR format through callbacks.
* \param num_rows number of rows * \param get_row_funptr Pointer to std::function<void(int idx, std::vector<std::pair<int, double>>& ret)
* \param num_col number of columns * (called for every row and expected to clear and fill ret)
* \param parameters additional parameters * \param num_rows Number of rows
* \param reference used to align bin mapper with other dataset, nullptr means don't used * \param num_col Number of columns
* \param out created dataset * \param parameters Additional parameters
* \return 0 when succeed, -1 when failure happens * \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_DatasetCreateFromCSRFunc(void* get_row_funptr, LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSRFunc(void* get_row_funptr,
int num_rows, int num_rows,
...@@ -175,20 +181,22 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSRFunc(void* get_row_funptr, ...@@ -175,20 +181,22 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSRFunc(void* get_row_funptr,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief create a dataset from CSC format * \fn LGBM_DatasetCreateFromCSC
* \param col_ptr pointer to col headers * \brief Create a dataset from CSC format.
* \param col_ptr_type type of col_ptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64 * \param col_ptr Pointer to column headers
* \param indices findex * \param col_ptr_type Type of col_ptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
* \param data fvalue * \param indices Pointer to row indices
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * \param data Pointer to the data space
* \param ncol_ptr number of cols in the matrix + 1 * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nelem number of nonzero elements in the matrix * \param ncol_ptr Number of columns in the matrix + 1
* \param num_row number of rows * \param nelem Number of nonzero elements in the matrix
* \param parameters additional parameters * \param num_row Number of rows
* \param reference used to align bin mapper with other dataset, nullptr means don't used * \param parameters Additional parameters
* \param out created dataset * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
* \return 0 when succeed, -1 when failure happens * \param[out] out Created dataset
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr, LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr,
int col_ptr_type, int col_ptr_type,
...@@ -203,16 +211,17 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr, ...@@ -203,16 +211,17 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief create dataset from dense matrix * \fn LGBM_DatasetCreateFromMat
* \param data pointer to the data space * \brief Create dataset from dense matrix.
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * \param data Pointer to the data space
* \param nrow number of rows * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param ncol number columns * \param nrow Number of rows
* \param is_row_major 1 for row major, 0 for column major * \param ncol Number of columns
* \param parameters additional parameters * \param is_row_major 1 for row-major, 0 for column-major
* \param reference used to align bin mapper with other dataset, nullptr means don't used * \param parameters Additional parameters
* \param out created dataset * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
* \return 0 when succeed, -1 when failure happens * \param[out] out Created dataset
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data, LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data,
int data_type, int data_type,
...@@ -224,17 +233,18 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data, ...@@ -224,17 +233,18 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief create dataset from array of dense matrices * \fn LGBM_DatasetCreateFromMats
* \param nmat number of matrices * \brief Create dataset from array of dense matrices.
* \param data pointer to the data space * \param nmat Number of dense matrices
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * \param data Pointer to the data space
* \param nrow number of rows * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param ncol number columns * \param nrow Number of rows
* \param is_row_major 1 for row major, 0 for column major * \param ncol Number of columns
* \param parameters additional parameters * \param is_row_major 1 for row-major, 0 for column-major
* \param reference used to align bin mapper with other dataset, nullptr means don't used * \param parameters Additional parameters
* \param out created dataset * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
* \return 0 when succeed, -1 when failure happens * \param[out] out Created dataset
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMats(int32_t nmat, LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMats(int32_t nmat,
const void** data, const void** data,
...@@ -247,13 +257,14 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMats(int32_t nmat, ...@@ -247,13 +257,14 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMats(int32_t nmat,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief Create subset of a data * \fn LGBM_DatasetGetSubset
* \param handle handle of full dataset * \brief Create subset of a data.
* \param used_row_indices Indices used in subset * \param handle Handle of full dataset
* \param num_used_row_indices len of used_row_indices * \param used_row_indices Indices used in subset
* \param parameters additional parameters * \param num_used_row_indices Len of used_row_indices
* \param out subset of data * \param parameters Additional parameters
* \return 0 when succeed, -1 when failure happens * \param[out] out Subset of data
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetGetSubset(const DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetGetSubset(const DatasetHandle handle,
const int32_t* used_row_indices, const int32_t* used_row_indices,
...@@ -262,11 +273,12 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetGetSubset(const DatasetHandle handle, ...@@ -262,11 +273,12 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetGetSubset(const DatasetHandle handle,
DatasetHandle* out); DatasetHandle* out);
/*! /*!
* \brief save feature names to Dataset * \fn LGBM_DatasetSetFeatureNames
* \param handle handle * \brief Save feature names to dataset.
* \param feature_names feature names * \param handle Handle of dataset
* \param num_feature_names number of feature names * \param feature_names Feature names
* \return 0 when succeed, -1 when failure happens * \param num_feature_names Number of feature names
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(DatasetHandle handle,
const char** feature_names, const char** feature_names,
...@@ -274,11 +286,12 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(DatasetHandle handle, ...@@ -274,11 +286,12 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(DatasetHandle handle,
/*! /*!
* \brief get feature names of Dataset * \fn LGBM_DatasetGetFeatureNames
* \param handle handle * \brief Get feature names of dataset.
* \param feature_names feature names, should pre-allocate memory * \param handle Handle of dataset
* \param num_feature_names number of feature names * \param[out] feature_names Feature names, should pre-allocate memory
* \return 0 when succeed, -1 when failure happens * \param[out] num_feature_names Number of feature names
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(DatasetHandle handle,
char** feature_names, char** feature_names,
...@@ -286,39 +299,46 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(DatasetHandle handle, ...@@ -286,39 +299,46 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(DatasetHandle handle,
/*! /*!
* \brief free space for dataset * \fn LGBM_DatasetFree
* \return 0 when succeed, -1 when failure happens * \brief Free space for dataset.
* \param handle Handle of dataset to be freed
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetFree(DatasetHandle handle); LIGHTGBM_C_EXPORT int LGBM_DatasetFree(DatasetHandle handle);
/*! /*!
* \brief save dataset to binary file * \fn LGBM_DatasetSaveBinary
* \param handle a instance of dataset * \brief Save dataset to binary file.
* \param filename file name * \param handle Handle of dataset
* \return 0 when succeed, -1 when failure happens * \param filename File name
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetSaveBinary(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetSaveBinary(DatasetHandle handle,
const char* filename); const char* filename);
/*! /*!
* \brief save dataset to text file, intended for debugging use only * \fn LGBM_DatasetDumpText
* \param handle a instance of dataset * \brief Save dataset to text file, intended for debugging use only.
* \param filename file name * \param handle Handle of dataset
* \return 0 when succeed, -1 when failure happens * \param filename File name
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetDumpText(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetDumpText(DatasetHandle handle,
const char* filename); const char* filename);
/*! /*!
* \brief set vector to a content in info * \fn LGBM_DatasetSetField
* Note: group and group only work for C_API_DTYPE_INT32 * \brief Set vector to a content in info.
* label and weight only work for C_API_DTYPE_FLOAT32 * Note: monotone_constraints only works for C_API_DTYPE_INT8,
* \param handle a instance of dataset * group only works for C_API_DTYPE_INT32,
* \param field_name field name, can be label, weight, group, group_id * label and weight only work for C_API_DTYPE_FLOAT32,
* \param field_data pointer to vector * init_score and feature_penalty only work for C_API_DTYPE_FLOAT64.
* \param num_element number of element in field_data * \param handle Handle of dataset
* \param type C_API_DTYPE_FLOAT32 or C_API_DTYPE_INT32 * \param field_name Field name, can be label, weight, init_score, group, feature_penalty, monotone_constraints
* \return 0 when succeed, -1 when failure happens * \param field_data Pointer to data vector
* \param num_element Number of elements in field_data
* \param type Type of data pointer, can be C_API_DTYPE_INT8, C_API_DTYPE_INT32, C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle,
const char* field_name, const char* field_name,
...@@ -327,13 +347,14 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle, ...@@ -327,13 +347,14 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle,
int type); int type);
/*! /*!
* \brief get info vector from dataset * \fn LGBM_DatasetGetField
* \param handle a instance of data matrix * \brief Get info vector from dataset.
* \param field_name field name * \param handle Handle of dataset
* \param out_len used to set result length * \param field_name Field name
* \param out_ptr pointer to the result * \param[out] out_len Used to set result length
* \param out_type C_API_DTYPE_FLOAT32 or C_API_DTYPE_INT32 * \param[out] out_ptr Pointer to the result
* \return 0 when succeed, -1 when failure happens * \param[out] out_type Type of result pointer, can be C_API_DTYPE_INT8, C_API_DTYPE_INT32, C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle,
const char* field_name, const char* field_name,
...@@ -341,38 +362,41 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle, ...@@ -341,38 +362,41 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle,
const void** out_ptr, const void** out_ptr,
int* out_type); int* out_type);
/*! /*!
* \brief Update parameters for a Dataset * \fn LGBM_DatasetUpdateParam
* \param handle a instance of data matrix * \brief Update parameters for a dataset.
* \param parameters parameters * \param handle Handle of dataset
* \param parameters Parameters
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetUpdateParam(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetUpdateParam(DatasetHandle handle,
const char* parameters); const char* parameters);
/*! /*!
* \brief get number of data. * \fn LGBM_DatasetGetNumData
* \param handle the handle to the dataset * \brief Get number of data points.
* \param out The address to hold number of data * \param handle Handle of dataset
* \return 0 when succeed, -1 when failure happens * \param[out] out The address to hold number of data points
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle,
int* out); int* out);
/*! /*!
* \brief get number of features * \fn LGBM_DatasetGetNumFeature
* \param handle the handle to the dataset * \brief Get number of features.
* \param out The output of number of features * \param handle Handle of dataset
* \return 0 when succeed, -1 when failure happens * \param[out] out The address to hold number of features
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle, LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle,
int* out); int* out);
/*! /*!
* \brief Add features from source to target, then free source * \fn LGBM_DatasetAddFeaturesFrom
* \param target The handle of the dataset to add features to * \brief Add features from source to target.
* \param source The handle of the dataset to take features from * \param target The handle of the dataset to add features to
* \return 0 when succeed, -1 when failure happens * \param source The handle of the dataset to take features from
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target, LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target,
DatasetHandle source); DatasetHandle source);
...@@ -380,10 +404,11 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target, ...@@ -380,10 +404,11 @@ LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target,
// --- start Booster interfaces // --- start Booster interfaces
/*! /*!
* \brief create an new boosting learner * \fn LGBM_BoosterCreate
* \param train_data training data set * \brief Create a new boosting learner.
* \param parameters format: 'key1=value1 key2=value2' * \param train_data Training dataset
* \param out handle of created Booster * \param parameters Parameters in format: 'key1=value1 key2=value2'
* \param[out] out Handle of created booster
* \return 0 when succeed, -1 when failure happens * \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data, LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data,
...@@ -391,102 +416,117 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data, ...@@ -391,102 +416,117 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data,
BoosterHandle* out); BoosterHandle* out);
/*! /*!
* \brief load an existing boosting from model file * \fn LGBM_BoosterCreateFromModelfile
* \param filename filename of model * \brief Load an existing booster from model file.
* \param out_num_iterations number of iterations of this booster * \param filename Filename of model
* \param out handle of created Booster * \param[out] out_num_iterations Number of iterations of this booster
* \return 0 when succeed, -1 when failure happens * \param[out] out Handle of created booster
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(const char* filename, LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(const char* filename,
int* out_num_iterations, int* out_num_iterations,
BoosterHandle* out); BoosterHandle* out);
/*! /*!
* \brief load an existing boosting from string * \fn LGBM_BoosterLoadModelFromString
* \param model_str model string * \brief Load an existing booster from string.
* \param out_num_iterations number of iterations of this booster * \param model_str Model string
* \param out handle of created Booster * \param[out] out_num_iterations Number of iterations of this booster
* \return 0 when succeed, -1 when failure happens * \param[out] out Handle of created booster
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(const char* model_str, LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(const char* model_str,
int* out_num_iterations, int* out_num_iterations,
BoosterHandle* out); BoosterHandle* out);
/*! /*!
* \brief free obj in handle * \fn LGBM_BoosterFree
* \param handle handle to be freed * \brief Free space for booster.
* \return 0 when succeed, -1 when failure happens * \param handle Handle of booster to be freed
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle); LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle);
/*! /*!
* \brief Shuffle Models * \fn LGBM_BoosterShuffleModels
* \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
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterShuffleModels(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterShuffleModels(BoosterHandle handle,
int start_iter, int start_iter,
int end_iter); int end_iter);
/*! /*!
* \brief Merge model in two booster to first handle * \fn LGBM_BoosterMerge
* \param handle handle, will merge other handle to this * \brief Merge model from other_handle into handle.
* \param other_handle * \param handle Handle of booster, will merge another booster into this one
* \return 0 when succeed, -1 when failure happens * \param other_handle Other handle of booster
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle,
BoosterHandle other_handle); BoosterHandle other_handle);
/*! /*!
* \brief Add new validation to booster * \fn LGBM_BoosterAddValidData
* \param handle handle * \brief Add new validation data to booster.
* \param valid_data validation data set * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param valid_data Validation dataset
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle,
const DatasetHandle valid_data); const DatasetHandle valid_data);
/*! /*!
* \brief Reset training data for booster * \fn LGBM_BoosterResetTrainingData
* \param handle handle * \brief Reset training data for booster.
* \param train_data training data set * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param train_data Training dataset
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle,
const DatasetHandle train_data); const DatasetHandle train_data);
/*! /*!
* \brief Reset config for current booster * \fn LGBM_BoosterResetParameter
* \param handle handle * \brief Reset config for booster.
* \param parameters format: 'key1=value1 key2=value2' * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param parameters Parameters in format: 'key1=value1 key2=value2'
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle,
const char* parameters); const char* parameters);
/*! /*!
* \brief Get number of class * \fn LGBM_BoosterGetNumClasses
* \param handle handle * \brief Get number of classes.
* \param out_len number of class * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param[out] out_len Number of classes
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle,
int* out_len); int* out_len);
/*! /*!
* \brief update the model in one round * \fn LGBM_BoosterUpdateOneIter
* \param handle handle * \brief Update the model for one iteration.
* \param is_finished 1 means finised(cannot split any more) * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle,
int* is_finished); int* is_finished);
/*! /*!
* \brief Refit the tree model using the new data (online learning) * \fn LGBM_BoosterRefit
* \param handle handle * \brief Refit the tree model using the new data (online learning).
* \param leaf_preds * \param handle Handle of booster
* \param nrow number of rows of leaf_preds * \param leaf_preds Pointer to predicted leaf indices
* \param ncol number of columns of leaf_preds * \param nrow Number of rows of leaf_preds
* \return 0 when succeed, -1 when failure happens * \param ncol Number of columns of leaf_preds
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterRefit(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterRefit(BoosterHandle handle,
const int32_t* leaf_preds, const int32_t* leaf_preds,
...@@ -494,13 +534,14 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterRefit(BoosterHandle handle, ...@@ -494,13 +534,14 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterRefit(BoosterHandle handle,
int32_t ncol); int32_t ncol);
/*! /*!
* \brief update the model, by directly specify gradient and second order gradient, * \fn LGBM_BoosterUpdateOneIterCustom
* this can be used to support customized loss function * \brief Update the model by specifying gradient and Hessian directly
* \param handle handle * (this can be used to support customized loss functions).
* \param grad gradient statistics * \param handle Handle of booster
* \param hess second order gradient statistics * \param grad The first order derivative (gradient) statistics
* \param is_finished 1 means finised(cannot split any more) * \param hess The second order derivative (Hessian) statistics
* \return 0 when succeed, -1 when failure happens * \param param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
const float* grad, const float* grad,
...@@ -508,88 +549,97 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle, ...@@ -508,88 +549,97 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
int* is_finished); int* is_finished);
/*! /*!
* \brief Rollback one iteration * \fn LGBM_BoosterRollbackOneIter
* \param handle handle * \brief Rollback one iteration.
* \return 0 when succeed, -1 when failure happens * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle); LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle);
/*! /*!
* \brief Get iteration of current boosting rounds * \fn LGBM_BoosterGetCurrentIteration
* \param handle handle * \brief Get index of the current boosting iteration.
* \param out_iteration iteration of boosting rounds * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param[out] out_iteration Index of the current boosting iteration
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle,
int* out_iteration); int* out_iteration);
/*! /*!
* \brief Get number of tree per iteration * \fn LGBM_BoosterNumModelPerIteration
* \param handle handle * \brief Get number of trees per iteration.
* \param out_tree_per_iteration number of tree per iteration * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param[out] out_tree_per_iteration Number of trees per iteration
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterNumModelPerIteration(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterNumModelPerIteration(BoosterHandle handle,
int* out_tree_per_iteration); int* out_tree_per_iteration);
/*! /*!
* \brief Get number of weak sub-models * \fn LGBM_BoosterNumberOfTotalModel
* \param handle handle * \brief Get number of weak sub-models.
* \param out_models number of weak sub-models * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param[out] out_models Number of weak sub-models
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterNumberOfTotalModel(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterNumberOfTotalModel(BoosterHandle handle,
int* out_models); int* out_models);
/*! /*!
* \brief Get number of eval * \fn LGBM_BoosterGetEvalCounts
* \param handle handle * \brief Get number of evaluation datasets.
* \param out_len total number of eval results * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param[out] out_len Total number of evaluation datasets
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle,
int* out_len); int* out_len);
/*! /*!
* \brief Get name of eval * \fn LGBM_BoosterGetEvalNames
* \param handle handle * \brief Get names of evaluation datasets.
* \param out_len total number of eval results * \param handle Handle of booster
* \param out_strs names of eval result, need to pre-allocate memory before call this * \param[out] out_len Total number of evaluation datasets
* \return 0 when succeed, -1 when failure happens * \param[out] out_strs Names of evaluation datasets, should pre-allocate memory
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle,
int* out_len, int* out_len,
char** out_strs); char** out_strs);
/*! /*!
* \brief Get name of features * \fn LGBM_BoosterGetFeatureNames
* \param handle handle * \brief Get names of features.
* \param out_len total number of features * \param handle Handle of booster
* \param out_strs names of features, need to pre-allocate memory before call this * \param[out] out_len Total number of features
* \return 0 when succeed, -1 when failure happens * \param[out] out_strs Names of features, should pre-allocate memory
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle,
int* out_len, int* out_len,
char** out_strs); char** out_strs);
/*! /*!
* \brief Get number of features * \fn LGBM_BoosterGetNumFeature
* \param handle handle * \brief Get number of features.
* \param out_len total number of features * \param handle Handle of booster
* \return 0 when succeed, -1 when failure happens * \param[out] out_len Total number of features
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle,
int* out_len); int* out_len);
/*! /*!
* \brief get evaluation for training data and validation data * \fn LGBM_BoosterGetEval
Note: 1. you should call LGBM_BoosterGetEvalNames first to get the name of evaluation results * \brief Get evaluation for training data and validation data.
2. should pre-allocate memory for out_results, you can get its length by LGBM_BoosterGetEvalCounts * Note: 1. You should call LGBM_BoosterGetEvalNames first to get the names of evaluation datasets.
* \param handle handle * 2. You should pre-allocate memory for out_results, you can get its length by LGBM_BoosterGetEvalCounts.
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ... * \param handle Handle of booster
* \param out_len len of output result * \param data_idx Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on
* \param out_results float arrary contains result * \param[out] out_len Length of output result
* \return 0 when succeed, -1 when failure happens * \param[out] out_result Array with evaluation results
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle,
int data_idx, int data_idx,
...@@ -597,27 +647,27 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle, ...@@ -597,27 +647,27 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle,
double* out_results); double* out_results);
/*! /*!
* \brief Get number of predict for inner dataset * \fn LGBM_BoosterGetNumPredict
this can be used to support customized eval function * \brief Get number of predictions for training data and validation data.
Note: should pre-allocate memory for out_result, its length is equal to num_class * num_data * This can be used to support customized evaluation functions.
* \param handle handle * \param handle Handle of booster
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ... * \param data_idx Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on
* \param out_len len of output result * \param[out] out_len Number of predictions
* \return 0 when succeed, -1 when failure happens * \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle,
int data_idx, int data_idx,
int64_t* out_len); int64_t* out_len);
/*! /*!
* \brief Get prediction for training data and validation data * \fn LGBM_BoosterGetPredict
this can be used to support customized eval function * \brief Get prediction for training data and validation data.
Note: should pre-allocate memory for out_result, its length is equal to num_class * num_data * Note: You should pre-allocate memory for out_result, its length is equal to num_class * num_data.
* \param handle handle * \param handle Handle of booster
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ... * \param data_idx Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on
* \param out_len len of output result * \param[out] out_len Length of output result
* \param out_result used to set a pointer to array, should allocate memory before call this function * \param[out] out_result Pointer to array with predictions
* \return 0 when succeed, -1 when failure happens * \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle,
int data_idx, int data_idx,
...@@ -625,18 +675,20 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle, ...@@ -625,18 +675,20 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle,
double* out_result); double* out_result);
/*! /*!
* \brief make prediction for file * \fn LGBM_BoosterPredictForFile
* \param handle handle * \brief Make prediction for file.
* \param data_filename filename of data file * \param handle Handle of booster
* \param data_has_header data file has header or not * \param data_filename Filename of file with data
* \param predict_type * \param data_has_header Whether file has header or not
* C_API_PREDICT_NORMAL: normal prediction, with transform (if needed) * \param predict_type What should be predicted
* C_API_PREDICT_RAW_SCORE: raw score * C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
* C_API_PREDICT_LEAF_INDEX: leaf index * C_API_PREDICT_RAW_SCORE: raw score
* \param num_iteration number of iteration for prediction, <= 0 means no limit * C_API_PREDICT_LEAF_INDEX: leaf index
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction. * C_API_PREDICT_CONTRIB: feature contributions (SHAP values)
* \param result_filename filename of result file * \param num_iteration Number of iterations for prediction, <= 0 means no limit
* \return 0 when succeed, -1 when failure happens * \param parameter Other parameters for prediction, e.g. early stopping for prediction.
* \param result_filename Filename of result file in which predictions will be written
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle,
const char* data_filename, const char* data_filename,
...@@ -647,16 +699,18 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle, ...@@ -647,16 +699,18 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle,
const char* result_filename); const char* result_filename);
/*! /*!
* \brief Get number of prediction * \fn LGBM_BoosterCalcNumPredict
* \param handle handle * \brief Get number of predictions.
* \param num_row * \param handle Handle of booster
* \param predict_type * \param num_row Number of rows
* C_API_PREDICT_NORMAL: normal prediction, with transform (if needed) * \param predict_type What should be predicted
* C_API_PREDICT_RAW_SCORE: raw score * C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
* C_API_PREDICT_LEAF_INDEX: leaf index * C_API_PREDICT_RAW_SCORE: raw score
* \param num_iteration number of iteration for prediction, <= 0 means no limit * C_API_PREDICT_LEAF_INDEX: leaf index
* \param out_len length of prediction * C_API_PREDICT_CONTRIB: feature contributions (SHAP values)
* \return 0 when succeed, -1 when failure happens * \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
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle,
int num_row, int num_row,
...@@ -665,28 +719,31 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle, ...@@ -665,28 +719,31 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle,
int64_t* out_len); int64_t* out_len);
/*! /*!
* \brief make prediction for an new data set * \fn LGBM_BoosterPredictForCSR
* Note: should pre-allocate memory for out_result, * \brief Make prediction for a new dataset in CSR format.
* for normal and raw score: its length is equal to num_class * num_data * Note: You should pre-allocate memory for out_result:
* for leaf index, its length is equal to num_class * num_data * num_iteration * for normal and raw score, its length is equal to num_class * num_data;
* \param handle handle * for leaf index, its length is equal to num_class * num_data * num_iteration;
* \param indptr pointer to row headers * for feature contributions, its length is equal to num_class * num_data * (num_feature + 1).
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64 * \param handle Handle of booster
* \param indices findex * \param indptr Pointer to row headers
* \param data fvalue * \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 * \param indices Pointer to column indices
* \param nindptr number of rows in the matrix + 1 * \param data Pointer to the data space
* \param nelem number of nonzero elements in the matrix * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param num_col number of columns; when it's set to 0, then guess from data * \param nindptr Number of rows in the matrix + 1
* \param predict_type * \param nelem Number of nonzero elements in the matrix
* C_API_PREDICT_NORMAL: normal prediction, with transform (if needed) * \param num_col Number of columns; when it's set to 0, then guess from data
* C_API_PREDICT_RAW_SCORE: raw score * \param predict_type What should be predicted
* C_API_PREDICT_LEAF_INDEX: leaf index * C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
* \param num_iteration number of iteration for prediction, <= 0 means no limit * C_API_PREDICT_RAW_SCORE: raw score
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction. * C_API_PREDICT_LEAF_INDEX: leaf index
* \param out_len len of output result * C_API_PREDICT_CONTRIB: feature contributions (SHAP values)
* \param out_result used to set a pointer to array, should allocate memory before call this function * \param num_iteration Number of iterations for prediction, <= 0 means no limit
* \return 0 when succeed, -1 when failure happens * \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_BoosterPredictForCSR(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle,
const void* indptr, const void* indptr,
...@@ -704,29 +761,32 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle, ...@@ -704,29 +761,32 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle,
double* out_result); double* out_result);
/*! /*!
* \brief make prediction for an new data set. This method re-uses the internal predictor structure * \fn LGBM_BoosterPredictForCSRSingleRow
* from previous calls and is optimized for single row invocation. * \brief Make prediction for a new dataset in CSR format. This method re-uses the internal predictor structure
* Note: should pre-allocate memory for out_result, * from previous calls and is optimized for single row invocation.
* for normal and raw score: its length is equal to num_class * num_data * Note: You should pre-allocate memory for out_result:
* for leaf index, its length is equal to num_class * num_data * num_iteration * for normal and raw score, its length is equal to num_class * num_data;
* \param handle handle * for leaf index, its length is equal to num_class * num_data * num_iteration;
* \param indptr pointer to row headers * for feature contributions, its length is equal to num_class * num_data * (num_feature + 1).
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64 * \param handle Handle of booster
* \param indices findex * \param indptr Pointer to row headers
* \param data fvalue * \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 * \param indices Pointer to column indices
* \param nindptr number of rows in the matrix + 1 * \param data Pointer to the data space
* \param nelem number of nonzero elements in the matrix * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param num_col number of columns; when it's set to 0, then guess from data * \param nindptr Number of rows in the matrix + 1
* \param predict_type * \param nelem Number of nonzero elements in the matrix
* C_API_PREDICT_NORMAL: normal prediction, with transform (if needed) * \param num_col Number of columns; when it's set to 0, then guess from data
* C_API_PREDICT_RAW_SCORE: raw score * \param predict_type What should be predicted
* C_API_PREDICT_LEAF_INDEX: leaf index * C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
* \param num_iteration number of iteration for prediction, <= 0 means no limit * C_API_PREDICT_RAW_SCORE: raw score
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction. * C_API_PREDICT_LEAF_INDEX: leaf index
* \param out_len len of output result * C_API_PREDICT_CONTRIB: feature contributions (SHAP values)
* \param out_result used to set a pointer to array, should allocate memory before call this function * \param num_iteration Number of iterations for prediction, <= 0 means no limit
* \return 0 when succeed, -1 when failure happens * \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_BoosterPredictForCSRSingleRow(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRow(BoosterHandle handle,
const void* indptr, const void* indptr,
...@@ -745,28 +805,31 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRow(BoosterHandle handle, ...@@ -745,28 +805,31 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRow(BoosterHandle handle,
/*! /*!
* \brief make prediction for an new data set * \fn LGBM_BoosterPredictForCSC
* Note: should pre-allocate memory for out_result, * \brief Make prediction for a new dataset in CSC format.
* for normal and raw score: its length is equal to num_class * num_data * Note: You should pre-allocate memory for out_result:
* for leaf index, its length is equal to num_class * num_data * num_iteration * for normal and raw score, its length is equal to num_class * num_data;
* \param handle handle * for leaf index, its length is equal to num_class * num_data * num_iteration;
* \param col_ptr pointer to col headers * for feature contributions, its length is equal to num_class * num_data * (num_feature + 1).
* \param col_ptr_type type of col_ptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64 * \param handle Handle of booster
* \param indices findex * \param col_ptr Pointer to column headers
* \param data fvalue * \param col_ptr_type Type of col_ptr, 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 * \param indices Pointer to row indices
* \param ncol_ptr number of cols in the matrix + 1 * \param data Pointer to the data space
* \param nelem number of nonzero elements in the matrix * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param num_row number of rows * \param ncol_ptr Number of columns in the matrix + 1
* \param predict_type * \param nelem Number of nonzero elements in the matrix
* C_API_PREDICT_NORMAL: normal prediction, with transform (if needed) * \param num_row Number of rows
* C_API_PREDICT_RAW_SCORE: raw score * \param predict_type What should be predicted
* C_API_PREDICT_LEAF_INDEX: leaf index * C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
* \param num_iteration number of iteration for prediction, <= 0 means no limit * C_API_PREDICT_RAW_SCORE: raw score
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction. * C_API_PREDICT_LEAF_INDEX: leaf index
* \param out_len len of output result * C_API_PREDICT_CONTRIB: feature contributions (SHAP values)
* \param out_result used to set a pointer to array, should allocate memory before call this function * \param num_iteration Number of iteration for prediction, <= 0 means no limit
* \return 0 when succeed, -1 when failure happens * \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_BoosterPredictForCSC(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle,
const void* col_ptr, const void* col_ptr,
...@@ -784,25 +847,28 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle, ...@@ -784,25 +847,28 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle,
double* out_result); double* out_result);
/*! /*!
* \brief make prediction for an new data set * \fn LGBM_BoosterPredictForMat
* Note: should pre-allocate memory for out_result, * \brief Make prediction for a new dataset.
* for normal and raw score: its length is equal to num_class * num_data * Note: You should pre-allocate memory for out_result:
* for leaf index, its length is equal to num_class * num_data * num_iteration * for normal and raw score, its length is equal to num_class * num_data;
* \param handle handle * for leaf index, its length is equal to num_class * num_data * num_iteration;
* \param data pointer to the data space * for feature contributions, its length is equal to num_class * num_data * (num_feature + 1).
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * \param handle Handle of booster
* \param nrow number of rows * \param data Pointer to the data space
* \param ncol number columns * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param is_row_major 1 for row major, 0 for column major * \param nrow Number of rows
* \param predict_type * \param ncol Number of columns
* C_API_PREDICT_NORMAL: normal prediction, with transform (if needed) * \param is_row_major 1 for row-major, 0 for column-major
* C_API_PREDICT_RAW_SCORE: raw score * \param predict_type What should be predicted
* C_API_PREDICT_LEAF_INDEX: leaf index * C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
* \param num_iteration number of iteration for prediction, <= 0 means no limit * C_API_PREDICT_RAW_SCORE: raw score
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction. * C_API_PREDICT_LEAF_INDEX: leaf index
* \param out_len len of output result * C_API_PREDICT_CONTRIB: feature contributions (SHAP values)
* \param out_result used to set a pointer to array, should allocate memory before call this function * \param num_iteration Number of iteration for prediction, <= 0 means no limit
* \return 0 when succeed, -1 when failure happens * \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_BoosterPredictForMat(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle,
const void* data, const void* data,
...@@ -817,55 +883,62 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle, ...@@ -817,55 +883,62 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle,
double* out_result); double* out_result);
/*! /*!
* \brief make prediction for an new data set. This method re-uses the internal predictor structure * \fn LGBM_BoosterPredictForMatSingleRow
* from previous calls and is optimized for single row invocation. * \brief Make prediction for an new dataset. This method re-uses the internal predictor structure
* Note: should pre-allocate memory for out_result, * from previous calls and is optimized for single row invocation.
* for normal and raw score: its length is equal to num_class * num_data * Note: You should pre-allocate memory for out_result:
* for leaf index, its length is equal to num_class * num_data * num_iteration * for normal and raw score, its length is equal to num_class * num_data;
* \param handle handle * for leaf index, its length is equal to num_class * num_data * num_iteration;
* \param data pointer to the data space * for feature contributions, its length is equal to num_class * num_data * (num_feature + 1).
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * \param handle Handle of booster
* \param ncol number columns * \param data Pointer to the data space
* \param is_row_major 1 for row major, 0 for column major * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param predict_type * \param ncol Number columns
* C_API_PREDICT_NORMAL: normal prediction, with transform (if needed) * \param is_row_major 1 for row major, 0 for column major
* C_API_PREDICT_RAW_SCORE: raw score * \param predict_type What should be predicted
* C_API_PREDICT_LEAF_INDEX: leaf index * C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
* \param num_iteration number of iteration for prediction, <= 0 means no limit * C_API_PREDICT_RAW_SCORE: raw score
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction. * C_API_PREDICT_LEAF_INDEX: leaf index
* \param out_len len of output result * C_API_PREDICT_CONTRIB: feature contributions (SHAP values)
* \param out_result used to set a pointer to array, should allocate memory before call this function * \param num_iteration Number of iteration for prediction, <= 0 means no limit
* \return 0 when succeed, -1 when failure happens * \param parameter Other parameters for prediction, e.g. early stopping for prediction.
*/LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRow(BoosterHandle handle, * \param[out] out_len Length of output result
const void* data, * \param[out] out_result Pointer to array with predictions
int data_type, * \return 0 when succeed, -1 when failure happens
int ncol, */
int is_row_major, LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRow(BoosterHandle handle,
int predict_type, const void* data,
int num_iteration, int data_type,
const char* parameter, int ncol,
int64_t* out_len, int is_row_major,
double* out_result); int predict_type,
int num_iteration,
/*! const char* parameter,
* \brief make prediction for an new data set int64_t* out_len,
* Note: should pre-allocate memory for out_result, double* out_result);
* for noraml and raw score: its length is equal to num_class * num_data
* for leaf index, its length is equal to num_class * num_data * num_iteration /*!
* \param handle handle * \fn LGBM_BoosterPredictForMats
* \param data pointer to the data space * \brief Make prediction for a new dataset presented in a form of array of pointers to rows.
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64 * Note: You should pre-allocate memory for out_result:
* \param nrow number of rows * for normal and raw score, its length is equal to num_class * num_data;
* \param ncol number columns * for leaf index, its length is equal to num_class * num_data * num_iteration;
* \param predict_type * for feature contributions, its length is equal to num_class * num_data * (num_feature + 1).
* C_API_PREDICT_NORMAL: normal prediction, with transform (if needed) * \param handle Handle of booster
* C_API_PREDICT_RAW_SCORE: raw score * \param data Pointer to the data space
* C_API_PREDICT_LEAF_INDEX: leaf index * \param data_type Type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param num_iteration number of iteration for prediction, <= 0 means no limit * \param nrow Number of rows
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction. * \param ncol Number columns
* \param out_len len of output result * \param predict_type What should be predicted
* \param out_result used to set a pointer to array, should allocate memory before call this function * C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
* \return 0 when succeed, -1 when failure happens * C_API_PREDICT_RAW_SCORE: raw score
* C_API_PREDICT_LEAF_INDEX: leaf index
* C_API_PREDICT_CONTRIB: feature contributions (SHAP values)
* \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_BoosterPredictForMats(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMats(BoosterHandle handle,
const void** data, const void** data,
...@@ -879,12 +952,13 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMats(BoosterHandle handle, ...@@ -879,12 +952,13 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMats(BoosterHandle handle,
double* out_result); double* out_result);
/*! /*!
* \brief save model into file * \fn LGBM_BoosterSaveModel
* \param handle handle * \brief Save model into file.
* \param start_iteration start iteration that should be saved * \param handle Handle of booster
* \param num_iteration, <= 0 means save all * \param start_iteration Start index of the iteration that should be saved
* \param filename file name * \param num_iteration Index of the iteration that should be saved, <= 0 means save all
* \return 0 when succeed, -1 when failure happens * \param filename File name
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle,
int start_iteration, int start_iteration,
...@@ -892,14 +966,15 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle, ...@@ -892,14 +966,15 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle,
const char* filename); const char* filename);
/*! /*!
* \brief save model to string * \fn LGBM_BoosterSaveModelToString
* \param handle handle * \brief Save model to string.
* \param start_iteration start iteration that should be saved * \param handle Handle of booster
* \param num_iteration, <= 0 means save all * \param start_iteration Start index of the iteration that should be saved
* \param buffer_len string buffer length, if buffer_len < out_len, re-allocate buffer * \param num_iteration Index of the iteration that should be saved, <= 0 means save all
* \param out_len actual output length * \param buffer_len String buffer length, if buffer_len < out_len, you should re-allocate buffer
* \param out_str string of model, need to pre-allocate memory before call this * \param[out] out_len Actual output length
* \return 0 when succeed, -1 when failure happens * \param[out] out_str String of model, should pre-allocate memory
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle,
int start_iteration, int start_iteration,
...@@ -909,14 +984,15 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle, ...@@ -909,14 +984,15 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle,
char* out_str); char* out_str);
/*! /*!
* \brief dump model to json * \fn LGBM_BoosterDumpModel
* \param handle handle * \brief Dump model to JSON.
* \param start_iteration start iteration that should be dumped * \param handle Handle of booster
* \param num_iteration, <= 0 means save all * \param start_iteration Start index of the iteration that should be dumped
* \param buffer_len string buffer length, if buffer_len < out_len, re-allocate buffer * \param num_iteration Index of the iteration that should be dumped, <= 0 means save all
* \param out_len actual output length * \param buffer_len String buffer length, if buffer_len < out_len, you should re-allocate buffer
* \param out_str json format string of model, need to pre-allocate memory before call this * \param[out] out_len Actual output length
* \return 0 when succeed, -1 when failure happens * \param[out] out_str JSON format string of model, should pre-allocate memory
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle,
int start_iteration, int start_iteration,
...@@ -926,12 +1002,13 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle, ...@@ -926,12 +1002,13 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle,
char* out_str); char* out_str);
/*! /*!
* \brief Get leaf value * \fn LGBM_BoosterGetLeafValue
* \param handle handle * \brief Get leaf value.
* \param tree_idx index of tree * \param handle Handle of booster
* \param leaf_idx index of leaf * \param tree_idx Index of tree
* \param out_val out result * \param leaf_idx Index of leaf
* \return 0 when succeed, -1 when failure happens * \param[out] out_val Output result from the specified leaf
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle,
int tree_idx, int tree_idx,
...@@ -939,12 +1016,13 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle, ...@@ -939,12 +1016,13 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle,
double* out_val); double* out_val);
/*! /*!
* \brief Set leaf value * \fn LGBM_BoosterSetLeafValue
* \param handle handle * \brief Set leaf value.
* \param tree_idx index of tree * \param handle Handle of booster
* \param leaf_idx index of leaf * \param tree_idx Index of tree
* \param val leaf value * \param leaf_idx Index of leaf
* \return 0 when succeed, -1 when failure happens * \param val Leaf value
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle,
int tree_idx, int tree_idx,
...@@ -952,12 +1030,15 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle, ...@@ -952,12 +1030,15 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle,
double val); double val);
/*! /*!
* \brief get model feature importance * \fn LGBM_BoosterFeatureImportance
* \param handle handle * \brief Get model feature importance.
* \param num_iteration, <= 0 means use all * \param handle Handle of booster
* \param importance_type: 0 for split, 1 for gain * \param num_iteration Number of iterations for which feature importance is calculated, <= 0 means use all
* \param out_results output value array * \param importance_type Method of importance calculation:
* \return 0 when succeed, -1 when failure happens * 0 for split, result contains numbers of times the feature is used in a model
* 1 for gain, result contains total gains of splits which use the feature
* \param[out] out_results Result array with feature importance
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle, LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle,
int num_iteration, int num_iteration,
...@@ -965,12 +1046,13 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle, ...@@ -965,12 +1046,13 @@ LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle,
double* out_results); double* out_results);
/*! /*!
* \brief Initilize the network * \fn LGBM_NetworkInit
* \param machines represent the nodes, format: ip1:port1,ip2:port2 * \brief Initialize the network.
* \param local_listen_port * \param machines List of machines in format 'ip1:port1,ip2:port2'
* \param listen_time_out * \param local_listen_port TCP listen port for local machines
* \param num_machines * \param listen_time_out Socket time-out in minutes
* \return 0 when succeed, -1 when failure happens * \param num_machines Total number of machines
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines, LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines,
int local_listen_port, int local_listen_port,
...@@ -978,11 +1060,22 @@ LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines, ...@@ -978,11 +1060,22 @@ LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines,
int num_machines); int num_machines);
/*! /*!
* \brief Finalize the network * \fn LGBM_NetworkFree
* \return 0 when succeed, -1 when failure happens * \brief Finalize the network.
* \return 0 when succeed, -1 when failure happens
*/ */
LIGHTGBM_C_EXPORT int LGBM_NetworkFree(); LIGHTGBM_C_EXPORT int LGBM_NetworkFree();
/*!
* \fn LGBM_NetworkInitWithFunctions
* \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
*/
LIGHTGBM_C_EXPORT int LGBM_NetworkInitWithFunctions(int num_machines, int rank, LIGHTGBM_C_EXPORT int LGBM_NetworkInitWithFunctions(int num_machines, int rank,
void* reduce_scatter_ext_fun, void* reduce_scatter_ext_fun,
void* allgather_ext_fun); void* allgather_ext_fun);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment