From ca0f7f271474df5a55c9588ae1481c4b74b01d0f Mon Sep 17 00:00:00 2001 From: Jiaming Yuan Date: Wed, 9 Nov 2022 07:14:12 +0800 Subject: [PATCH] [doc] Update C tutorial. [skip ci] (#8436) - Use rst references instead of doxygen links. - Replace deprecated functions. - Add SaveModel; put free step last [skip ci] Co-authored-by: Hyunsu Cho --- doc/tutorials/c_api_tutorial.rst | 63 ++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 23 deletions(-) diff --git a/doc/tutorials/c_api_tutorial.rst b/doc/tutorials/c_api_tutorial.rst index 5d4cb68cf..1cfec70f4 100644 --- a/doc/tutorials/c_api_tutorial.rst +++ b/doc/tutorials/c_api_tutorial.rst @@ -163,7 +163,7 @@ c. Assertion technique: It works both in C/ C++. If expression evaluates to 0 (f Sample examples along with Code snippet to use C API functions ************************************************************** -1. If the dataset is available in a file, it can be loaded into a ``DMatrix`` object using the `XGDMatrixCreateFromFile `_ +1. If the dataset is available in a file, it can be loaded into a ``DMatrix`` object using the :cpp:func:`XGDMatrixCreateFromFile` .. code-block:: c @@ -172,7 +172,7 @@ Sample examples along with Code snippet to use C API functions safe_xgboost(XGDMatrixCreateFromFile("/path/to/file/filename", silent, &data)); -2. You can also create a ``DMatrix`` object from a 2D Matrix using the `XGDMatrixCreateFromMat function `_ +2. You can also create a ``DMatrix`` object from a 2D Matrix using the :cpp:func:`XGDMatrixCreateFromMat` .. code-block:: c @@ -191,7 +191,7 @@ Sample examples along with Code snippet to use C API functions safe_xgboost(XGDMatrixCreateFromMat(data2, ROWS, COLS, -1, &dmatrix2)); -3. Create a Booster object for training & testing on dataset using `XGBoosterCreate `_ +3. Create a Booster object for training & testing on dataset using :cpp:func:`XGBoosterCreate` .. code-block:: c @@ -202,7 +202,7 @@ Sample examples along with Code snippet to use C API functions safe_xgboost(XGBoosterCreate(eval_dmats, eval_dmats_size, &booster)); -4. For each ``DMatrix`` object, set the labels using `XGDMatrixSetFloatInfo `_. Later you can access the label using `XGDMatrixGetFloatInfo `_. +4. For each ``DMatrix`` object, set the labels using :cpp:func:`XGDMatrixSetFloatInfo`. Later you can access the label using :cpp:func:`XGDMatrixGetFloatInfo`. .. code-block:: c @@ -235,7 +235,7 @@ Sample examples along with Code snippet to use C API functions } -5. Set the parameters for the ``Booster`` object according to the requirement using `XGBoosterSetParam `_ . Check out the full list of parameters available `here `_ . +5. Set the parameters for the ``Booster`` object according to the requirement using :cpp:func:`XGBoosterSetParam` . Check out the full list of parameters available :doc:`here ` . .. code-block :: c @@ -247,7 +247,7 @@ Sample examples along with Code snippet to use C API functions safe_xgboost(XGBoosterSetParam(booster, "eta", "0.1")); -6. Train & evaluate the model using `XGBoosterUpdateOneIter `_ and `XGBoosterEvalOneIter `_ respectively. +6. Train & evaluate the model using :cpp:func:`XGBoosterUpdateOneIter` and :cpp:func:`XGBoosterEvalOneIter` respectively. .. code-block:: c @@ -264,32 +264,31 @@ Sample examples along with Code snippet to use C API functions printf("%s\n", eval_result); } -.. note:: For customized loss function, use `XGBoosterBoostOneIter function `_ instead and manually specify the gradient and 2nd order gradient. +.. note:: For customized loss function, use :cpp:func:`XGBoosterBoostOneIter` instead and manually specify the gradient and 2nd order gradient. -7. Predict the result on a test set using `XGBoosterPredict `_ +7. Predict the result on a test set using :cpp:func:`XGBoosterPredictFromDMatrix` .. code-block:: c - bst_ulong output_length; - - const float *output_result; - safe_xgboost(XGBoosterPredict(booster, test, 0, 0, &output_length, &output_result)); + char const config[] = + "{\"training\": false, \"type\": 0, " + "\"iteration_begin\": 0, \"iteration_end\": 0, \"strict_shape\": false}"; + /* Shape of output prediction */ + uint64_t const* out_shape; + /* Dimension of output prediction */ + uint64_t out_dim; + /* Pointer to a thread local contigious array, assigned in prediction function. */ + float const* out_result = NULL; + safe_xgboost( + XGBoosterPredictFromDMatrix(booster, dmatrix, config, &out_shape, &out_dim, &out_result)); for (unsigned int i = 0; i < output_length; i++){ printf("prediction[%i] = %f \n", i, output_result[i]); } -8. Free all the internal structure used in your code using `XGDMatrixFree `_ and `XGBoosterFree `_. This step is important to prevent memory leak. - -.. code-block:: c - - safe_xgboost(XGDMatrixFree(dmatrix)); - safe_xgboost(XGBoosterFree(booster)); - - -9. Get the number of features in your dataset using `XGBoosterGetNumFeature `_. +8. Get the number of features in your dataset using :cpp:func:`XGBoosterGetNumFeature`. .. code-block:: c @@ -304,12 +303,22 @@ Sample examples along with Code snippet to use C API functions printf("num_feature: %lu\n", (unsigned long)(num_of_features)); -10. Load the model using `XGBoosterLoadModel function `_ + +9. Save the model using :cpp:func:`XGBoosterSaveModel` .. code-block:: c BoosterHandle booster; - const char *model_path = "/path/of/model"; + const char *model_path = "/path/of/model.json"; + safe_xgboost(XGBoosterSaveModel(booster, model_path)); + + +10. Load the model using :cpp:func:`XGBoosterLoadModel` + +.. code-block:: c + + BoosterHandle booster; + const char *model_path = "/path/of/model.json"; // create booster handle first safe_xgboost(XGBoosterCreate(NULL, 0, &booster)); @@ -320,3 +329,11 @@ Sample examples along with Code snippet to use C API functions safe_xgboost(XGBoosterLoadModel(booster, model_path)); // predict the model here + + +11. Free all the internal structure used in your code using :cpp:func:`XGDMatrixFree` and :cpp:func:`XGBoosterFree`. This step is important to prevent memory leak. + +.. code-block:: c + + safe_xgboost(XGDMatrixFree(dmatrix)); + safe_xgboost(XGBoosterFree(booster));