edu.illinois.cs.cogcomp.lbjava.learn

Class SparseNetworkLearner

java.lang.Object

edu.illinois.cs.cogcomp.lbjava.classify.Classifier

edu.illinois.cs.cogcomp.lbjava.learn.Learner

edu.illinois.cs.cogcomp.lbjava.learn.SparseNetworkLearner

All Implemented Interfaces:

Serializable, 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.

Author:

Nick Rizzolo

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SparseNetworkLearner.Parameters Simply a container for all of SparseNetworkLearner's configurable parameters.

Field Summary

Fields

Modifier and Type	Field and Description
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 edu.illinois.cs.cogcomp.core.datastructures.vectors.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 edu.illinois.cs.cogcomp.lbjava.learn.Learner

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

Fields inherited from class edu.illinois.cs.cogcomp.lbjava.classify.Classifier

containingPackage, name

Constructor Summary

Constructors

Constructor and Description
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(String n) Instantiates this multi-class learner with the default learning algorithm: defaultBaseLTU.
SparseNetworkLearner(String n, LinearThresholdUnit ltu) Instantiates this multi-class learner using the specified algorithm to learn each class separately as a binary classifier.
SparseNetworkLearner(String n, SparseNetworkLearner.Parameters p) Initializing constructor.

Method Summary

Modifier and Type	Method and Description
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.
Object	clone() Returns a deep clone of this learning algorithm.
protected ScoreSet	conjunctiveScores(int[] exampleFeatures, double[] exampleValues, 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, Iterator I) This method is a surrogate for valueOf(int[],double[],Collection) when the labeler is known to produce conjunctive features.
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.
LinearThresholdUnit	getBaseLTU()
Object	getLTU(int i) returns the i-th LTU; the type of this depends on the type of the baseLTU (see above).
edu.illinois.cs.cogcomp.core.datastructures.vectors.OVector	getNetwork()
int	getNumExamples()
int	getNumFeatures()
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.
boolean	isUsingConjunctiveLabels()
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(edu.illinois.cs.cogcomp.core.datastructures.vectors.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, Collection candidates) Returns scores for only those labels in the given collection.
ScoreSet	scores(Object example, 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	setNetworkLabel(int label) Create a LinearThresholdUnit and add it to the network
void	setParameters(SparseNetworkLearner.Parameters p) Sets the values of parameters that control the behavior of this learning algorithm.
Feature	valueOf(int[] exampleFeatures, double[] exampleValues, Collection candidates) Using this method, the winner-take-all competition is narrowed to involve only those labels contained in the specified list.
Feature	valueOf(Object example, Collection candidates) Using this method, the winner-take-all competition is narrowed to involve only those labels contained in the specified list.
void	write(edu.illinois.cs.cogcomp.core.datastructures.vectors.ExceptionlessOutputStream out) Writes the learned function's internal representation in binary form.
void	write(PrintStream out) Writes the algorithm's internal representation as text.

Methods inherited from class edu.illinois.cs.cogcomp.lbjava.learn.Learner

classify, classify, classify, classify, countFeatures, createPrediction, createPrediction, demandLexicon, discreteValue, discreteValue, emptyClone, featureValue, featureValue, getCurrentLexicon, 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, scoresAugmented, setCandidates, setEncoding, setLabelLexicon, setLexicon, setLexiconLocation, setLexiconLocation, setLossFlag, setModelLocation, setModelLocation, setParameters, setReadLexiconOnDemand, unclone, unsetLossFlag, write, writeLexicon, writeModel, writeParameters

Methods inherited from class edu.illinois.cs.cogcomp.lbjava.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 edu.illinois.cs.cogcomp.core.datastructures.vectors.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(String n)

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

Parameters:

n - The name of the classifier.

SparseNetworkLearner

public SparseNetworkLearner(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(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

getNumExamples

public int getNumExamples()

getNumFeatures

public int getNumFeatures()

getBaseLTU

public LinearThresholdUnit getBaseLTU()

getNetwork

public edu.illinois.cs.cogcomp.core.datastructures.vectors.OVector getNetwork()

isUsingConjunctiveLabels

public boolean isUsingConjunctiveLabels()

getLTU

public Object getLTU(int i)

returns the i-th LTU; the type of this depends on the type of the baseLTU (see above).

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.

setNetworkLabel

public void setNetworkLabel(int label)

Create a LinearThresholdUnit and add it to the network

Parameters:

label - The label associated with the LTU

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(Object example,
                       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,
                       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,
                                     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 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(Object example,
                       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,
                       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,
                                     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(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(edu.illinois.cs.cogcomp.core.datastructures.vectors.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(edu.illinois.cs.cogcomp.core.datastructures.vectors.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 Object clone()

Returns a deep clone of this learning algorithm.

Overrides:

clone in class Learner

Returns:

A shallow clone.