LBJ2.learn
Class Learner

java.lang.Object
  LBJ2.classify.Classifier
      LBJ2.learn.Learner

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

AdaBoost, LinearThresholdUnit, MuxLearner, NaiveBayes, SparseMIRA, SparseNetworkLearner, StochasticGradientDescent, SupportVectorMachine, WekaWrapper

public abstract class Learner
extends Classifier

Extend this class to create a new Classifier that learns to mimic one an oracle classifier given a feature extracting classifier and example objects.

See Also:

Serialized Form

Nested Class Summary

static class

Learner.Parameters Parameters classes are used to hold values for learning algorithm parameters, and all learning algorithm implementations must provide a constructor that takes such an object as input.

Field Summary

protected java.lang.String	encoding The encoding used by this learner's feature lexicon.
protected Classifier	extractor Stores the classifiers used to produce features.
protected Classifier	labeler Stores the classifier used to produce labels.
protected Lexicon	labelLexicon Stores the label Lexicon.
protected java.net.URL	lcFilePath Caches the location of this learner's offline binary representation.
protected java.net.URL	lexFilePath Caches the location of this learner's offline lexicon.
protected Lexicon	lexicon Stores the feature Lexicon.
protected FVector	predictions Stores the set of predictions that this learner will choose from when classifying a new example.
protected boolean	readLexiconOnDemand Informs this learner that it can and should read its feature lexicon on demand.

Fields inherited from class LBJ2.classify.Classifier

containingPackage, name

Constructor Summary

protected	Learner() This constructor is used by the LBJ2 compiler; it should never be called by a programmer.
protected	Learner(java.lang.String n) Initializes the name.
protected	Learner(java.lang.String n, Classifier e) Constructor for unsupervised learning.
protected	Learner(java.lang.String n, Classifier l, Classifier e) Constructor for supervised learning.

Method Summary

FeatureVector	classify(FeatureVector vector) This method makes one or more decisions about a single feature vector, returning those decisions as Features in a vector.
FeatureVector[]	classify(FeatureVector[] vectors) Use this method to make a batch of classification decisions about several objects.
abstract FeatureVector	classify(int[] exampleFeatures, double[] exampleValues) This method makes one or more decisions about a single object, returning those decisions as Features in a vector.
FeatureVector	classify(java.lang.Object example) This method makes one or more decisions about a single object, returning those decisions as Features in a vector.
FeatureVector[]	classify(java.lang.Object[][] e) Use this method to make a batch of classification decisions about several examples.
java.lang.Object	clone() Returns a deep (enough) clone of this learner.
void	countFeatures(Lexicon.CountPolicy policy) Establishes a new feature counting policy for this learner's lexicon.
protected void	createPrediction(int index) If it hasn't been created already, this method will create the prediction feature in predictions associated with the label feature at the given index of labelLexicon.
protected void	createPrediction(Lexicon lex, int index) If it hasn't been created already, this method will create the prediction feature in predictions associated with the label feature at the given index of lex.
Lexicon	demandLexicon() Forces this learner to read in its lexicon representation, but only if the lexicon currently available in this object is empty and the learner has been scheduled to read its lexicon on demand with readLexiconOnDemand(URL).
java.lang.String	discreteValue(FeatureVector vector) Returns the value of the discrete prediction that this learner would make, given a feature vector.
java.lang.String	discreteValue(int[] f, double[] v) Returns the value of the discrete feature that would be returned by this classifier.
java.lang.String	discreteValue(java.lang.Object example) Returns the value of the discrete prediction that this learner would make, given an example.
void	doneLearning() Overridden by subclasses to perform any required post-processing computations after all training examples have been observed through learn(Object) and learn(Object[]).
void	doneWithRound() Called after each round of training.
Learner	emptyClone() Returns a new, emtpy learner into which all of the parameters that control the behavior of the algorithm have been copied.
Feature	featureValue(FeatureVector vector) Returns the classification of the given feature vector as a single feature instead of a FeatureVector.
Feature	featureValue(int[] f, double[] v) Returns the classification of the given example as a single feature instead of a FeatureVector.
Feature	featureValue(java.lang.Object example) Returns the classification of the given example object as a single feature instead of a FeatureVector.
void	forget() Reinitializes the learner to the state it started at before any learning was performed.
java.lang.Object[]	getExampleArray(java.lang.Object example) Converts an example object into an array of arrays representing the example including its labels.
java.lang.Object[]	getExampleArray(java.lang.Object example, boolean training) Converts an example object into an array of arrays representing the example.
Classifier	getExtractor() Returns the extractor.
Classifier	getLabeler() Returns the labeler.
Lexicon	getLabelLexicon() Returns the label lexicon.
Lexicon	getLexicon() Returns the feature lexicon.
Lexicon	getLexiconDiscardCounts() Returns this learner's feature lexicon after discarding any feature counts it may have been storing.
java.net.URL	getLexiconLocation() Returns the lexicon's location.
java.net.URL	getModelLocation() Returns the model's location.
Learner.Parameters	getParameters() Retrieves the parameters that are set in this learner.
int	getPrunedLexiconSize() Returns the size of the lexicon after any pruning that may have taken place or 0 if the lexicon's location isn't known.
void	initialize(int numExamples, int numFeatures) This method is sometimes called before training begins, although it is not guaranteed to be called at all.
void	learn(FeatureVector vector) Trains the learning algorithm given a feature vector as an example.
void	learn(FeatureVector[] examples) Trains the learning algorithm given many feature vectors as examples.
abstract void	learn(int[] exampleFeatures, double[] exampleValues, int[] exampleLabels, double[] labelValues) Trains the learning algorithm given an example formatted as arrays of feature indices, their values, and the example labels.
void	learn(java.lang.Object example) Trains the learning algorithm given an object as an example.
void	learn(java.lang.Object[] examples) Trains the learning algorithm given many objects as examples.
void	read(ExceptionlessInputStream in) Reads the binary representation of a learner with this object's run-time type, overwriting any and all learned or manually specified parameters as well as the label lexicon but without modifying the feature lexicon.
void	read(java.lang.String modelFile, java.lang.String lexFile) Reads the learned function's binary internal represetation including both its model and lexicons from the specified files, overwriting any and all data this object may have already contained.
void	readLabelLexicon(ExceptionlessInputStream in) Reads the initial portion of the model file, including the containing package and name strings, the names of the labeler and extractor, and finally the label lexicon.
static Learner	readLearner(ExceptionlessInputStream in) Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon) from the given stream.
static Learner	readLearner(ExceptionlessInputStream in, boolean whole) Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon), with the option of cutting off the reading process after the label lexicon and before any learned parameters.
static Learner	readLearner(java.lang.String filename) Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon) from the given file.
static Learner	readLearner(java.lang.String filename, boolean whole) Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon), with the option of cutting off the reading process after the label lexicon and before any learned parameters.
static Learner	readLearner(java.net.URL url) Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon) from the given location.
static Learner	readLearner(java.net.URL url, boolean whole) Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon), with the option of cutting off the reading process after the label lexicon and before any learned parameters.
void	readLexicon(java.lang.String filename) Reads the learned function's feature lexicon from the specified file, overwriting the lexicon present in this object, if any.
void	readLexicon(java.net.URL url) Reads the learned function's feature lexicon from the specified location, overwriting the lexicon present in this object, if any.
void	readLexiconOnDemand(java.lang.String file) Prepares this learner to read in its feature lexicon from the specified location on demand; has no effect if this learner already has a non-empty lexicon.
void	readLexiconOnDemand(java.net.URL url) Prepares this learner to read in its feature lexicon from the specified location on demand; has no effect if this learner already has a non-empty lexicon.
void	readModel(java.lang.String filename) Reads only the learned function's model and label lexicon from the specified file in binary form, overwriting whatever model data may have already existed in this object.
void	readModel(java.net.URL url) Reads only the learned function's model and label lexicon from the specified location in binary form, overwriting whatever model data may have already existed in this object.
static Learner.Parameters	readParameters(java.net.URL url) Deserializes a Learner.Parameters object out of the specified locaiton.
double	realValue(FeatureVector vector) Returns the value of the real prediction that this learner would make, given a feature vector.
double	realValue(int[] f, double[] v) Returns the value of the real feature that would be returned by this classifier.
double	realValue(java.lang.Object example) Returns the value of the real prediction that this learner would make, given an example.
void	save() Writes the binary representation of this learned function if there is a location cached in lcFilePath, and writes the binary representation of the feature lexicon if there is a location cached in lexFilePath.
void	saveLexicon() Writes the binary representation of the feature lexicon to the location specified by lexFilePath.
void	saveModel() Writes the binary representation of this learned function to the location specified by lcFilePath.
ScoreSet	scores(FeatureVector vector) Produces a set of scores indicating the degree to which each possible discrete classification value is associated with the given feature vector.
abstract ScoreSet	scores(int[] exampleFeatures, double[] exampleValues) Produces a set of scores indicating the degree to which each possible discrete classification value is associated with the given example object.
ScoreSet	scores(java.lang.Object example) Produces a set of scores indicating the degree to which each possible discrete classification value is associated with the given example object.
void	setEncoding(java.lang.String e) Sets the encoding to use in this learner's feature lexicon.
void	setExtractor(Classifier e) Sets the extractor.
void	setLabeler(Classifier l) Sets the labeler.
void	setLabelLexicon(Lexicon l) Sets the label lexicon.
void	setLexicon(Lexicon l) Sets the feature lexicon.
void	setLexiconLocation(java.lang.String p) Sets the location of the lexicon as a regular file on this file system.
void	setLexiconLocation(java.net.URL u) Sets the location of the model as a URL.
void	setModelLocation(java.lang.String p) Sets the location of the model as a regular file on this file system.
void	setModelLocation(java.net.URL u) Sets the location of the model as a URL.
void	setParameters(Learner.Parameters p) Sets the values of parameters that control the behavior of this learning algorithm.
void	unclone() Automatically generated code will override this method to set their isClone field to false.
void	write(ExceptionlessOutputStream out) Writes the learned function's internal representation in binary form.
abstract void	write(java.io.PrintStream out) Writes the learned function's internal representation as text.
void	write(java.lang.String modelFile, java.lang.String lexFile) Writes the learned function's binary internal represetation including both its model and lexicons to the specified files.
void	writeLexicon(java.lang.String filename) Writes the learned function's feature lexicon to the specified file.
void	writeModel(java.lang.String filename) Writes only the learned function's model (which includes the label lexicon) to the specified file in binary form.
static void	writeParameters(Learner.Parameters p, java.lang.String file) Serializes a Learner.Parameters object to the specified file.

Methods inherited from class LBJ2.classify.Classifier

allowableValues, classify, discreteValueArray, getCompositeChildren, getInputType, getOutputType, realValueArray, test, toString, valueIndexOf

Methods inherited from class java.lang.Object

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

Field Detail

labeler

protected Classifier labeler

Stores the classifier used to produce labels.

extractor

protected Classifier extractor

Stores the classifiers used to produce features.

lexicon

protected Lexicon lexicon

Stores the feature Lexicon.

labelLexicon

protected Lexicon labelLexicon

Stores the label Lexicon.

encoding

protected java.lang.String encoding

The encoding used by this learner's feature lexicon.

predictions

protected FVector predictions

Stores the set of predictions that this learner will choose from when classifying a new example.

lcFilePath

protected java.net.URL lcFilePath

Caches the location of this learner's offline binary representation.

lexFilePath

protected java.net.URL lexFilePath

Caches the location of this learner's offline lexicon.

readLexiconOnDemand

protected boolean readLexiconOnDemand

Informs this learner that it can and should read its feature lexicon on demand.

Constructor Detail

Learner

protected Learner()

This constructor is used by the LBJ2 compiler; it should never be called by a programmer.

Learner

protected Learner(java.lang.String n)

Initializes the name.

Parameters:

n - The name of the classifier.

Learner

protected Learner(java.lang.String n,
                  Classifier e)

Constructor for unsupervised learning.

Parameters:

n - The name of the classifier.

e - The feature extracting classifier.

Learner

protected Learner(java.lang.String n,
                  Classifier l,
                  Classifier e)

Constructor for supervised learning.

Parameters:

n - The name of the classifier.

l - The labeling classifier.

e - The feature extracting classifier.

Method Detail

setParameters

public void setParameters(Learner.Parameters p)

Sets the values of parameters that control the behavior of this learning algorithm.

Parameters:

p - The parameters.

getParameters

public Learner.Parameters getParameters()

Retrieves the parameters that are set in this learner.

setLabeler

public void setLabeler(Classifier l)

Sets the labeler.

Parameters:

l - A labeling classifier.

getLabeler

public Classifier getLabeler()

Returns the labeler.

setExtractor

public void setExtractor(Classifier e)

Sets the extractor.

Parameters:

e - A feature extracting classifier.

getExtractor

public Classifier getExtractor()

Returns the extractor.

setLexicon

public void setLexicon(Lexicon l)

Sets the feature lexicon. If set to null, the JVM's garbage collector is invoked.

Parameters:

l - A feature lexicon.

getLexicon

public Lexicon getLexicon()

Returns the feature lexicon.

setLabelLexicon

public void setLabelLexicon(Lexicon l)

Sets the label lexicon.

Parameters:

l - A feature lexicon.

getLabelLexicon

public Lexicon getLabelLexicon()

Returns the label lexicon.

setEncoding

public void setEncoding(java.lang.String e)

Sets the encoding to use in this learner's feature lexicon.

Parameters:

e - The encoding.

setModelLocation

public void setModelLocation(java.lang.String p)

Sets the location of the model as a regular file on this file system.

Parameters:

p - The file's path.

setModelLocation

public void setModelLocation(java.net.URL u)

Sets the location of the model as a URL.

Parameters:

u - The model's location.

getModelLocation

public java.net.URL getModelLocation()

Returns the model's location.

setLexiconLocation

public void setLexiconLocation(java.lang.String p)

Sets the location of the lexicon as a regular file on this file system.

Parameters:

p - The file's path.

setLexiconLocation

public void setLexiconLocation(java.net.URL u)

Sets the location of the model as a URL.

Parameters:

u - The model's location.

getLexiconLocation

public java.net.URL getLexiconLocation()

Returns the lexicon's location.

countFeatures

public void countFeatures(Lexicon.CountPolicy policy)

Establishes a new feature counting policy for this learner's lexicon.

Parameters:

policy - The new feature counting policy.

getLexiconDiscardCounts

public Lexicon getLexiconDiscardCounts()

Returns this learner's feature lexicon after discarding any feature counts it may have been storing. This method is likely only useful when the lexicon and its counts are currently stored on disk and readLexiconOnDemand(String) or readLexiconOnDemand(URL) has already been called, in which case the lexicon is read from disk without wasting time loading the counts.

emptyClone

public Learner emptyClone()

Returns a new, emtpy learner into which all of the parameters that control the behavior of the algorithm have been copied. Here, "emtpy" means no learning has taken place.

learn

public void learn(java.lang.Object example)

Trains the learning algorithm given an object as an example. By default, this simply converts the example object into arrays and passes it to learn(int[],double[],int[],double[]).

Parameters:

example - An example of the desired learned classifier's behavior.

learn

public void learn(FeatureVector vector)

Trains the learning algorithm given a feature vector as an example. This simply converts the example object into arrays and passes it to learn(int[],double[],int[],double[]).

Parameters:

vector - An example of the desired learned classifier's behavior.

learn

public abstract void learn(int[] exampleFeatures,
                           double[] exampleValues,
                           int[] exampleLabels,
                           double[] labelValues)

Trains the learning algorithm given an example formatted as arrays of feature indices, their values, and the example labels.

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

exampleLabels - The example's label(s).

labelValues - The values of the labels.

learn

public void learn(java.lang.Object[] examples)

Trains the learning algorithm given many objects as examples. This implementation simply calls learn(Object) on each of the objects in the input array and finishes by calling doneLearning(). It should be overridden if there is a more efficient implementation.

Parameters:

examples - Examples of the desired learned classifier's behavior.

learn

public void learn(FeatureVector[] examples)

Trains the learning algorithm given many feature vectors as examples. This implementation simply calls learn(FeatureVector) on each of the vectors in the input array and finishes by calling doneLearning(). It should be overridden if there is a more efficient implementation.

Parameters:

examples - Examples of the desired learned classifier's behavior.

classify

public FeatureVector classify(java.lang.Object example)

This method makes one or more decisions about a single object, returning those decisions as Features in a vector.

Specified by:

classify in class Classifier

Parameters:

example - The object to make decisions about.

Returns:

A vector of Features about the input object.

classify

public FeatureVector classify(FeatureVector vector)

This method makes one or more decisions about a single feature vector, returning those decisions as Features in a vector.

Parameters:

vector - The vector to make decisions about.

Returns:

A vector of Features about the input vector.

classify

public abstract FeatureVector classify(int[] exampleFeatures,
                                       double[] exampleValues)

This method makes one or more decisions about a single object, returning those decisions as Features in a vector.

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

Returns:

A vector of Features about the input object.

classify

public FeatureVector[] classify(FeatureVector[] vectors)

Use this method to make a batch of classification decisions about several objects. This function is implemented in the most naive way (simply calling classify(FeatureVector) repeatedly) and should be overridden if there is a more efficient implementation.

Parameters:

vectors - The vectors to make decisions about.

Returns:

An array of feature vectors, one per input vector.

classify

public FeatureVector[] classify(java.lang.Object[][] e)

Use this method to make a batch of classification decisions about several examples. This function is implemented in the most naive way (simply calling classify(int[],double[]) repeatedly) and should be overridden if there is a more efficient implementation.

Parameters:

e - The examples to make decisions about, represented as arrays of indices and strengths.

Returns:

An array of feature vectors, one per input object.

featureValue

public Feature featureValue(java.lang.Object example)

Returns the classification of the given example object as a single feature instead of a FeatureVector.

Overrides:

featureValue in class Classifier

Parameters:

example - The object to classify.

Returns:

The classification of example as a feature.

featureValue

public Feature featureValue(FeatureVector vector)

Returns the classification of the given feature vector as a single feature instead of a FeatureVector.

Parameters:

vector - The vector to classify.

Returns:

The classification of vector as a feature.

featureValue

public Feature featureValue(int[] f,
                            double[] v)

Returns the classification of the given example as a single feature instead of a FeatureVector.

Parameters:

f - The features array.

v - The values array.

Returns:

The classification of o as a feature.

discreteValue

public java.lang.String discreteValue(java.lang.Object example)

Returns the value of the discrete prediction that this learner would make, given an example.

Overrides:

discreteValue in class Classifier

Parameters:

example - The example object.

Returns:

The discrete value.

discreteValue

public java.lang.String discreteValue(FeatureVector vector)

Returns the value of the discrete prediction that this learner would make, given a feature vector.

Parameters:

vector - The example vector.

Returns:

The discrete value.

discreteValue

public java.lang.String discreteValue(int[] f,
                                      double[] v)

Returns the value of the discrete feature that would be returned by this classifier. This method should only be called when overridden by a classifier returning a single discrete feature.

Parameters:

f - The features array.

v - The values array.

Returns:

The value of the feature produced for the input object.

realValue

public double realValue(java.lang.Object example)

Returns the value of the real prediction that this learner would make, given an example.

Overrides:

realValue in class Classifier

Parameters:

example - The example object.

Returns:

The real value.

realValue

public double realValue(FeatureVector vector)

Returns the value of the real prediction that this learner would make, given a feature vector.

Parameters:

vector - The example vector.

Returns:

The real value.

realValue

public double realValue(int[] f,
                        double[] v)

Returns the value of the real feature that would be returned by this classifier. This method should only be called when overridden by a classifier returning a single real feature.

Parameters:

f - The features array.

v - The values array.

Returns:

The value of the feature produced for the input object.

doneLearning

public void doneLearning()

Overridden by subclasses to perform any required post-processing computations after all training examples have been observed through learn(Object) and learn(Object[]). By default this method does nothing.

initialize

public void initialize(int numExamples,
                       int numFeatures)

This method is sometimes called before training begins, although it is not guaranteed to be called at all. It allows the number of examples and number of features to be passed to the Learner, in case this information is available, such as after pre-extraction. By default this method does nothing.

Parameters:

numExamples - The number of examples that will be observed during training.

numFeatures - The number of features that will be observed during training.

doneWithRound

public void doneWithRound()

Called after each round of training. Does nothing by default.

getExampleArray

public java.lang.Object[] getExampleArray(java.lang.Object example)

Converts an example object into an array of arrays representing the example including its labels. The first array contains the integer keys of the example's features, as indexed in the lexicon. The second array gives the double values corresponding to the strengths of the features in the first array. The third and fourth arrays play the same roles as the first and second arrays respectively, except they describe the labels.

Parameters:

example - The example object.

Returns:

The converted example array.

getExampleArray

public java.lang.Object[] getExampleArray(java.lang.Object example,
                                          boolean training)

Converts an example object into an array of arrays representing the example. The first array contains the integer keys of the example's features, as indexed in the lexicon. The second array gives the double values corresponding to the strengths of the features in the first array. The third and fourth arrays will only be present if training is set to true. They play the same roles as the first and second arrays respectively, except they describe the labels.

Parameters:

example - The example object.

training - Whether or not labels should be extracted.

Returns:

The converted example array.

createPrediction

protected void createPrediction(int index)

If it hasn't been created already, this method will create the prediction feature in predictions associated with the label feature at the given index of labelLexicon. This method does not create RealFeatures in predictions since their strengths cannot be modified. In association with DiscreteFeatures it creates a DiscretePrimitiveStringFeature with an empty identifier. Its value, valueIndex, and totalValues fields are filled by calling the label feature's getStringValue(), getValueIndex(), and totalValues() methods respectively.

Parameters:

index - The index of a label feature in labelLexicon.

createPrediction

protected void createPrediction(Lexicon lex,
                                int index)

If it hasn't been created already, this method will create the prediction feature in predictions associated with the label feature at the given index of lex. This method does not create RealFeatures in predictions since their strengths cannot be modified. In association with DiscreteFeatures it creates a DiscretePrimitiveStringFeature with an empty identifier. Its value, valueIndex, and totalValues fields are filled by calling the label feature's getStringValue(), getValueIndex(), and totalValues() methods respectively.

Parameters:

lex - The label lexicon to associate prediction features with.

index - The index of a label feature in lex.

forget

public void forget()

Reinitializes the learner to the state it started at before any learning was performed. By default, this sets the lexicons to blank Lexicon objects and calls initialize(int,int) to reset the number of examples and features to 0, for learners that use this.

scores

public ScoreSet scores(java.lang.Object example)

Produces a set of scores indicating the degree to which each possible discrete classification value is associated with the given example object. Learners that return a real feature or more than one feature may implement this method by simply returning null.

Parameters:

example - The object to make decisions about.

Returns:

A set of scores indicating the degree to which each possible discrete classification value is associated with the given example object.

scores

public ScoreSet scores(FeatureVector vector)

Produces a set of scores indicating the degree to which each possible discrete classification value is associated with the given feature vector. Learners that return a real feature or more than one feature may implement this method by simply returning null.

Parameters:

vector - The vector to make decisions about.

Returns:

A set of scores indicating the degree to which each possible discrete classification value is associated with the given example vector.

scores

public abstract ScoreSet scores(int[] exampleFeatures,
                                double[] exampleValues)

Produces a set of scores indicating the degree to which each possible discrete classification value is associated with the given example object. Learners that return a real feature or more than one feature may implement this method by simply returning null.

Parameters:

exampleFeatures - The example's array of feature indices

exampleValues - The example's array of values

Returns:

A set of scores indicating the degree to which each possible discrete classification value is associated with the given example object.

write

public abstract void write(java.io.PrintStream out)

Writes the learned function's internal representation as text.

Parameters:

out - The output stream.

unclone

public void unclone()

Automatically generated code will override this method to set their isClone field to false. This then allows a pure java program to read a learner's representation into any instance of the learner's class. By default, this method does nothing.

getPrunedLexiconSize

public int getPrunedLexiconSize()

Returns the size of the lexicon after any pruning that may have taken place or 0 if the lexicon's location isn't known.

clone

public java.lang.Object clone()

Returns a deep (enough) clone of this learner. The following fields are cloned themselves: lexicon, labelLexicon, and predictions.

Note that this is an overriding implementation of Object's clone() method, and its functionality is completely separate from and unrelated to that of this class's unclone() method.

Overrides:

clone in class Classifier

Returns:

A shallow clone.

save

public void save()

Writes the binary representation of this learned function if there is a location cached in lcFilePath, and writes the binary representation of the feature lexicon if there is a location cached in lexFilePath.

saveModel

public void saveModel()

Writes the binary representation of this learned function to the location specified by lcFilePath. If lcFilePath is not set, this method will produce an error message and exit the program.

saveLexicon

public void saveLexicon()

Writes the binary representation of the feature lexicon to the location specified by lexFilePath. If lexFilePath is not set, this method will produce an error message and exit the program.

write

public void write(java.lang.String modelFile,
                  java.lang.String lexFile)

Writes the learned function's binary internal represetation including both its model and lexicons to the specified files. These files are then cached in lcFilePath and lexFilePath.

Parameters:

modelFile - The name of the file in which to write the model.

lexFile - The name of the file in which to write the feature lexicon.

writeModel

public void writeModel(java.lang.String filename)

Writes only the learned function's model (which includes the label lexicon) to the specified file in binary form. This file is then cached in lcFilePath.

Parameters:

filename - The name of the file in which to write the model.

writeLexicon

public void writeLexicon(java.lang.String filename)

Writes the learned function's feature lexicon to the specified file. This file is then cached in lexFilePath.

Parameters:

filename - The name of the file in which to write the feature lexicon.

write

public void write(ExceptionlessOutputStream out)

Writes the learned function's internal representation in binary form.

Parameters:

out - The output stream.

read

public void read(java.lang.String modelFile,
                 java.lang.String lexFile)

Reads the learned function's binary internal represetation including both its model and lexicons from the specified files, overwriting any and all data this object may have already contained. These files are then cached in lcFilePath and lexFilePath.

Parameters:

modelFile - The name of the file from which to read the model.

lexFile - The name of the file from which to read the feature lexicon.

readModel

public void readModel(java.lang.String filename)

Reads only the learned function's model and label lexicon from the specified file in binary form, overwriting whatever model data may have already existed in this object. This file is then cached in lcFilePath.

Parameters:

filename - The name of the file from which to read the model.

readModel

public void readModel(java.net.URL url)

Reads only the learned function's model and label lexicon from the specified location in binary form, overwriting whatever model data may have already existed in this object. This location is then cached in lcFilePath.

Parameters:

url - The location from which to read the model.

readLexicon

public void readLexicon(java.lang.String filename)

Reads the learned function's feature lexicon from the specified file, overwriting the lexicon present in this object, if any. This file is then cached in lexFilePath.

Parameters:

filename - The name of the file from which to read the feature lexicon.

readLexicon

public void readLexicon(java.net.URL url)

Reads the learned function's feature lexicon from the specified location, overwriting the lexicon present in this object, if any. This location is then cached in lexFilePath.

Parameters:

url - The location from which to read the feature lexicon.

readLearner

public static Learner readLearner(java.lang.String filename)

Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon) from the given file. In that file, there should first be stored a string containing the fully qualified class name of the learner. If the short value -1 appears instead, this method returns null.

This method is appropriate for reading learners as written by write(ExceptionlessOutputStream).

Parameters:

filename - The name of the file from which to read the learner.

Returns:

The learner read from the file.

readLearner

public static Learner readLearner(java.lang.String filename,
                                  boolean whole)

Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon), with the option of cutting off the reading process after the label lexicon and before any learned parameters. When whole is false, the reading process is cut off in this way.

This method is appropriate for reading learners as written by write(ExceptionlessOutputStream).

Parameters:

filename - The name of the file from which to read the learner.

whole - Whether or not to read the whole model.

Returns:

The learner read from the file.

readLearner

public static Learner readLearner(java.net.URL url)

Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon) from the given location. At that location, there should first be stored a string containing the fully qualified class name of the learner. If the short value -1 appears instead, this method returns null. Finally, the location is cached in lcFilePath.

This method is appropriate for reading learners as written by write(ExceptionlessOutputStream).

Parameters:

url - The location from which to read the learner.

Returns:

The learner read from the location.

readLearner

public static Learner readLearner(java.net.URL url,
                                  boolean whole)

Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon), with the option of cutting off the reading process after the label lexicon and before any learned parameters. When whole is false, the reading process is cut off in this way. Finally, the location is cached in lcFilePath.

This method is appropriate for reading learners as written by write(ExceptionlessOutputStream).

Parameters:

url - The location from which to read the learner.

whole - Whether or not to read the whole model.

Returns:

The learner read from the location.

readLearner

public static Learner readLearner(ExceptionlessInputStream in)

Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon) from the given stream. The stream is expected to first return a string containing the fully qualified class name of the learner. If the short value -1 appears instead, this method returns null.

This method is appropriate for reading learners as written by write(ExceptionlessOutputStream).

Parameters:

in - The input stream.

Returns:

The learner read from the stream.

readLearner

public static Learner readLearner(ExceptionlessInputStream in,
                                  boolean whole)

Reads the binary representation of any type of learner (including the label lexicon, but not including the feature lexicon), with the option of cutting off the reading process after the label lexicon and before any learned parameters. When whole is false, the reading process is cut off in this way.

This method is appropriate for reading learners as written by write(ExceptionlessOutputStream).

Parameters:

in - The input stream.

whole - Whether or not to read the whole model.

Returns:

The learner read from the stream.

read

public void read(ExceptionlessInputStream in)

Reads the binary representation of a learner with this object's run-time type, overwriting any and all learned or manually specified parameters as well as the label lexicon but without modifying the feature lexicon.

Parameters:

in - The input stream.

readLabelLexicon

public void readLabelLexicon(ExceptionlessInputStream in)

Reads the initial portion of the model file, including the containing package and name strings, the names of the labeler and extractor, and finally the label lexicon. This method will not read any further model parameters, however.

Parameters:

in - The input stream.

readLexiconOnDemand

public void readLexiconOnDemand(java.lang.String file)

Prepares this learner to read in its feature lexicon from the specified location on demand; has no effect if this learner already has a non-empty lexicon.

Parameters:

file - The file from which to read the feature lexicon.

readLexiconOnDemand

public void readLexiconOnDemand(java.net.URL url)

Prepares this learner to read in its feature lexicon from the specified location on demand; has no effect if this learner already has a non-empty lexicon.

Parameters:

url - The location from which to read the feature lexicon.

demandLexicon

public Lexicon demandLexicon()

Forces this learner to read in its lexicon representation, but only if the lexicon currently available in this object is empty and the learner has been scheduled to read its lexicon on demand with readLexiconOnDemand(URL).

Returns:

The lexicon just read into lexicon.

See Also:

readLexiconOnDemand

writeParameters

public static void writeParameters(Learner.Parameters p,
                                   java.lang.String file)

Serializes a Learner.Parameters object to the specified file.

Parameters:

p - The parameters to serialize.

file - The file in which to serialize them.

readParameters

public static Learner.Parameters readParameters(java.net.URL url)

Deserializes a Learner.Parameters object out of the specified locaiton.

Parameters:

url - The location from which to read the object.

Returns:

The parameters object.