public class RLink
extends java.lang.Object
| 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.
|
| 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.
|
| 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.
|
public static final double EMPTY_SCORE
public static final double MIN_SCORE
public static final double MAX_SCORE
public static final double NO_CONFIDENCE_MEASURE
@Deprecated public static RLink getInstance()
protected void finalize()
finalize in class java.lang.Objectpublic static void destroyModels()
public static void verifyModelId(int modelId)
modelId - - ID of the model that was created or read from file.java.lang.ArrayIndexOutOfBoundsException - if the model with the given modelId does not existpublic static int createModel(int nFeatures,
double p,
double learningRate,
int precisionBits,
RLink.ThermometerType thermometerType,
int[] falseSubsets)
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.public static void setSubsetTrainMode(int modelId,
RLink.SubsetTrainMode stMode)
modelId - - ID of the model that was created or read from file.stMode - - the new subset training mode. Not null.public static RLink.SubsetTrainMode getSubsetTrainMode(int modelId)
public static void verifyTaper(double positiveTaper,
double negativeTaper)
java.lang.IllegalArgumentException - if any taper value is not between 0 and 1.public static void setTaper(int modelId,
double positiveTaper,
double negativeTaper)
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.java.lang.IllegalArgumentException - if any taper value is not between 0 and 1.public static double getPositiveTaper(int modelId)
public static double getNegativeTaper(int modelId)
public static void verifyMissingInfoLimit(double value)
java.lang.IllegalArgumentException - if the missing info limit is not between 0 and 1.public static void setMissingInfoLimit(int modelId,
double value)
modelId - - ID of the model that was created or read from file.value - - percentage of values that may be missing in a generated example.java.lang.IllegalArgumentException - if the missing info limit is not between 0 and 1
or the modelId is invalid.public static double getMissingInfoLimit(int modelId)
modelId - - ID of the model that was created or read from file.java.lang.IllegalArgumentException - if the modelId is invalid.java.lang.IllegalStateException - if model was not trained in SubsetTrainMode.FIXED mode.public static void setDynamic(int modelId,
double[] trueInsertScores,
double[] falseInsertScores,
double[] trueRemoveLimits,
double[] falseRemoveLimits)
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_DEFAULTfalseInsertScores - - 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_DEFAULTtrueRemoveLimits - - 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.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.public static double[] getTrueInsertScores(int modelId)
public static double[] getFalseInsertScores(int modelId)
public static double[] getTrueRemoveLimits(int modelId)
public static double[] getFalseRemoveLimits(int modelId)
public static void write(int modelId,
java.lang.String fileName)
throws java.io.IOException
modelId - - ID of the model that was created or read from file.fileName - - name of model binary file.java.lang.IllegalArgumentException - if fileName is null.java.io.IOExceptionpublic static int read(java.lang.String fileName)
throws java.io.FileNotFoundException
fileName - - name of model binary file.java.io.FileNotFoundException - if the specified model file does not exist.java.lang.IllegalArgumentException - if fileName is null.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)
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.java.lang.IllegalArgumentException - on any errors reading or writing the files.java.lang.NullPointerException - if a required argument is null or on other errors.public static void setMetadata(int modelId,
java.lang.String metadata)
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.public static java.lang.String getMetadata(int modelId)
modelId - - ID of the model that was created or read from file.public static double getThreshold(int modelId)
modelId - - ID of the model that was created or read from file.public static void setThreshold(int modelId,
double threshold)
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].public static java.lang.String getVersion(int modelId)
modelId - - ID of the model that was created or read from file.public static void setVersion(int modelId,
java.lang.String version)
modelId - - ID of the model that was created or read from file.version - - version ID as a string. This should not be null.public static java.lang.String getID(int modelId)
modelId - - ID of the model that was created or read from file.public static void setID(int modelId,
java.lang.String id)
modelId - - ID of the model that was created or read from file.id - - unique ID. This should not be null.public static int getSkippedCount(int modelId)
modelId - - ID of the model that was created or read from file.public static int getTrainedCount(int modelId)
modelId - - ID of the model that was created or read from file.public static int getFeatureCount(int modelId)
modelId - - ID of the model that was created or read from file.public static double getNorm(int modelId)
public static int getPrecisionBits(int modelId)
public static double getInitialLearningRate(int modelId)
public static void setAnnealingRate(int modelId,
double value)
value - - the annealing rate. Larger values decrease the learning rate faster.
0 means learning rate stays the same.public static RLink.ThermometerType getThermometerType(int modelId)
java.lang.IllegalArgumentException - for file versions below RFV5.public static RLinkOut predict(int modelId, double[] featureValues, PredictOptions predictOpts)
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.public static RLinkOut predict(int modelId, double[] featureValues)
predict(int, double[], PredictOptions).public static void learn(int modelId,
double[] featureValues,
boolean label)
modelId - - ID of the model to be trainedfeatureValues - - the feature vector.label - - the actual label to be learned for this feature vector.public static void beginIteration(int modelId)
modelId - - ID of the model being trained.public static void endIteration(int modelId)
modelId - - ID of the model being trained.