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:

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
static class	Booster.PredictionType This enumeration defines the type of prediction to be made and is used for inplace predictions.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_FORMAT

Method Summary

Modifier and Type	Method and Description
void	boost(DMatrix dtrain, float[] grad, float[] hess) Deprecated.
void	boost(DMatrix dtrain, int iter, float[] grad, float[] hess) Update with give grad and hess
void	dispose()
String	evalSet(DMatrix[] evalMatrixs, String[] evalNames, IEvaluation eval) Evaluate the Booster model given customized Evaluation class
String	evalSet(DMatrix[] evalMatrixs, String[] evalNames, IEvaluation eval, float[] metricsOut)
String	evalSet(DMatrix[] evalMatrixs, String[] evalNames, int iter) Evaluate the Booster model with given dmatrixs.
String	evalSet(DMatrix[] evalMatrixs, String[] evalNames, int iter, float[] metricsOut) Evaluate the Booster model with given dmatrixs.
protected void	finalize()
String	getAttr(String key) Get attribute value from the Booster based on the key provided.
Map<String,String>	getAttrs() Get attributes stored in the Booster as a Map.
String[]	getFeatureNames() Get all the feature names from the Booster.
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[]	getFeatureTypes() Get feature types from the Booster.
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) Get the dump of the model as a string array with specified feature map, stats, and the specified 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) Get the dump of the model as a string array with specified feature map, stats, and the specified format.
int	getNumBoostedRound()
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
float[][]	inplace_predict(float[] data, int nrow, int ncol, float missing) Perform thread-safe prediction.
float[][]	inplace_predict(float[] data, int nrow, int ncol, float missing, int[] iteration_range) Perform thread-safe prediction.
float[][]	inplace_predict(float[] data, int nrow, int ncol, float missing, int[] iteration_range, Booster.PredictionType predict_type, float[] base_margin) Perform thread-safe prediction.
float[][]	predict(DMatrix data) Make a prediction with test data in a DMatrix format.
float[][]	predict(DMatrix data, boolean outputMargin) Make a prediction with test data in a DMatrix format and output margin.
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(OutputStream out, String format) Save the model to file opened as output stream.
void	saveModel(String modelPath) Save model to modelPath
void	setAttr(String key, String value) Set an attribute key-value pair to the Booster.
void	setAttrs(Map<String,String> attrs) Set multiple attribute key-value pairs to the Booster.
void	setFeatureNames(String[] featureNames) Set feature names to the Booster.
void	setFeatureTypes(String[] featureTypes) Set feature types 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.
byte[]	toByteArray() Save model into raw byte array in the UBJSON ("ubj") format.
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, int iter, IObjective obj) Update with customize object functon
void	update(DMatrix dtrain, IObjective obj) Deprecated.
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

Field Detail

DEFAULT_FORMAT

public static final String DEFAULT_FORMAT

See Also:

Constant Field Values

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 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