A machine learning "example" to be used in training, testing or performance of various machine learning algorithms.
An instance contains four generic fields of predefined name: "data", "target", "name", and "source". "Data" holds the data represented `by the instance, "target" is often a label associated with the instance, "name" is a short identifying name for the instance (such as a filename), and "source" is human-readable sourceinformation, (such as the original text).
Each field has no predefined type, and may change type as the instance is processed. For example, the data field may start off being a string that represents a file name and then be processed by a {@link cc.mallet.pipe.Pipe} into a CharSequencerepresenting the contents of the file, and eventually to a feature vector holding indices into an {@link cc.mallet.types.Alphabet} holding words found in the file.It is up to each pipe which fields in the Instance it modifies; the most common case is that the pipe modifies the data field.
Generally speaking, there are two modes of operation for Instances. (1) An instance gets created and passed through a Pipe, and the resulting data/target/name/source fields are used. This is generally done for training instances. (2) An instance gets created with raw values in its slots, then different users of the instance call newPipedCopy() with their respective different pipes. This might be done for test instances at "performance" time.
Rather than store an {@link cc.mallet.types.Alphabet} in the Instance,we obtain it through the Pipe instance variable, because the Pipe also indicates where the data came from and how to interpret the Alphabet.
Instances can be made immutable if locked. Although unlocked Instances are mutable, typically the only code that changes the values in the four slots is inside Pipes.
Note that constructing an instance with a pipe argument means "Construct the instance and then run it through the pipe". {@link cc.mallet.types.InstanceList} uses this methodwhen adding instances through a pipeInputIterator.
@see Pipe
@see Alphabet
@see InstanceList
@author Andrew McCallum mccallum@cs.umass.edu