Package 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 an XGBoost Model
See Also:

  • Field Details

  • Method Details

    • 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 value from the Booster based on the key provided.
      Parameters:
      key - attribute key
      Returns:
      attribute value
      Throws:
      XGBoostError - native error

    • setAttr

      public final void setAttr(String key, String value) throws XGBoostError
      Set an attribute key-value pair 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 multiple attribute key-value pairs to the Booster.
      Parameters:
      attrs - attributes key-value map
      Throws:
      XGBoostError - native error

    • getFeatureNames

      public final String[] getFeatureNames() throws XGBoostError
      Get all the feature names from the Booster.
      Returns:
      An array of all the feature names.
      Throws:
      XGBoostError

    • setFeatureNames

      public void setFeatureNames(String[] featureNames) throws XGBoostError
      Set feature names to the Booster.
      Parameters:
      featureNames - An array of all the feature names.
      Throws:
      XGBoostError

    • getFeatureTypes

      public final String[] getFeatureTypes() throws XGBoostError
      Get feature types from the Booster.
      Returns:
      An array of all the feature types.
      Throws:
      XGBoostError

    • setFeatureTypes

      public void setFeatureTypes(String[] featureTypes) throws XGBoostError
      Set feature types to the Booster.
      Parameters:
      featureTypes - An array of all the feature types.
      Throws:
      XGBoostError

    • 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

      @Deprecated public void update(DMatrix dtrain, IObjective obj) throws XGBoostError
      Deprecated.
      Throws:
      XGBoostError

    • update

      public void update(DMatrix dtrain, int iter, IObjective obj) throws XGBoostError
      Update with customize object functon
      Parameters:
      dtrain - training data
      iter - The current training iteration.
      obj - customized objective class
      Throws:
      XGBoostError - native error

    • boost

      @Deprecated public void boost(DMatrix dtrain, float[] grad, float[] hess) throws XGBoostError
      Deprecated.
      Throws:
      XGBoostError

    • boost

      public void boost(DMatrix dtrain, int iter, float[] grad, float[] hess) throws XGBoostError
      Update with give grad and hess
      Parameters:
      dtrain - training data
      iter - The current training iteration.
      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 the Booster model with given dmatrixs.
      Parameters:
      evalMatrixs - dmatrixs for evaluation
      evalNames - name for eval dmatrixs, used for check results
      iter - current eval iteration
      Returns:
      eval Information containing the evaluation results
      Throws:
      XGBoostError - native error

    • evalSet

      public String evalSet(DMatrix[] evalMatrixs, String[] evalNames, int iter, float[] metricsOut) throws XGBoostError
      Evaluate the Booster model 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 containing the evaluation results
      Throws:
      XGBoostError - native error

    • evalSet

      public String evalSet(DMatrix[] evalMatrixs, String[] evalNames, IEvaluation eval) throws XGBoostError
      Evaluate the Booster model given customized Evaluation class
      Parameters:
      evalMatrixs - evaluation matrix
      evalNames - evaluation names
      eval - custom evaluator
      Returns:
      eval Information containing the evaluation results
      Throws:
      XGBoostError - native error

    • evalSet

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

    • inplace_predict

      public float[][] inplace_predict(float[] data, int nrow, int ncol, float missing) throws XGBoostError
      Perform thread-safe prediction.
      Parameters:
      data - Flattened input matrix of features for prediction
      nrow - The number of preditions to make (count of input matrix rows)
      ncol - The number of features in the model (count of input matrix columns)
      missing - Value indicating missing element in the data input matrix
      Returns:
      predict Result matrix
      Throws:
      XGBoostError

    • inplace_predict

      public float[][] inplace_predict(float[] data, int nrow, int ncol, float missing, int[] iteration_range) throws XGBoostError
      Perform thread-safe prediction.
      Parameters:
      data - Flattened input matrix of features for prediction
      nrow - The number of preditions to make (count of input matrix rows)
      ncol - The number of features in the model (count of input matrix columns)
      missing - Value indicating missing element in the data input matrix
      iteration_range - Specifies which layer of trees are used in prediction. For example, if a random forest is trained with 100 rounds. Specifying `iteration_range=[10, 20)`, then only the forests built during [10, 20) (half open set) rounds are used in this prediction.
      Returns:
      predict Result matrix
      Throws:
      XGBoostError

    • inplace_predict

      public float[][] inplace_predict(float[] data, int nrow, int ncol, float missing, int[] iteration_range, Booster.PredictionType predict_type, float[] base_margin) throws XGBoostError
      Perform thread-safe prediction.
      Parameters:
      data - Flattened input matrix of features for prediction
      nrow - The number of preditions to make (count of input matrix rows)
      ncol - The number of features in the model (count of input matrix columns)
      missing - Value indicating missing element in the data input matrix
      iteration_range - Specifies which layer of trees are used in prediction. For example, if a random forest is trained with 100 rounds. Specifying `iteration_range=[10, 20)`, then only the forests built during [10, 20) (half open set) rounds are used in this prediction.
      predict_type - What kind of prediction to run.
      Returns:
      predict Result matrix
      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
      Make a prediction with test data in a DMatrix format.
      Parameters:
      data - dmatrix storing the test input on which predictions are to be made
      Returns:
      predict The results of the prediction, where each row corresponds to a prediction.
      Throws:
      XGBoostError - native error

    • predict

      public float[][] predict(DMatrix data, boolean outputMargin) throws XGBoostError
      Make a prediction with test data in a DMatrix format and output margin.
      Parameters:
      data - dmatrix storing the test input on which predictions are to be made
      outputMargin - output margin
      Returns:
      predict The results of the prediction, where each row corresponds to a prediction.
      Throws:
      XGBoostError

    • predict

      public float[][] predict(DMatrix data, boolean outputMargin, int treeLimit) throws XGBoostError
      Advanced predict function with all the options.
      Parameters:
      data - matrix storing the test input on which predictions are to be made
      outputMargin - output margin
      treeLimit - limit number of trees, 0 means all trees.
      Returns:
      predict The results of the prediction, where each row corresponds to a prediction.
      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

    • saveModel

      public void saveModel(OutputStream out, String format) 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
      format - The model format (ubj, json, deprecated)
      Throws:
      XGBoostError
      IOException

    • getModelDump

      public String[] getModelDump(String featureMap, boolean withStats) throws XGBoostError
      Get the dump of the model as a string array
      Parameters:
      featureMap - A string containing the path to a feature map.
      withStats - Controls whether the split statistics are output.
      Returns:
      The dumped model information
      Throws:
      XGBoostError - native error

    • getModelDump

      public String[] getModelDump(String featureMap, boolean withStats, String format) throws XGBoostError
      Get the dump of the model as a string array with specified feature map, stats, and the specified format.
      Parameters:
      featureMap - A string containing the path to a feature map.
      withStats - Controls whether the split statistics are output.
      format - The format in which the model is dumped (text, json, ubj).
      Returns:
      The dumped model information
      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
      Get the dump of the model as a string array with specified feature map, stats, and the specified format.
      Parameters:
      featureNames - An array of strings containing the feature names.
      withStats - Controls whether the split statistics are output.
      format - The format in which the model is dumped (text, json, ubj).
      Returns:
      The dumped model information
      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

    • toByteArray

      public byte[] toByteArray() throws XGBoostError
      Save model into raw byte array in the UBJSON ("ubj") format.
      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

    • getNumBoostedRound

      public int getNumBoostedRound() throws XGBoostError
      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