ml.dmlc.xgboost4j.java

## Class Booster

- java.lang.Object
- - ml.dmlc.xgboost4j.java.Booster

- All Implemented Interfaces:
    com.esotericsoftware.kryo.KryoSerializable, Serializable

      public class Booster
      extends Object
      implements Serializable, com.esotericsoftware.kryo.KryoSerializable

  Booster for xgboost, this is a model API that support interactive build of a XGBoost Model
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Booster.FeatureImportanceType` Supported feature importance types WEIGHT = Number of nodes that a feature was used to determine a split GAIN = Average information gain per split for a feature COVER = Average cover per split for a feature TOTAL_GAIN = Total information gain over all splits of a feature TOTAL_COVER = Total cover over all splits of a feature

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `boost(DMatrix dtrain, float[] grad, float[] hess)` update with give grad and hess
    `void` | `dispose()`
    `String` | `evalSet(DMatrix[] evalMatrixs, String[] evalNames, IEvaluation eval)` evaluate with given customized Evaluation class
    `String` | `evalSet(DMatrix[] evalMatrixs, String[] evalNames, IEvaluation eval, float[] metricsOut)`
    `String` | `evalSet(DMatrix[] evalMatrixs, String[] evalNames, int iter)` evaluate with given dmatrixs.
    `String` | `evalSet(DMatrix[] evalMatrixs, String[] evalNames, int iter, float[] metricsOut)` evaluate with given dmatrixs.
    `protected void` | `finalize()`
    `String` | `getAttr(String key)` Get attribute from the Booster.
    `Map<String,String>` | `getAttrs()` Get attributes stored in the Booster as a Map.
    `Map<String,Integer>` | `getFeatureScore(String featureMap)` Get importance of each feature
    `Map<String,Integer>` | `getFeatureScore(String[] featureNames)` Get importance of each feature with specified feature names.
    `String[]` | `getModelDump(String[] featureNames, boolean withStats)` Get the dump of the model as a string array with specified feature names.
    `String[]` | `getModelDump(String[] featureNames, boolean withStats, String format)`
    `String[]` | `getModelDump(String featureMap, boolean withStats)` Get the dump of the model as a string array
    `String[]` | `getModelDump(String featureMap, boolean withStats, String format)`
    `long` | `getNumFeature()` Get number of model features.
    `Map<String,Double>` | `getScore(String[] featureNames, String importanceType)` Get the feature importances for gain or cover (average or total)
    `Map<String,Double>` | `getScore(String featureMap, String importanceType)` Get the feature importances for gain or cover (average or total), with feature names
    `int` | `getVersion()`
    `float[][]` | `predict(DMatrix data)` Predict with data
    `float[][]` | `predict(DMatrix data, boolean outputMargin)` Predict with data
    `float[][]` | `predict(DMatrix data, boolean outputMargin, int treeLimit)` Advanced predict function with all the options.
    `float[][]` | `predictContrib(DMatrix data, int treeLimit)` Output feature contributions toward predictions of given data
    `float[][]` | `predictLeaf(DMatrix data, int treeLimit)` Predict leaf indices given the data
    `void` | `read(com.esotericsoftware.kryo.Kryo kryo, com.esotericsoftware.kryo.io.Input input)`
    `void` | `saveModel(OutputStream out)` Save the model to file opened as output stream.
    `void` | `saveModel(String modelPath)` Save model to modelPath
    `void` | `setAttr(String key, String value)` Set attribute to the Booster.
    `void` | `setAttrs(Map<String,String> attrs)` Set attributes to the Booster.
    `void` | `setParam(String key, Object value)` Set parameter to the Booster.
    `void` | `setParams(Map<String,Object> params)` Set parameters to the Booster.
    `void` | `setVersion(int version)`
    `byte[]` | `toByteArray()` Save model into raw byte array.
    `byte[]` | `toByteArray(String format)` Save model into raw byte array.
    `void` | `update(DMatrix dtrain, int iter)` Update the booster for one iteration.
    `void` | `update(DMatrix dtrain, IObjective obj)` Update with customize obj func
    `void` | `write(com.esotericsoftware.kryo.Kryo kryo, com.esotericsoftware.kryo.io.Output output)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### setParam

          public final void setParam(String key,
                                     Object value)
                              throws XGBoostError

      Set parameter to the Booster.
      Parameters:
        `key` - param name
        `value` - param value
      Throws:
        `XGBoostError` - native error

    - #### setParams

          public void setParams(Map<String,Object> params)
                         throws XGBoostError

      Set parameters to the Booster.
      Parameters:
        `params` - parameters key-value map
      Throws:
        `XGBoostError` - native error

    - #### getAttrs

          public final Map<String,String> getAttrs()
                                            throws XGBoostError

      Get attributes stored in the Booster as a Map.
      Returns:
        A map contain attribute pairs.
      Throws:
        `XGBoostError` - native error

    - #### getAttr

          public final String getAttr(String key)
                               throws XGBoostError

      Get attribute from the Booster.
      Parameters:
        `key` - attribute key
      Returns:
        attribute value
      Throws:
        `XGBoostError` - native error

    - #### setAttr

          public final void setAttr(String key,
                                    String value)
                             throws XGBoostError

      Set attribute to the Booster.
      Parameters:
        `key` - attribute key
        `value` - attribute value
      Throws:
        `XGBoostError` - native error

    - #### setAttrs

          public void setAttrs(Map<String,String> attrs)
                        throws XGBoostError

      Set attributes to the Booster.
      Parameters:
        `attrs` - attributes key-value map
      Throws:
        `XGBoostError` - native error

    - #### update

          public void update(DMatrix dtrain,
                             int iter)
                      throws XGBoostError

      Update the booster for one iteration.
      Parameters:
        `dtrain` - training data
        `iter` - current iteration number
      Throws:
        `XGBoostError` - native error

    - #### update

          public void update(DMatrix dtrain,
                             IObjective obj)
                      throws XGBoostError

      Update with customize obj func
      Parameters:
        `dtrain` - training data
        `obj` - customized objective class
      Throws:
        `XGBoostError` - native error

    - #### boost

          public void boost(DMatrix dtrain,
                            float[] grad,
                            float[] hess)
                     throws XGBoostError

      update with give grad and hess
      Parameters:
        `dtrain` - training data
        `grad` - first order of gradient
        `hess` - seconde order of gradient
      Throws:
        `XGBoostError` - native error

    - #### evalSet

          public String evalSet(DMatrix[] evalMatrixs,
                                String[] evalNames,
                                int iter)
                         throws XGBoostError

      evaluate with given dmatrixs.
      Parameters:
        `evalMatrixs` - dmatrixs for evaluation
        `evalNames` - name for eval dmatrixs, used for check results
        `iter` - current eval iteration
      Returns:
        eval information
      Throws:
        `XGBoostError` - native error

    - #### evalSet

          public String evalSet(DMatrix[] evalMatrixs,
                                String[] evalNames,
                                int iter,
                                float[] metricsOut)
                         throws XGBoostError

      evaluate with given dmatrixs.
      Parameters:
        `evalMatrixs` - dmatrixs for evaluation
        `evalNames` - name for eval dmatrixs, used for check results
        `iter` - current eval iteration
        `metricsOut` - output array containing the evaluation metrics for each evalMatrix
      Returns:
        eval information
      Throws:
        `XGBoostError` - native error

    - #### evalSet

          public String evalSet(DMatrix[] evalMatrixs,
                                String[] evalNames,
                                IEvaluation eval)
                         throws XGBoostError

      evaluate with given customized Evaluation class
      Parameters:
        `evalMatrixs` - evaluation matrix
        `evalNames` - evaluation names
        `eval` - custom evaluator
      Returns:
        eval information
      Throws:
        `XGBoostError` - native error

    - #### evalSet

          public String evalSet(DMatrix[] evalMatrixs,
                                String[] evalNames,
                                IEvaluation eval,
                                float[] metricsOut)
                         throws XGBoostError

      Throws:
        `XGBoostError`

    - #### predictLeaf

          public float[][] predictLeaf(DMatrix data,
                                       int treeLimit)
                                throws XGBoostError

      Predict leaf indices given the data
      Parameters:
        `data` - The input data.
        `treeLimit` - Number of trees to include, 0 means all trees.
      Returns:
        The leaf indices of the instance.
      Throws:
        `XGBoostError`

    - #### predictContrib

          public float[][] predictContrib(DMatrix data,
                                          int treeLimit)
                                   throws XGBoostError

      Output feature contributions toward predictions of given data
      Parameters:
        `data` - The input data.
        `treeLimit` - Number of trees to include, 0 means all trees.
      Returns:
        The feature contributions and bias.
      Throws:
        `XGBoostError`

    - #### predict

          public float[][] predict(DMatrix data)
                            throws XGBoostError

      Predict with data
      Parameters:
        `data` - dmatrix storing the input
      Returns:
        predict result
      Throws:
        `XGBoostError` - native error

    - #### predict

          public float[][] predict(DMatrix data,
                                   boolean outputMargin)
                            throws XGBoostError

      Predict with data
      Parameters:
        `data` - data
        `outputMargin` - output margin
      Returns:
        predict results
      Throws:
        `XGBoostError`

    - #### predict

          public float[][] predict(DMatrix data,
                                   boolean outputMargin,
                                   int treeLimit)
                            throws XGBoostError

      Advanced predict function with all the options.
      Parameters:
        `data` - data
        `outputMargin` - output margin
        `treeLimit` - limit number of trees, 0 means all trees.
      Returns:
        predict results
      Throws:
        `XGBoostError`

    - #### saveModel

          public void saveModel(String modelPath)
                         throws XGBoostError

      Save model to modelPath
      Parameters:
        `modelPath` - model path
      Throws:
        `XGBoostError`

    - #### saveModel

          public void saveModel(OutputStream out)
                         throws XGBoostError,
                                IOException

      Save the model to file opened as output stream. The model format is compatible with other xgboost bindings. The output stream can only save one xgboost model. This function will close the OutputStream after the save.
      Parameters:
        `out` - The output stream
      Throws:
        `XGBoostError`
        `IOException`

    - #### getModelDump

          public String[] getModelDump(String featureMap,
                                       boolean withStats)
                                throws XGBoostError

      Get the dump of the model as a string array
      Parameters:
        `withStats` - Controls whether the split statistics are output.
      Returns:
        dumped model information
      Throws:
        `XGBoostError` - native error

    - #### getModelDump

          public String[] getModelDump(String featureMap,
                                       boolean withStats,
                                       String format)
                                throws XGBoostError

      Throws:
        `XGBoostError`

    - #### getModelDump

          public String[] getModelDump(String[] featureNames,
                                       boolean withStats)
                                throws XGBoostError

      Get the dump of the model as a string array with specified feature names.
      Parameters:
        `featureNames` - Names of the features.
      Returns:
        dumped model information
      Throws:
        `XGBoostError`

    - #### getModelDump

          public String[] getModelDump(String[] featureNames,
                                       boolean withStats,
                                       String format)
                                throws XGBoostError

      Throws:
        `XGBoostError`

    - #### getFeatureScore

          public Map<String,Integer> getFeatureScore(String[] featureNames)
                                              throws XGBoostError

      Get importance of each feature with specified feature names.
      Returns:
        featureScoreMap key: feature name, value: feature importance score, can be nill.
      Throws:
        `XGBoostError` - native error

    - #### getFeatureScore

          public Map<String,Integer> getFeatureScore(String featureMap)
                                              throws XGBoostError

      Get importance of each feature
      Returns:
        featureScoreMap key: feature index, value: feature importance score, can be nill
      Throws:
        `XGBoostError` - native error

    - #### getScore

          public Map<String,Double> getScore(String[] featureNames,
                                             String importanceType)
                                      throws XGBoostError

      Get the feature importances for gain or cover (average or total)
      Returns:
        featureImportanceMap key: feature index, values: feature importance score based on gain or cover
      Throws:
        `XGBoostError` - native error

    - #### getScore

          public Map<String,Double> getScore(String featureMap,
                                             String importanceType)
                                      throws XGBoostError

      Get the feature importances for gain or cover (average or total), with feature names
      Returns:
        featureImportanceMap key: feature name, values: feature importance score based on gain or cover
      Throws:
        `XGBoostError` - native error

    - #### getVersion

          public int getVersion()

    - #### setVersion

          public void setVersion(int version)

    - #### toByteArray

          public byte[] toByteArray()
                             throws XGBoostError

      Save model into raw byte array. Currently it's using the deprecated format as default, which will be changed into `ubj` in future releases.
      Returns:
        the saved byte array
      Throws:
        `XGBoostError` - native error

    - #### toByteArray

          public byte[] toByteArray(String format)
                             throws XGBoostError

      Save model into raw byte array.
      Parameters:
        `format` - The output format. Available options are "json", "ubj" and "deprecated".
      Returns:
        the saved byte array
      Throws:
        `XGBoostError` - native error

    - #### getNumFeature

          public long getNumFeature()
                             throws XGBoostError

      Get number of model features.
      Returns:
        the number of features.
      Throws:
        `XGBoostError`

    - #### finalize

          protected void finalize()
                           throws Throwable

      Overrides:
        `finalize` in class `Object`
      Throws:
        `Throwable`

    - #### dispose

          public void dispose()

    - #### write

          public void write(com.esotericsoftware.kryo.Kryo kryo,
                            com.esotericsoftware.kryo.io.Output output)

      Specified by:
        `write` in interface `com.esotericsoftware.kryo.KryoSerializable`

    - #### read

          public void read(com.esotericsoftware.kryo.Kryo kryo,
                           com.esotericsoftware.kryo.io.Input input)

      Specified by:
        `read` in interface `com.esotericsoftware.kryo.KryoSerializable`

Copyright © 2022. All rights reserved.