LBJ2.classify
Class Feature

java.lang.Object
  LBJ2.classify.Feature

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

Direct Known Subclasses:

DiscreteFeature, RealFeature

public abstract class Feature
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Comparable, java.io.Serializable

Objects of this class represent the value of a Classifier's decision.

See Also:

Serialized Form

Field Summary

protected java.lang.String	containingPackage The Java package containing the classifier that produced this feature.
protected java.lang.String	generatingClassifier The name of the LBJ classifier that produced this feature.

Constructor Summary

protected	Feature() For internal use only.
	Feature(java.lang.String p, java.lang.String c) Initializing constructor.

Method Summary

int	childLexiconLookup(ChildLexicon lex, int label) Does a feature-type-specific lookup of this feature in the given ChildLexicon.
boolean	classEquivalent(Feature f) Some features are functionally equivalent, differing only in the encoding of their values; this method will return true iff the class of this feature and f are different, but they differ only because they encode their values differently.
java.lang.Object	clone() Returns a shallow clone of this Feature.
int	compareNameStrings(java.lang.Object o) Compares only the run-time types, packages, classifier names, and identifiers of the features.
abstract int	compareTo(java.lang.Object o) Used to sort features into an order that is convenient both to page through and for the lexicon to read off disk.
private int	compareTypes(java.lang.Object o) Compares only the run-time types of the features.
abstract Feature	conjunction(Feature f, Classifier c) Create a feature representing the conjunction of this feature with the given argument feature.
protected Feature	conjunctWith(DiscreteFeature f, Classifier c) Create a feature representing the conjunction of this feature with the given argument feature.
protected Feature	conjunctWith(RealFeature f, Classifier c) Create a feature representing the conjunction of this feature with the given argument feature.
int	depth() The depth of a feature is one more than the maximum depth of any of its children, or 0 if it has no children.
abstract Feature	encode(java.lang.String e) Returns a feature object in which any strings that are being used to represent an identifier or value have been encoded in byte strings.
boolean	equals(java.lang.Object o) Two Features are equal when their packages and generating classifiers are equivalent.
boolean	fromArray() Determines if this feature comes from an array.
abstract ByteString	getByteStringIdentifier() Retrieves this feature's identifier as a byte string.
abstract ByteString	getByteStringValue() Gives a string representation of the value of this feature.
Feature	getFeatureKey(Lexicon lexicon) Return the feature that should be used to index this feature into a lexicon.
abstract Feature	getFeatureKey(Lexicon lexicon, boolean training, int label) Return the feature that should be used to index this feature into a lexicon.
java.lang.String	getGeneratingClassifier() Retrieves the name of the classifier that produced this feature.
java.lang.String	getPackage() Retrieves this feature's package.
abstract double	getStrength() Returns the strength of this feature if it were to be placed in a mathematical vector space.
abstract java.lang.String	getStringIdentifier() Retrieves this feature's identifier as a string.
abstract java.lang.String	getStringValue() Gives a string representation of the value of this feature.
short	getValueIndex() Returns the index in the generating classifier's value list of this feature's value.
boolean	hasByteStringIdentifier() Determines if this feature contains a byte string identifier field.
int	hashCode() The hash code of a Feature is a function of the hash codes of containingPackage and generatingClassifier.
boolean	hasStringIdentifier() Determines if this feature contains a string identifier field.
boolean	isConjunctive() Determines if this feature is conjunctive.
abstract boolean	isDiscrete() Determines if this feature is discrete.
boolean	isPrimitive() Determines if this feature is primitive.
boolean	isReferrer() Determines if this feature is a referring feature.
void	lexRead(ExceptionlessInputStream in, Lexicon lex, java.lang.String p, java.lang.String g, java.lang.String si, ByteString bi) Reads the representation of a feature with this object's run-time type as stored by a lexicon, overwriting the data in this object.
static Feature	lexReadFeature(ExceptionlessInputStream in, Lexicon lex, java.lang.Class c, java.lang.String p, java.lang.String g, java.lang.String si, ByteString bi) Reads the representation of a feature of any type as stored by a lexicon, omitting redundant information.
java.lang.String	lexWrite(ExceptionlessOutputStream out, Lexicon lex, java.lang.String c, java.lang.String p, java.lang.String g, java.lang.String si, ByteString bi) Writes a binary representation of the feature intended for use by a lexicon, omitting redundant information when possible.
abstract RealFeature	makeReal() Returns a RealFeature whose value is the strength of the current feature, and whose identifier field contains all the information necessary to distinguish this feature from other features.
void	read(ExceptionlessInputStream in) Reads the representation of a feature with this object's run-time type from the given stream, overwriting the data in this object.
static Feature	readFeature(ExceptionlessInputStream in) Reads the binary representation of a feature of any type from the given stream.
private void	readObject(java.io.ObjectInputStream in) Special handling during deserialization to ensure that Strings are intern()ed.
void	removeFromChildLexicon(ChildLexicon lex) Takes care of any feature-type-specific tasks that need to be taken care of when removing a feature of this type from a ChildLexicon, in particular updating parent counts and removing children of this feature if necessary.
void	setArrayLength(int l) If this feature is an array feature, call this method to set its array length; otherwise, this method has no effect.
java.lang.String	toString() Returns a string representation of this Feature.
java.lang.String	toStringNoPackage() Returns a string representation of this Feature omitting the package.
short	totalValues() Returns the total number of values this feature might possibly be set to.
abstract boolean	valueEquals(java.lang.String v) Determines whether or not the parameter is equivalent to the string representation of the value of this feature.
abstract Feature	withStrength(double s) Returns a new feature object that's identical to this feature except its strength is given by s.
void	write(ExceptionlessOutputStream out) Writes a complete binary representation of the feature.
abstract void	write(java.lang.StringBuffer buffer) Writes a string representation of this Feature to the specified buffer.
void	writeNameString(java.lang.StringBuffer buffer) Writes a string representation of this Feature's package, generating classifier, and sometimes identifier information to the specified buffer.
void	writeNoPackage(java.lang.StringBuffer buffer) Writes a string representation of this Feature to the specified buffer, omitting the package name.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

containingPackage

protected java.lang.String containingPackage

The Java package containing the classifier that produced this feature.

generatingClassifier

protected java.lang.String generatingClassifier

The name of the LBJ classifier that produced this feature.

Constructor Detail

Feature

protected Feature()

For internal use only.

See Also:

readFeature(ExceptionlessInputStream)

Feature

public Feature(java.lang.String p,
               java.lang.String c)

Initializing constructor.

Parameters:

p - The package containing the classifier that produced this feature.

c - The name of the classifier that produced this feature.

Method Detail

getPackage

public java.lang.String getPackage()

Retrieves this feature's package.

getGeneratingClassifier

public java.lang.String getGeneratingClassifier()

Retrieves the name of the classifier that produced this feature.

getStringIdentifier

public abstract java.lang.String getStringIdentifier()

Retrieves this feature's identifier as a string.

Returns:

This feature's identifier as a string.

getByteStringIdentifier

public abstract ByteString getByteStringIdentifier()

Retrieves this feature's identifier as a byte string.

Returns:

This feature's identifier as a byte string.

getStringValue

public abstract java.lang.String getStringValue()

Gives a string representation of the value of this feature.

Returns:

A string representation of the value of this feature.

getByteStringValue

public abstract ByteString getByteStringValue()

Gives a string representation of the value of this feature.

Returns:

A string representation of the value of this feature.

valueEquals

public abstract boolean valueEquals(java.lang.String v)

Determines whether or not the parameter is equivalent to the string representation of the value of this feature.

Parameters:

v - The string to compare against.

Returns:

true iff the parameter is equivalent to the string representation of the value of this feature.

isDiscrete

public abstract boolean isDiscrete()

Determines if this feature is discrete.

Returns:

true iff this is discrete.

hasByteStringIdentifier

public boolean hasByteStringIdentifier()

Determines if this feature contains a byte string identifier field.

Returns:

true iff this feature contains a byte string identifier field.

hasStringIdentifier

public boolean hasStringIdentifier()

Determines if this feature contains a string identifier field.

Returns:

true iff this feature contains a string identifier field.

isPrimitive

public boolean isPrimitive()

Determines if this feature is primitive.

Returns:

true iff this is primitive.

isConjunctive

public boolean isConjunctive()

Determines if this feature is conjunctive.

Returns:

true iff this feature is conjunctive.

isReferrer

public boolean isReferrer()

Determines if this feature is a referring feature.

Returns:

true iff this feature is a referring feature.

fromArray

public boolean fromArray()

Determines if this feature comes from an array.

Returns:

true iff this feature comes from an array.

depth

public int depth()

The depth of a feature is one more than the maximum depth of any of its children, or 0 if it has no children.

Returns:

The depth of this feature as described above.

getValueIndex

public short getValueIndex()

Returns the index in the generating classifier's value list of this feature's value.

Returns:

A non-negative integer index, or -1 if this feature is real or doesn't have a value list.

totalValues

public short totalValues()

Returns the total number of values this feature might possibly be set to.

Returns:

Some integer greater than 1 iff this feature is a discrete feature with a specified value list or a conjunctive feature whose arguments have value lists, and 0 otherwise.

setArrayLength

public void setArrayLength(int l)

If this feature is an array feature, call this method to set its array length; otherwise, this method has no effect.

Parameters:

l - The new length.

getStrength

public abstract double getStrength()

Returns the strength of this feature if it were to be placed in a mathematical vector space.

getFeatureKey

public Feature getFeatureKey(Lexicon lexicon)

Return the feature that should be used to index this feature into a lexicon. This method simply calls getFeatureKey(lexicon, true, -1).

Parameters:

lexicon - The lexicon into which this feature will be indexed.

Returns:

A feature object appropriate for use as the key of a map.

See Also:

getFeatureKey(Lexicon,boolean,int)

getFeatureKey

public abstract Feature getFeatureKey(Lexicon lexicon,
                                      boolean training,
                                      int label)

Return the feature that should be used to index this feature into a lexicon.

Parameters:

lexicon - The lexicon into which this feature will be indexed.

training - Whether or not the learner is currently training.

label - The label of the example containing this feature, or -1 if we aren't doing per class feature counting.

Returns:

A feature object appropriate for use as the key of a map.

makeReal

public abstract RealFeature makeReal()

Returns a RealFeature whose value is the strength of the current feature, and whose identifier field contains all the information necessary to distinguish this feature from other features. When defining this method, RealFeatures may simply return themselves.

conjunction

public abstract Feature conjunction(Feature f,
                                    Classifier c)

Create a feature representing the conjunction of this feature with the given argument feature.

Parameters:

f - The feature to conjunct with.

c - The classifier producing the resulting feature.

Returns:

A feature representing the conjunction of this feature and f.

conjunctWith

protected Feature conjunctWith(DiscreteFeature f,
                               Classifier c)

Create a feature representing the conjunction of this feature with the given argument feature.

Parameters:

f - The feature to conjunct with.

c - The classifier producing the resulting feature.

Returns:

A feature representing the conjunction of this feature and f.

conjunctWith

protected Feature conjunctWith(RealFeature f,
                               Classifier c)

Create a feature representing the conjunction of this feature with the given argument feature.

Parameters:

f - The feature to conjunct with.

c - The classifier producing the resulting feature.

Returns:

A feature representing the conjunction of this feature and f.

withStrength

public abstract Feature withStrength(double s)

Returns a new feature object that's identical to this feature except its strength is given by s.

Parameters:

s - The strength of the new feature.

Returns:

A new feature object as above, or null if this feature cannot take the specified strength.

encode

public abstract Feature encode(java.lang.String e)

Returns a feature object in which any strings that are being used to represent an identifier or value have been encoded in byte strings.

Parameters:

e - The encoding to use.

Returns:

A feature object as above; possible this object.

removeFromChildLexicon

public void removeFromChildLexicon(ChildLexicon lex)

Takes care of any feature-type-specific tasks that need to be taken care of when removing a feature of this type from a ChildLexicon, in particular updating parent counts and removing children of this feature if necessary.

Parameters:

lex - The child lexicon this feature is being removed from.

childLexiconLookup

public int childLexiconLookup(ChildLexicon lex,
                              int label)

Does a feature-type-specific lookup of this feature in the given ChildLexicon.

Parameters:

lex - The child lexicon this feature is being looked up in.

label - The label of the example containing this feature, or -1 if we aren't doing per class feature counting.

Returns:

The index of f in this lexicon.

hashCode

public int hashCode()

The hash code of a Feature is a function of the hash codes of containingPackage and generatingClassifier.

Overrides:

hashCode in class java.lang.Object

Returns:

The hash code of this Feature.

equals

public boolean equals(java.lang.Object o)

Two Features are equal when their packages and generating classifiers are equivalent.

Overrides:

equals in class java.lang.Object

Returns:

true iff the argument is an equivalent Feature.

classEquivalent

public boolean classEquivalent(Feature f)

Some features are functionally equivalent, differing only in the encoding of their values; this method will return true iff the class of this feature and f are different, but they differ only because they encode their values differently. This method does not compare the values themselves, however.

Parameters:

f - Another feature.

Returns:

See above.

compareTo

public abstract int compareTo(java.lang.Object o)

Used to sort features into an order that is convenient both to page through and for the lexicon to read off disk.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - An object to compare with.

Returns:

Integers appropriate for sorting features first by package, then by classifier name, and then by identifier.

compareNameStrings

public int compareNameStrings(java.lang.Object o)

Compares only the run-time types, packages, classifier names, and identifiers of the features. This method must be overridden in order to accomplish the comparison of identifiers, but the overriding method will still have the convenience of calling this method to accomplish the majority of the work.

Parameters:

o - An object to compare with.

Returns:

Integers appropriate for sorting features first by package, then by classifier name, and then by identifier.

compareTypes

private int compareTypes(java.lang.Object o)

Compares only the run-time types of the features.

Parameters:

o - An object to compare with.

Returns:

Integers appropriate for sorting features by run-time type.

write

public abstract void write(java.lang.StringBuffer buffer)

Writes a string representation of this Feature to the specified buffer.

Parameters:

buffer - The buffer to write to.

writeNameString

public void writeNameString(java.lang.StringBuffer buffer)

Writes a string representation of this Feature's package, generating classifier, and sometimes identifier information to the specified buffer. This method will need to be overridden to write the identifier information, but at least the overriding method will have the convenience of calling this method to accomplish most of the work first.

Parameters:

buffer - The buffer to write to.

write

public void write(ExceptionlessOutputStream out)

Writes a complete binary representation of the feature.

Parameters:

out - The output stream.

writeNoPackage

public void writeNoPackage(java.lang.StringBuffer buffer)

Writes a string representation of this Feature to the specified buffer, omitting the package name.

Parameters:

buffer - The buffer to write to.

lexWrite

public java.lang.String lexWrite(ExceptionlessOutputStream out,
                                 Lexicon lex,
                                 java.lang.String c,
                                 java.lang.String p,
                                 java.lang.String g,
                                 java.lang.String si,
                                 ByteString bi)

Writes a binary representation of the feature intended for use by a lexicon, omitting redundant information when possible.

Parameters:

out - The output stream.

lex - The lexicon out of which this feature is being written.

c - The fully qualified name of the assumed class. The runtime class of this feature won't be written if it's equivalent to c.

p - The assumed package string. This feature's package string won't be written if it's equivalent to p.

g - The assumed classifier name string. This feature's classifier name string won't be written if it's equivalent to g.

si - The assumed identifier as a string. If this feature has a string identifier, it won't be written if it's equivalent to si.

bi - The assumed identifier as a byte string. If this feature has a byte string identifier, it won't be written if it's equivalent to bi.

Returns:

The name of the runtime type of this feature.

readFeature

public static Feature readFeature(ExceptionlessInputStream in)

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

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

Parameters:

in - The input stream.

Returns:

The feature read from the stream.

read

public void read(ExceptionlessInputStream in)

Reads the representation of a feature with this object's run-time type from the given stream, overwriting the data in this object.

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

Parameters:

in - The input stream.

lexReadFeature

public static Feature lexReadFeature(ExceptionlessInputStream in,
                                     Lexicon lex,
                                     java.lang.Class c,
                                     java.lang.String p,
                                     java.lang.String g,
                                     java.lang.String si,
                                     ByteString bi)

Reads the representation of a feature of any type as stored by a lexicon, omitting redundant information.

This method is appropriate for reading features as written by lexWrite(ExceptionlessOutputStream,Lexicon,String,String,String,String,ByteString).

Parameters:

in - The input stream.

lex - The lexicon we are reading in to.

c - The assumed class. If no class name is given in the input stream, a feature of this type is instantiated.

p - The assumed package string. If no package name is given in the input stream, the instantiated feature is given this package.

g - The assumed classifier name string. If no classifier name is given in the input stream, the instantiated feature is given this classifier name.

si - The assumed identifier as a string. If the feature being read has a string identifier field and no identifier is given in the input stream, the feature is given this identifier.

bi - The assumed identifier as a byte string. If the feature being read has a byte string identifier field and no identifier is given in the input stream, the feature is given this identifier.

Returns:

The feature read from the stream.

lexRead

public void lexRead(ExceptionlessInputStream in,
                    Lexicon lex,
                    java.lang.String p,
                    java.lang.String g,
                    java.lang.String si,
                    ByteString bi)

Reads the representation of a feature with this object's run-time type as stored by a lexicon, overwriting the data in this object.

This method is appropriate for reading features as written by lexWrite(ExceptionlessOutputStream,Lexicon,String,String,String,String,ByteString).

Parameters:

in - The input stream.

lex - The lexicon we are reading in to.

p - The assumed package string. If no package name is given in the input stream, the instantiated feature is given this package.

g - The assumed classifier name string. If no classifier name is given in the input stream, the instantiated feature is given this classifier name.

si - The assumed identifier as a string. If the feature being read has a string identifier field and no identifier is given in the input stream, the feature is given this identifier.

bi - The assumed identifier as a byte string. If the feature being read has a byte string identifier field and no identifier is given in the input stream, the feature is given this identifier.

toString

public java.lang.String toString()

Returns a string representation of this Feature.

Overrides:

toString in class java.lang.Object

toStringNoPackage

public java.lang.String toStringNoPackage()

Returns a string representation of this Feature omitting the package.

clone

public java.lang.Object clone()

Returns a shallow clone of this Feature.

Overrides:

clone in class java.lang.Object

readObject

private void readObject(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException

Special handling during deserialization to ensure that Strings are intern()ed.

Parameters:

in - The stream to deserialize from.

Throws:

java.io.IOException

java.lang.ClassNotFoundException