LBJ2.learn
Class SparseNetworkLearner

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

MultiLabelLearner

public class SparseNetworkLearner
extends Learner

A SparseNetworkLearner uses multiple LinearThresholdUnits to make a multi-class classification. Any LinearThresholdUnit may be used, so long as it implements its clone() method and a public constructor that takes no arguments.

It is assumed that a single discrete label feature will be produced in association with each example object. A feature taking one of the values observed in that label feature will be produced by the learned classifier.

This algorithm's user-configurable parameters are stored in member fields of this class. They may be set via either a constructor that names each parameter explicitly or a constructor that takes an instance of Parameters as input. The documentation in each member field in this class indicates the default value of the associated parameter when using the former type of constructor. The documentation of the associated member field in the Parameters class indicates the default value of the parameter when using the latter type of constructor.

See Also:

Serialized Form

Nested Class Summary

static class

SparseNetworkLearner.Parameters Simply a container for all of SparseNetworkLearner's configurable parameters.

Field Summary

protected LinearThresholdUnit	baseLTU The underlying algorithm used to learn each class separately as a binary classifier; default defaultBaseLTU.
protected boolean	conjunctiveLabels Whether or not this learner's labeler produces conjunctive features.
static LinearThresholdUnit	defaultBaseLTU Default for baseLTU.
protected OVector	network A collection of the linear threshold units used to learn each label, indexed by the label.
protected int	numExamples The total number of examples in the training data, or 0 if unknown.
protected int	numFeatures The total number of distinct features in the training data, or 0 if unknown.

Fields inherited from class LBJ2.learn.Learner

encoding, extractor, labeler, labelLexicon, lcFilePath, lexFilePath, lexicon, predictions, readLexiconOnDemand

Fields inherited from class LBJ2.classify.Classifier

containingPackage, name

Constructor Summary

SparseNetworkLearner()
Instantiates this multi-class learner with the default learning algorithm: defaultBaseLTU.

SparseNetworkLearner(LinearThresholdUnit ltu)
Instantiates this multi-class learner using the specified algorithm to learn each class separately as a binary classifier.

SparseNetworkLearner(SparseNetworkLearner.Parameters p)
Initializing constructor.

SparseNetworkLearner(java.lang.String n)
Instantiates this multi-class learner with the default learning algorithm: defaultBaseLTU.

SparseNetworkLearner(java.lang.String n, LinearThresholdUnit ltu)
Instantiates this multi-class learner using the specified algorithm to learn each class separately as a binary classifier.

SparseNetworkLearner(java.lang.String n, SparseNetworkLearner.Parameters p)
Initializing constructor.

Method Summary

FeatureVector	classify(int[] exampleFeatures, double[] exampleValues) This implementation uses a winner-take-all comparison of the outputs from the individual linear threshold units' score methods.
java.lang.Object	clone() Returns a deep clone of this learning algorithm.
protected ScoreSet	conjunctiveScores(int[] exampleFeatures, double[] exampleValues, java.util.Iterator I) This method is a surrogate for scores(int[],double[],Collection) when the labeler is known to produce conjunctive features.
protected Feature	conjunctiveValueOf(int[] exampleFeatures, double[] exampleValues, java.util.Iterator I) This method is a surrogate for valueOf(int[],double[],Collection) when the labeler is known to produce conjunctive features.
java.lang.String	discreteValue(int[] exampleFeatures, double[] exampleValues) This implementation uses a winner-take-all comparison of the outputs from the individual linear threshold units' score methods.
void	doneLearning() Simply calls doneLearning() on every LTU in the network.
void	doneWithRound() Simply calls Learner.doneWithRound() on every LTU in the network.
Feature	featureValue(int[] f, double[] v) Returns the classification of the given example as a single feature instead of a FeatureVector.
void	forget() Clears the network.
Learner.Parameters	getParameters() Retrieves the parameters that are set in this learner.
void	initialize(int ne, int nf) Sets the number of examples and features.
void	learn(int[] exampleFeatures, double[] exampleValues, int[] exampleLabels, double[] labelValues) Each example is treated as a positive example for the linear threshold unit associated with the label's value that is active for the example and as a negative example for all other linear threshold units in the network.
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.
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(int[] exampleFeatures, double[] exampleValues, java.util.Collection candidates) Returns scores for only those labels in the given collection.
ScoreSet	scores(java.lang.Object example, java.util.Collection candidates) Returns scores for only those labels in the given collection.
void	setExtractor(Classifier e) Sets the extractor.
void	setLabeler(Classifier l) Sets the labeler.
void	setLTU(LinearThresholdUnit ltu) Sets the baseLTU variable.
void	setParameters(SparseNetworkLearner.Parameters p) Sets the values of parameters that control the behavior of this learning algorithm.
Feature	valueOf(int[] exampleFeatures, double[] exampleValues, java.util.Collection candidates) Using this method, the winner-take-all competition is narrowed to involve only those labels contained in the specified list.
Feature	valueOf(java.lang.Object example, java.util.Collection candidates) Using this method, the winner-take-all competition is narrowed to involve only those labels contained in the specified list.
void	write(ExceptionlessOutputStream out) Writes the learned function's internal representation in binary form.
void	write(java.io.PrintStream out) Writes the algorithm's internal representation as text.

Methods inherited from class LBJ2.learn.Learner

classify, classify, classify, classify, countFeatures, createPrediction, createPrediction, demandLexicon, discreteValue, discreteValue, emptyClone, featureValue, featureValue, getExampleArray, getExampleArray, getExtractor, getLabeler, getLabelLexicon, getLexicon, getLexiconDiscardCounts, getLexiconLocation, getModelLocation, getPrunedLexiconSize, learn, learn, learn, learn, read, readLabelLexicon, readLearner, readLearner, readLearner, readLearner, readLearner, readLearner, readLexicon, readLexicon, readLexiconOnDemand, readLexiconOnDemand, readModel, readModel, readParameters, realValue, realValue, realValue, save, saveLexicon, saveModel, scores, scores, setEncoding, setLabelLexicon, setLexicon, setLexiconLocation, setLexiconLocation, setModelLocation, setModelLocation, setParameters, unclone, write, writeLexicon, writeModel, writeParameters

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

defaultBaseLTU

public static final LinearThresholdUnit defaultBaseLTU

Default for baseLTU.

baseLTU

protected LinearThresholdUnit baseLTU

The underlying algorithm used to learn each class separately as a binary classifier; default defaultBaseLTU.

network

protected OVector network

A collection of the linear threshold units used to learn each label, indexed by the label.

numExamples

protected int numExamples

The total number of examples in the training data, or 0 if unknown.

numFeatures

protected int numFeatures

The total number of distinct features in the training data, or 0 if unknown.

conjunctiveLabels

protected boolean conjunctiveLabels

Whether or not this learner's labeler produces conjunctive features.

Constructor Detail

SparseNetworkLearner

public SparseNetworkLearner()

Instantiates this multi-class learner with the default learning algorithm: defaultBaseLTU.

SparseNetworkLearner

public SparseNetworkLearner(LinearThresholdUnit ltu)

Instantiates this multi-class learner using the specified algorithm to learn each class separately as a binary classifier. This constructor will normally only be called by the compiler.

Parameters:

ltu - The linear threshold unit used to learn binary classifiers.

SparseNetworkLearner

public SparseNetworkLearner(SparseNetworkLearner.Parameters p)

Initializing constructor. Sets all member variables to their associated settings in the SparseNetworkLearner.Parameters object.

Parameters:

p - The settings of all parameters.

SparseNetworkLearner

public SparseNetworkLearner(java.lang.String n)

Instantiates this multi-class learner with the default learning algorithm: defaultBaseLTU.

Parameters:

n - The name of the classifier.

SparseNetworkLearner

public SparseNetworkLearner(java.lang.String n,
                            LinearThresholdUnit ltu)

Instantiates this multi-class learner using the specified algorithm to learn each class separately as a binary classifier.

Parameters:

n - The name of the classifier.

ltu - The linear threshold unit used to learn binary classifiers.

SparseNetworkLearner

public SparseNetworkLearner(java.lang.String n,
                            SparseNetworkLearner.Parameters p)

Initializing constructor. Sets all member variables to their associated settings in the SparseNetworkLearner.Parameters object.

Parameters:

n - The name of the classifier.

p - The settings of all parameters.

Method Detail

setParameters

public void setParameters(SparseNetworkLearner.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.

Overrides:

getParameters in class Learner

Returns:

An object containing all the values of the parameters that control the behavior of this learning algorithm.

setLTU

public void setLTU(LinearThresholdUnit ltu)

Sets the baseLTU variable. This method will not have any effect on the LTUs that already exist in the network. However, new LTUs created after this method is executed will be of the same type as the object specified.

Parameters:

ltu - The new LTU.

setLabeler

public void setLabeler(Classifier l)

Sets the labeler.

Overrides:

setLabeler in class Learner

Parameters:

l - A labeling classifier.

setExtractor

public void setExtractor(Classifier e)

Sets the extractor.

Overrides:

setExtractor in class Learner

Parameters:

e - A feature extracting classifier.

learn

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

Each example is treated as a positive example for the linear threshold unit associated with the label's value that is active for the example and as a negative example for all other linear threshold units in the network.

Specified by:

learn in class Learner

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 labels' values.

doneLearning

public void doneLearning()

Simply calls doneLearning() on every LTU in the network.

Overrides:

doneLearning in class Learner

initialize

public void initialize(int ne,
                       int nf)

Sets the number of examples and features.

Overrides:

initialize in class Learner

Parameters:

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

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

doneWithRound

public void doneWithRound()

Simply calls Learner.doneWithRound() on every LTU in the network.

Overrides:

doneWithRound in class Learner

forget

public void forget()

Clears the network.

Overrides:

forget in class Learner

scores

public ScoreSet scores(java.lang.Object example,
                       java.util.Collection candidates)

Returns scores for only those labels in the given collection. If the given collection is empty, scores for all labels will be returned. If there is no LinearThresholdUnit associated with a given label from the collection, that label's score in the returned ScoreSet will be set to Double.NEGATIVE_INFINITY.

The elements of candidates must all be Strings.

Parameters:

example - The example object.

candidates - A list of the only labels the example may take.

Returns:

Scores for only those labels in candidates.

scores

public ScoreSet scores(int[] exampleFeatures,
                       double[] exampleValues,
                       java.util.Collection candidates)

Returns scores for only those labels in the given collection. If the given collection is empty, scores for all labels will be returned. If there is no LinearThresholdUnit associated with a given label from the collection, that label's score in the returned ScoreSet will be set to Double.NEGATIVE_INFINITY.

The elements of candidates must all be Strings.

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

candidates - A list of the only labels the example may take.

Returns:

Scores for only those labels in candidates.

conjunctiveScores

protected ScoreSet conjunctiveScores(int[] exampleFeatures,
                                     double[] exampleValues,
                                     java.util.Iterator I)

This method is a surrogate for scores(int[],double[],Collection) when the labeler is known to produce conjunctive features. It is necessary because when given a string label from the collection, we will not know how to construct the appropriate conjunctive feature key for lookup in the label lexicon. So, we must go through each feature in the label lexicon and use Feature.valueEquals(String).

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

I - An iterator over the set of labels to choose from.

Returns:

The label chosen by this classifier or null if the network did not contain any of the specified labels.

scores

public 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. These scores are just the scores of each LTU's positive classification as produced by LinearThresholdUnit.scores(Object).

Specified by:

scores in class Learner

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

Returns:

The set of scores produced by the LTUs

See Also:

Learner.scores(Object)

featureValue

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

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

Overrides:

featureValue in class Learner

Parameters:

f - The features array.

v - The values array.

Returns:

The classification of the example as a feature.

discreteValue

public java.lang.String discreteValue(int[] exampleFeatures,
                                      double[] exampleValues)

This implementation uses a winner-take-all comparison of the outputs from the individual linear threshold units' score methods.

Overrides:

discreteValue in class Learner

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

Returns:

A single value with the winning linear threshold unit's associated value.

classify

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

This implementation uses a winner-take-all comparison of the outputs from the individual linear threshold units' score methods.

Specified by:

classify in class Learner

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

Returns:

A single feature with the winning linear threshold unit's associated value.

valueOf

public Feature valueOf(java.lang.Object example,
                       java.util.Collection candidates)

Using this method, the winner-take-all competition is narrowed to involve only those labels contained in the specified list. The list must contain only Strings.

Parameters:

example - The example object.

candidates - A list of the only labels the example may take.

Returns:

The prediction as a feature or null if the network did not contain any of the specified labels.

valueOf

public Feature valueOf(int[] exampleFeatures,
                       double[] exampleValues,
                       java.util.Collection candidates)

Using this method, the winner-take-all competition is narrowed to involve only those labels contained in the specified list. The list must contain only Strings.

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

candidates - A list of the only labels the example may take.

Returns:

The prediction as a feature or null if the network did not contain any of the specified labels.

conjunctiveValueOf

protected Feature conjunctiveValueOf(int[] exampleFeatures,
                                     double[] exampleValues,
                                     java.util.Iterator I)

This method is a surrogate for valueOf(int[],double[],Collection) when the labeler is known to produce conjunctive features. It is necessary because when given a string label from the collection, we will not know how to construct the appropriate conjunctive feature key for lookup in the label lexicon. So, we must go through each feature in the label lexicon and use Feature.valueEquals(String).

Parameters:

exampleFeatures - The example's array of feature indices.

exampleValues - The example's array of feature values.

I - An iterator over the set of labels to choose from.

Returns:

The label chosen by this classifier or null if the network did not contain any of the specified labels.

write

public void write(java.io.PrintStream out)

Writes the algorithm's internal representation as text.

Specified by:

write in class Learner

Parameters:

out - The output stream.

write

public void write(ExceptionlessOutputStream out)

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

Overrides:

write in class Learner

Parameters:

out - The output 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.

Overrides:

read in class Learner

Parameters:

in - The input stream.

clone

public java.lang.Object clone()

Returns a deep clone of this learning algorithm.

Overrides:

clone in class Learner

Returns:

A shallow clone.