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