com.tibco.patterns.learn.rlink

Class RLink

java.lang.Object

com.tibco.patterns.learn.rlink.RLink

public class RLink
extends java.lang.Object

Performs communication with rlink_jni library using JNI to create, load, save, train and evaluate RLink models. Can manage several models at the same time. When new model is created or read from file, a model ID is returned. It is then passed as modelId to all other methods to refer to a specific model. Model training and evaluation is done with individual feature vectors. Most methods are wrappers of native functions. They throw exceptions when native functions return error codes.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RLink.SubsetTrainMode Defines methods used to generate training examples for subsets of given training example
static class	RLink.ThermometerType Type of thermometers used in RLink model.

Field Summary

Fields

Modifier and Type	Field and Description
static double	EMPTY_SCORE The value -1 used for the empty feature score (when it cannot be calculated).
static double	MAX_SCORE The maximum non-empty feature score, and the maximum model score (1).
static double	MIN_SCORE The minimum non-empty feature score, and the minimum model score (0).
static double	NO_CONFIDENCE_MEASURE The value returned if no confidence measure was calculated or if the requested confidence measure is not supported by the given model.

Method Summary

Modifier and Type	Method and Description
static void	beginIteration(int modelId) Must be called before each training iteration with the entire training dataset.
static int	createModel(int nFeatures, double p, double learningRate, int precisionBits, RLink.ThermometerType thermometerType, int[] falseSubsets) Creates a new untrained RLink model.
static void	destroyModels() Destroys all RLink models created by the RLink singleton object.
static void	endIteration(int modelId) Must be called after each training iteration with the entire training dataset.
protected void	finalize() Provided for safety, but client code must call destroyModels() explicitly.
static double[]	getFalseInsertScores(int modelId)
static double[]	getFalseRemoveLimits(int modelId)
static int	getFeatureCount(int modelId) Gets the number of model features.
static java.lang.String	getID(int modelId) Return the unique ID for this model.
static double	getInitialLearningRate(int modelId) Returns the initial learning rate, or -1 for file versions below RFV5.
static RLink	getInstance() Deprecated. use static methods instead.
static java.lang.String	getMetadata(int modelId) Returns the notes (meta-data) of the model.
static double	getMissingInfoLimit(int modelId)
static double	getNegativeTaper(int modelId)
static double	getNorm(int modelId)
static double	getPositiveTaper(int modelId)
static int	getPrecisionBits(int modelId) Returns number of precision bits, or -1 for file versions below RFV5.
static int	getSkippedCount(int modelId) Skipped count is applicable only for TAPER subset training mode.
static RLink.SubsetTrainMode	getSubsetTrainMode(int modelId)
static RLink.ThermometerType	getThermometerType(int modelId) Returns the thermometer type, or throws exception for file versions below RFV5 (thermometer type is -1, which is invalid).
static double	getThreshold(int modelId) Return the threshold for this model.
static int	getTrainedCount(int modelId) Trained count is applicable only for TAPER subset training mode.
static double[]	getTrueInsertScores(int modelId)
static double[]	getTrueRemoveLimits(int modelId)
static java.lang.String	getVersion(int modelId) Return the version ID for this model.
static void	learn(int modelId, double[] featureValues, boolean label) Trains the existing model with the given training example (feature vector and label).
static RLinkOut	predict(int modelId, double[] featureValues) Predicts the score (and label) using default options.
static RLinkOut	predict(int modelId, double[] featureValues, PredictOptions predictOpts) Predicts the score (and label), calculates the requested confidence and significance.
static int	read(java.lang.String fileName) Loads a model from file.
static void	setAnnealingRate(int modelId, double value) Sets the annealing rate (the speed of the learning rate decrease with each training iteration).
static void	setDynamic(int modelId, double[] trueInsertScores, double[] falseInsertScores, double[] trueRemoveLimits, double[] falseRemoveLimits) Sets parameters for removal and insertion of scores to generate related training vectors when using SubsetTrainMode.DYNAMIC.
static void	setHeader(java.lang.String in_file, java.lang.String out_file, java.lang.String meta_data, java.lang.String version, double threshold) Copy a model file, updating the header values.
static void	setID(int modelId, java.lang.String id) Set the ID of the model.
static void	setMetadata(int modelId, java.lang.String metadata) Sets the notes (meta-data) field for an existing model.
static void	setMissingInfoLimit(int modelId, double value) Sets the percentage of values that may be missing in a generated training example for a subset.
static void	setSubsetTrainMode(int modelId, RLink.SubsetTrainMode stMode) Set the subset training mode to an existing model.
static void	setTaper(int modelId, double positiveTaper, double negativeTaper) Set parameters for the tapering function that generates examples for subsets.
static void	setThreshold(int modelId, double threshold) Set the cutoff threshold for the model.
static void	setVersion(int modelId, java.lang.String version) Set the version ID of the model.
static void	verifyMissingInfoLimit(double value)
static void	verifyModelId(int modelId) Verifies that the model with the given modelId actually exists.
static void	verifyTaper(double positiveTaper, double negativeTaper)
static void	write(int modelId, java.lang.String fileName) Saves the existing model to file.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_SCORE

public static final double EMPTY_SCORE

The value -1 used for the empty feature score (when it cannot be calculated).

See Also:

Constant Field Values

MIN_SCORE

public static final double MIN_SCORE

The minimum non-empty feature score, and the minimum model score (0).

See Also:

Constant Field Values

MAX_SCORE

public static final double MAX_SCORE

The maximum non-empty feature score, and the maximum model score (1).

See Also:

Constant Field Values

NO_CONFIDENCE_MEASURE

public static final double NO_CONFIDENCE_MEASURE

The value returned if no confidence measure was calculated or if the requested confidence measure is not supported by the given model.

See Also:

Constant Field Values

Method Detail

getInstance

@Deprecated
public static RLink getInstance()

Deprecated. use static methods instead.

Returns:

the singleton instance of RLink.

finalize

protected void finalize()

Provided for safety, but client code must call destroyModels() explicitly.

Overrides:

finalize in class java.lang.Object

destroyModels

public static void destroyModels()

Destroys all RLink models created by the RLink singleton object. No error codes are used, so this native method is public. Client code must call destroyModels when RLink class will no longer be used

verifyModelId

public static void verifyModelId(int modelId)

Verifies that the model with the given modelId actually exists.

Parameters:

modelId - - ID of the model that was created or read from file.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the model with the given modelId does not exist

createModel

public static int createModel(int nFeatures,
                              double p,
                              double learningRate,
                              int precisionBits,
                              RLink.ThermometerType thermometerType,
                              int[] falseSubsets)

Creates a new untrained RLink model. ModelConfig.build() must be used from other packages.

Parameters:

nFeatures - - number of model features.

p - - Minkowski norm value for combining feature values.

learningRate - - the learning rate.

precisionBits - - defines precision of internal model weights.

thermometerType - - thermometers used by model. Use ARRAY.

falseSubsets - - subsets that are always false. May be null.

Returns:

the index of the new model

setSubsetTrainMode

public static void setSubsetTrainMode(int modelId,
                                      RLink.SubsetTrainMode stMode)

Set the subset training mode to an existing model. If this call is not used, the default subset training mode is TAPER. For model creation, this is typically set in ModelConfig. If model is read from file, subset training mode is set to default. This method can be used to change it before any further training of the loaded model.

Parameters:

modelId - - ID of the model that was created or read from file.

stMode - - the new subset training mode. Not null.

getSubsetTrainMode

public static RLink.SubsetTrainMode getSubsetTrainMode(int modelId)

Returns:

the subset training mode of an existing model.

verifyTaper

public static void verifyTaper(double positiveTaper,
                               double negativeTaper)

Throws:

java.lang.IllegalArgumentException - if any taper value is not between 0 and 1.

setTaper

public static void setTaper(int modelId,
                            double positiveTaper,
                            double negativeTaper)

Set parameters for the tapering function that generates examples for subsets. This is only relevant when SubsetTrainMode.TAPER is used. Larger taper values result in more generated examples being skipped. For model creation, this is typically set in ModelConfig. If model is read from file, taper values are set to default. This method can be used to change them before any further training of the loaded model.

Parameters:

modelId - - ID of the model that was created or read from file.

positiveTaper - - steepness of tapering function for examples with True labels.

negativeTaper - - steepness of tapering function for examples with False labels.

Throws:

java.lang.IllegalArgumentException - if any taper value is not between 0 and 1.

getPositiveTaper

public static double getPositiveTaper(int modelId)

Returns:

the tapering value for true-labeled items

getNegativeTaper

public static double getNegativeTaper(int modelId)

Returns:

the tapering value for false-labeled items

verifyMissingInfoLimit

public static void verifyMissingInfoLimit(double value)

Throws:

java.lang.IllegalArgumentException - if the missing info limit is not between 0 and 1.

setMissingInfoLimit

public static void setMissingInfoLimit(int modelId,
                                       double value)

Sets the percentage of values that may be missing in a generated training example for a subset. This is only relevant when SubsetTrainMode.FIXED is used. For model creation, this is typically set in ModelConfig. If model is read from file, missing info limit is set to default. This method can be used to change it before any further training of the loaded model.

Parameters:

modelId - - ID of the model that was created or read from file.

value - - percentage of values that may be missing in a generated example.

Throws:

java.lang.IllegalArgumentException - if the missing info limit is not between 0 and 1 or the modelId is invalid.

getMissingInfoLimit

public static double getMissingInfoLimit(int modelId)

Parameters:

modelId - - ID of the model that was created or read from file.

Returns:

the percentage of values that may be missing in a generated training example for a subset. This is only relevant when the model was trained in SubsetTrainMode.FIXED mode.

Throws:

java.lang.IllegalArgumentException - if the modelId is invalid.

java.lang.IllegalStateException - if model was not trained in SubsetTrainMode.FIXED mode.

setDynamic

public static void setDynamic(int modelId,
                              double[] trueInsertScores,
                              double[] falseInsertScores,
                              double[] trueRemoveLimits,
                              double[] falseRemoveLimits)

Sets parameters for removal and insertion of scores to generate related training vectors when using SubsetTrainMode.DYNAMIC. For model creation this is typically set in STDynamic. This method can be used to change the parameters before any further training of the loaded model.

Parameters:

modelId - - ID of the model that was created or read from file.

trueInsertScores - - Score to insert into true-labeled vectors when filling in a missing score. This score should be close to 1.0. Must be between 0.0 and 1.0, or RL_DYN_NO_INSERT, or RL_DYN_INSERT_DEFAULT

falseInsertScores - - Score to insert into false-labeled vectors when filling in a missing score. This score should be close to 0.0. Must be between 0.0 and 1.0, or RL_DYN_NO_INSERT, or RL_DYN_INSERT_DEFAULT

trueRemoveLimits - - Scores above this value will not be removed from true-labeled vectors. It is recommended this be no higher than 0.75. Must be between 0.0 and 1.0, or RL_DYN_NO_REMOVE.

falseRemoveLimits - - Scores below this value will not be removed from false-labeled vectors. It is recommended this be no lower than 0.50. Must be between 0.0 and 1.0, or RL_DYN_NO_REMOVE.

Throws:

java.lang.IllegalArgumentException - if length of any given array does not match the number of features for this model, or an array contains an invalid value.

java.lang.ArrayIndexOutOfBoundsException - if modelId is invalid.

getTrueInsertScores

public static double[] getTrueInsertScores(int modelId)

Returns:

the scores to insert into true-labeled vectors when filling in a missing score.

getFalseInsertScores

public static double[] getFalseInsertScores(int modelId)

Returns:

the scores to insert into false-labeled vectors when filling in a missing score.

getTrueRemoveLimits

public static double[] getTrueRemoveLimits(int modelId)

Returns:

the scores above which values will not be removed from true-labeled vectors

getFalseRemoveLimits

public static double[] getFalseRemoveLimits(int modelId)

Returns:

the scores below which values will not be removed from false-labeled vectors

write

public static void write(int modelId,
                         java.lang.String fileName)
                  throws java.io.IOException

Saves the existing model to file. Uses the same format as the file that was read.

Parameters:

modelId - - ID of the model that was created or read from file.

fileName - - name of model binary file.

Throws:

java.lang.IllegalArgumentException - if fileName is null.

java.io.IOException

read

public static int read(java.lang.String fileName)
                throws java.io.FileNotFoundException

Loads a model from file. Default values are set to subset train mode, positive and negative taper, and missing info limit. See description of ModelConfig class for default values.

Parameters:

fileName - - name of model binary file.

Returns:

the index of the newly loaded model

Throws:

java.io.FileNotFoundException - if the specified model file does not exist.

java.lang.IllegalArgumentException - if fileName is null.

setHeader

public static void setHeader(java.lang.String in_file,
                             java.lang.String out_file,
                             java.lang.String meta_data,
                             java.lang.String version,
                             double threshold)

Copy a model file, updating the header values. This copies a model file from one location to another, updating one or more of the header values. It is much faster than loading the model into memory and then writing the model out. The fastest way to update header values is to use this method to copy the file, delete the old and then rename the new file to the old name.

Parameters:

in_file - path to input file.

out_file - path to output file.

meta_data - new meta data value for header. If null meta data is not updated.

version - new version value for header. If null version is not updated.

threshold - new threshold value for header. If negative threshold is not updated.

Throws:

java.lang.IllegalArgumentException - on any errors reading or writing the files.

java.lang.NullPointerException - if a required argument is null or on other errors.

setMetadata

public static void setMetadata(int modelId,
                               java.lang.String metadata)

Sets the notes (meta-data) field for an existing model.

Parameters:

modelId - - ID of the model that was created or read from file.

metadata - - the text of meta-data. May be null to clear meta-data.

getMetadata

public static java.lang.String getMetadata(int modelId)

Returns the notes (meta-data) of the model.

Parameters:

modelId - - ID of the model that was created or read from file.

Returns:

notes (meta-data) from an existing model.

getThreshold

public static double getThreshold(int modelId)

Return the threshold for this model. If no threshold was set for this model -1.0 is returned.

Parameters:

modelId - - ID of the model that was created or read from file.

Returns:

the threshold value for this model.

setThreshold

public static void setThreshold(int modelId,
                                double threshold)

Set the cutoff threshold for the model.

Parameters:

modelId - - ID of the model that was created or read from file.

threshold - - the threshold value for this model. Currently it is not restricted to the range [0; 1].

getVersion

public static java.lang.String getVersion(int modelId)

Return the version ID for this model.

Parameters:

modelId - - ID of the model that was created or read from file.

Returns:

the version string for this model, or null if it is not set.

setVersion

public static void setVersion(int modelId,
                              java.lang.String version)

Set the version ID of the model.

Parameters:

modelId - - ID of the model that was created or read from file.

version - - version ID as a string. This should not be null.

getID

public static java.lang.String getID(int modelId)

Return the unique ID for this model.

Parameters:

modelId - - ID of the model that was created or read from file.

Returns:

the ID string for this model, or null if it is not set.

setID

public static void setID(int modelId,
                         java.lang.String id)

Set the ID of the model.

Parameters:

modelId - - ID of the model that was created or read from file.

id - - unique ID. This should not be null.

getSkippedCount

public static int getSkippedCount(int modelId)

Skipped count is applicable only for TAPER subset training mode. This parameter is reset to 0 after a model has been loaded from file.

Parameters:

modelId - - ID of the model that was created or read from file.

Returns:

the number of generated examples that were skipped during learning.

getTrainedCount

public static int getTrainedCount(int modelId)

Trained count is applicable only for TAPER subset training mode. This parameter is reset to 0 after a model has been loaded from file.

Parameters:

modelId - - ID of the model that was created or read from file.

Returns:

the number of generated examples that were used (not skipped) during learning.

getFeatureCount

public static int getFeatureCount(int modelId)

Gets the number of model features.

Parameters:

modelId - - ID of the model that was created or read from file.

Returns:

the number of features in the specified model.

getNorm

public static double getNorm(int modelId)

Returns:

the Minkowski norm value for combining feature values used by the specified model.

getPrecisionBits

public static int getPrecisionBits(int modelId)

Returns number of precision bits, or -1 for file versions below RFV5.

Returns:

the precision of internal model weights of the specified model.

getInitialLearningRate

public static double getInitialLearningRate(int modelId)

Returns the initial learning rate, or -1 for file versions below RFV5.

Returns:

the initial learning rate of the specified model.

setAnnealingRate

public static void setAnnealingRate(int modelId,
                                    double value)

Sets the annealing rate (the speed of the learning rate decrease with each training iteration).

Parameters:

value - - the annealing rate. Larger values decrease the learning rate faster. 0 means learning rate stays the same.

getThermometerType

public static RLink.ThermometerType getThermometerType(int modelId)

Returns the thermometer type, or throws exception for file versions below RFV5 (thermometer type is -1, which is invalid).

Returns:

the thermometer type used by the specified model.

Throws:

java.lang.IllegalArgumentException - for file versions below RFV5.

predict

public static RLinkOut predict(int modelId,
                               double[] featureValues,
                               PredictOptions predictOpts)

Predicts the score (and label), calculates the requested confidence and significance.

Parameters:

modelId - ID of the model that was created or read from file.

featureValues - - the feature vector.

predictOpts - - the options to use for this prediction. If null, uses default uptions.

Returns:

prediction from the existing model of the given feature vector.

predict

public static RLinkOut predict(int modelId,
                               double[] featureValues)

Predicts the score (and label) using default options. See predict(int, double[], PredictOptions).

learn

public static void learn(int modelId,
                         double[] featureValues,
                         boolean label)

Trains the existing model with the given training example (feature vector and label).

Parameters:

modelId - - ID of the model to be trained

featureValues - - the feature vector.

label - - the actual label to be learned for this feature vector.

beginIteration

public static void beginIteration(int modelId)

Must be called before each training iteration with the entire training dataset.

Parameters:

modelId - - ID of the model being trained.

endIteration

public static void endIteration(int modelId)

Must be called after each training iteration with the entire training dataset.

Parameters:

modelId - - ID of the model being trained.