Class LGBMBooster

java.lang.Object

io.github.metarank.lightgbm4j.LGBMBooster

All Implemented Interfaces:

AutoCloseable

public class LGBMBooster
extends Object
implements AutoCloseable

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	LGBMBooster.FastConfig
static enum	LGBMBooster.FeatureImportanceType

Method Summary

Modifier and Type	Method	Description
void	addValidData(LGBMDataset dataset)	Add new validation data to booster.
void	close()	Deallocate all native memory for the LightGBM model.
static LGBMBooster	create(LGBMDataset dataset, String parameters)	Create a new boosting learner.
static LGBMBooster	createFromModelfile(String file)	Load an existing booster from model file.
double[]	featureImportance(int numIteration, LGBMBooster.FeatureImportanceType importanceType)	Get model feature importance.
double[]	getEval(int dataIndex)	Get evaluation for training data and validation data.
String[]	getEvalNames()	Get names of evaluation datasets.
String[]	getFeatureNames()	Get names of features.
int	getNumClasses()	Get number of classes.
int	getNumFeature()	Get number of features.
long	getNumPredict(int dataIdx)	Get number of predictions for training data and validation data (this can be used to support customized evaluation functions).
double[]	getPredict(int dataIdx)	Get prediction for training data and validation data.
static boolean	isNativeLoaded()	Called from tests.
static LGBMBooster	loadModelFromString(String model)	Load an existing booster from string.
static void	loadNative()	Loads all corresponsing native libraries for current platform.
double[]	predictForMat(double[] input, int rows, int cols, boolean isRowMajor, PredictionType predictionType)
double[]	predictForMat(double[] input, int rows, int cols, boolean isRowMajor, PredictionType predictionType, String parameter)	Make prediction for a new double[] dataset.
double[]	predictForMat(float[] input, int rows, int cols, boolean isRowMajor, PredictionType predictionType)
double[]	predictForMat(float[] input, int rows, int cols, boolean isRowMajor, PredictionType predictionType, String parameter)	Make prediction for a new float[] dataset.
double	predictForMatSingleRow(double[] data, PredictionType predictionType)	Make prediction for a new double[] row dataset.
double	predictForMatSingleRow(float[] data, PredictionType predictionType)	Make prediction for a new float[] row dataset.
double	predictForMatSingleRowFast(LGBMBooster.FastConfig config, double[] data, PredictionType predictionType)
double	predictForMatSingleRowFast(LGBMBooster.FastConfig config, float[] data, PredictionType predictionType)
LGBMBooster.FastConfig	predictForMatSingleRowFastInit(PredictionType predictionType, int dtype, int ncols, String parameter)
String	saveModelToString(int startIteration, int numIteration, LGBMBooster.FeatureImportanceType featureImportance)	Save model to string.
boolean	updateOneIter()	Update the model for one iteration.
boolean	updateOneIterCustom(float[] grad, float[] hess)	Update the model by specifying gradient and Hessian directly (this can be used to support customized loss functions).

Methods inherited from class java.lang.Object

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

Method Details

isNativeLoaded

public static boolean isNativeLoaded()

Called from tests.

Returns:

true if JNI libraries were loaded successfully.

loadNative

public static void loadNative()
                       throws IOException

Loads all corresponsing native libraries for current platform. Called from the class initializer, so usually there is no need to call it directly.

Throws:

IOException

createFromModelfile

public static LGBMBooster createFromModelfile(String file)
                                       throws LGBMException

Load an existing booster from model file.

Parameters:

file - Filename of model

Returns:

Booster instance.

Throws:

LGBMException

loadModelFromString

public static LGBMBooster loadModelFromString(String model)
                                       throws LGBMException

Load an existing booster from string.

Parameters:

model - Model string

Returns:

Booster instance.

Throws:

LGBMException

close

public void close()
           throws LGBMException

Deallocate all native memory for the LightGBM model.

Specified by:

close in interface AutoCloseable

Throws:

LGBMException

predictForMat

public double[] predictForMat(float[] input,
 int rows,
 int cols,
 boolean isRowMajor,
 PredictionType predictionType,
 String parameter)
                       throws LGBMException

Make prediction for a new float[] dataset.

Parameters:

input - input matrix, as a 1D array. Size should be rows * cols.

rows - number of rows

cols - number of cols

isRowMajor - is the 1d encoding a row-major?

predictionType - the prediction type

parameter - prediction options

Returns:

array of predictions

Throws:

LGBMException

predictForMat

public double[] predictForMat(float[] input,
 int rows,
 int cols,
 boolean isRowMajor,
 PredictionType predictionType)
                       throws LGBMException

Throws:

LGBMException

predictForMat

public double[] predictForMat(double[] input,
 int rows,
 int cols,
 boolean isRowMajor,
 PredictionType predictionType,
 String parameter)
                       throws LGBMException

Make prediction for a new double[] dataset.

Parameters:

input - input matrix, as a 1D array. Size should be rows * cols.

rows - number of rows

cols - number of cols

isRowMajor - is the 1 d encoding a row-major?

predictionType - the prediction type

parameter - prediction options

Returns:

array of predictions

Throws:

LGBMException

predictForMat

public double[] predictForMat(double[] input,
 int rows,
 int cols,
 boolean isRowMajor,
 PredictionType predictionType)
                       throws LGBMException

Throws:

LGBMException

create

public static LGBMBooster create(LGBMDataset dataset,
 String parameters)
                          throws LGBMException

Create a new boosting learner.

Parameters:

dataset - a LGBMDataset with the training data.

parameters - Parameters in format ‘key1=value1 key2=value2’

Returns:

Throws:

LGBMException

updateOneIter

public boolean updateOneIter()
                      throws LGBMException

Update the model for one iteration.

Returns:

true if there are no more splits possible, so training is finished.

Throws:

LGBMException

saveModelToString

public String saveModelToString(int startIteration,
 int numIteration,
 LGBMBooster.FeatureImportanceType featureImportance)
                         throws LGBMException

Save model to string.

Parameters:

startIteration - Start index of the iteration that should be saved

numIteration - Index of the iteration that should be saved, 0 and negative means save all

featureImportance - Type of feature importance, can be FeatureImportanceType.SPLIT or FeatureImportanceType.GAIN

Returns:

Throws:

LGBMException

getFeatureNames

public String[] getFeatureNames()
                         throws LGBMException

Get names of features.

Returns:

a list of feature names.

Throws:

LGBMException

addValidData

public void addValidData(LGBMDataset dataset)
                  throws LGBMException

Add new validation data to booster.

Parameters:

dataset - dataset to validate

Throws:

LGBMException

getEval

public double[] getEval(int dataIndex)
                 throws LGBMException

Get evaluation for training data and validation data.

Parameters:

dataIndex - Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on

Returns:

Throws:

LGBMException

getEvalNames

public String[] getEvalNames()
                      throws LGBMException

Get names of evaluation datasets.

Returns:

array of eval dataset names.

Throws:

LGBMException

featureImportance

public double[] featureImportance(int numIteration,
 LGBMBooster.FeatureImportanceType importanceType)
                           throws LGBMException

Get model feature importance.

Parameters:

numIteration - Number of iterations for which feature importance is calculated, 0 or less means use all

importanceType - GAIN or SPLIT

Returns:

Result array with feature importance

Throws:

LGBMException

getNumFeature

public int getNumFeature()
                  throws LGBMException

Get number of features.

Returns:

number of features

Throws:

LGBMException

predictForMatSingleRow

public double predictForMatSingleRow(double[] data,
 PredictionType predictionType)
                              throws LGBMException

Make prediction for a new double[] row dataset. This method re-uses the internal predictor structure from previous calls and is optimized for single row invocation.

Parameters:

data - input vector

predictionType - the prediction type

Returns:

score

Throws:

LGBMException

predictForMatSingleRow

public double predictForMatSingleRow(float[] data,
 PredictionType predictionType)
                              throws LGBMException

Make prediction for a new float[] row dataset. This method re-uses the internal predictor structure from previous calls and is optimized for single row invocation.

Parameters:

data - input vector

predictionType - the prediction type

Returns:

score

Throws:

LGBMException

predictForMatSingleRowFastInit

public LGBMBooster.FastConfig predictForMatSingleRowFastInit(PredictionType predictionType,
 int dtype,
 int ncols,
 String parameter)
                                                      throws LGBMException

Throws:

LGBMException

predictForMatSingleRowFast

public double predictForMatSingleRowFast(LGBMBooster.FastConfig config,
 float[] data,
 PredictionType predictionType)
                                  throws LGBMException

Throws:

LGBMException

predictForMatSingleRowFast

public double predictForMatSingleRowFast(LGBMBooster.FastConfig config,
 double[] data,
 PredictionType predictionType)
                                  throws LGBMException

Throws:

LGBMException

getNumClasses

public int getNumClasses()
                  throws LGBMException

Get number of classes.

Returns:

Number of classes

Throws:

LGBMException

getNumPredict

public long getNumPredict(int dataIdx)
                   throws LGBMException

Get number of predictions for training data and validation data (this can be used to support customized evaluation functions).

Parameters:

dataIdx - Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on

Returns:

Number of predictions

Throws:

LGBMException

getPredict

public double[] getPredict(int dataIdx)
                    throws LGBMException

Get prediction for training data and validation data.

Parameters:

dataIdx - Index of data, 0: training data, 1: 1st validation data, 2: 2nd validation data and so on

Returns:

array with predictions, of size num_class * dataset.num_data

Throws:

LGBMException

updateOneIterCustom

public boolean updateOneIterCustom(float[] grad,
 float[] hess)
                            throws LGBMException

Update the model by specifying gradient and Hessian directly (this can be used to support customized loss functions). The length of the arrays referenced by grad and hess must be equal to num_class * num_train_data, this is not verified by the library, the caller must ensure this.

Parameters:

grad - The first order derivative (gradient) statistics

hess - The second order derivative (Hessian) statistics

Returns:

true means the update was successfully finished (cannot split anymore), false indicates failure

Throws:

LGBMException