All Packages  Class Hierarchy  This Package  Previous  Next  Index  WEKA's home

Class weka.core.Instance

java.lang.Object
   |
   +----weka.core.Instance

public class Instance
extends Object
implements Copyable, Serializable
Class for handling an instance. All values (numeric, nominal, or string) are internally stored as floating-point numbers. If an attribute is nominal (or a string), the stored value is the index of the corresponding nominal (or string) value in the attribute's definition. We have chosen this approach in favor of a more elegant object-oriented approach because it is much faster.

Typical usage (code from the main() method of this class):

...
// Create empty instance with three attribute values
Instance inst = new Instance(3);

// Set instance's values for the attributes "length", "weight", and "position"
inst.setValue(length, 5.3);
inst.setValue(weight, 300);
inst.setValue(position, "first");

// Set instance's dataset to be the dataset "race"
inst.setDataset(race);

// Print the instance
System.out.println("The instance: " + inst);
...

All methods that change an instance are safe, ie. a change of an instance does not affect any other instances. All methods that change an instance's attribute values clone the attribute value vector before it is changed. If your application heavily modifies instance values, it may be faster to create a new instance from scratch.

Author:
Eibe Frank (eibe@cs.waikato.ac.nz)

Constructor Index

 o Instance(double, double[])
Constructor that inititalizes instance variable with given values.
 o Instance(Instance)
Constructor that copies the attribute values and the weight from the given instance.
 o Instance(int)
Constructor of an instance that sets weight to one, all values to be missing, and the reference to the dataset to null.

Method Index

 o attribute(int)
Returns the attribute with the given index.
 o attributeSparse(int)
Returns the attribute with the given index.
 o classAttribute()
Returns class attribute.
 o classIndex()
Returns the class attribute's index.
 o classIsMissing()
Tests if an instance's class is missing.
 o classValue()
Returns an instance's class value in internal format.
 o copy()
Produces a shallow copy of this instance.
 o dataset()
Returns the dataset this instance has access to.
 o deleteAttributeAt(int)
Deletes an attribute at the given position (0 to numAttributes() - 1).
 o enumerateAttributes()
Returns an enumeration of all the attributes.
 o equalHeaders(Instance)
Tests if the headers of two instances are equivalent.
 o index(int)
Returns the index of the attribute stored at the given position.
 o insertAttributeAt(int)
Inserts an attribute at the given position (0 to numAttributes()).
 o isMissing(Attribute)
Tests if a specific value is "missing".
 o isMissing(int)
Tests if a specific value is "missing".
 o isMissingSparse(int)
Tests if a specific value is "missing".
 o isMissingValue(double)
Tests if the given value codes "missing".
 o main(String[])
Main method for testing this class.
 o mergeInstance(Instance)
Merges this instance with the given instance and returns the result.
 o missingValue()
Returns the double that codes "missing".
 o numAttributes()
Returns the number of attributes.
 o numClasses()
Returns the number of class labels.
 o numValues()
Returns the number of values present.
 o replaceMissingValues(double[])
Replaces all missing values in the instance with the values contained in the given array.
 o setClassMissing()
Sets the class value of an instance to be "missing".
 o setClassValue(double)
Sets the class value of an instance to the given value (internal floating-point format).
 o setClassValue(String)
Sets the class value of an instance to the given value.
 o setDataset(Instances)
Sets the reference to the dataset.
 o setMissing(Attribute)
Sets a specific value to be "missing".
 o setMissing(int)
Sets a specific value to be "missing".
 o setValue(Attribute, double)
Sets a specific value in the instance to the given value (internal floating-point format).
 o setValue(Attribute, String)
Sets a value of an nominal or string attribute to the given value.
 o setValue(int, double)
Sets a specific value in the instance to the given value (internal floating-point format).
 o setValue(int, String)
Sets a value of a nominal or string attribute to the given value.
 o setValueSparse(int, double)
Sets a specific value in the instance to the given value (internal floating-point format).
 o setWeight(double)
Sets the weight of an instance.
 o stringValue(Attribute)
Returns the value of a nominal (or string) attribute for the instance.
 o stringValue(int)
Returns the value of a nominal (or string) attribute for the instance.
 o toDoubleArray()
Returns the values of each attribute as an array of doubles.
 o toString()
Returns the description of one instance.
 o toString(Attribute)
Returns the description of one value of the instance as a string.
 o toString(int)
Returns the description of one value of the instance as a string.
 o value(Attribute)
Returns an instance's attribute value in internal format.
 o value(int)
Returns an instance's attribute value in internal format.
 o valueSparse(int)
Returns an instance's attribute value in internal format.
 o weight()
Returns the instance's weight.

Constructors

 o Instance
 public Instance(Instance instance)
Constructor that copies the attribute values and the weight from the given instance. Reference to the dataset is set to null. (ie. the instance doesn't have access to information about the attribute types)

Parameters:
instance - the instance from which the attribute values and the weight are to be copied
 o Instance
 public Instance(double weight,
                 double attValues[])
Constructor that inititalizes instance variable with given values. Reference to the dataset is set to null. (ie. the instance doesn't have access to information about the attribute types)

Parameters:
weight - the instance's weight
attValues - a vector of attribute values
 o Instance
 public Instance(int numAttributes)
Constructor of an instance that sets weight to one, all values to be missing, and the reference to the dataset to null. (ie. the instance doesn't have access to information about the attribute types)

Parameters:
numAttributes - the size of the instance

Methods

 o attribute
 public Attribute attribute(int index)
Returns the attribute with the given index.

Parameters:
index - the attribute's index
Returns:
the attribute at the given position
Throws: UnassignedDatasetException
if instance doesn't have access to a dataset
 o attributeSparse
 public Attribute attributeSparse(int indexOfIndex)
Returns the attribute with the given index. Does the same thing as attribute().

Parameters:
indexOfIndex - the index of the attribute's index
Returns:
the attribute at the given position
Throws: UnassignedDatasetException
if instance doesn't have access to a dataset
 o classAttribute
 public Attribute classAttribute()
Returns class attribute.

Returns:
the class attribute
Throws: UnassignedDatasetException
if the class is not set or the instance doesn't have access to a dataset
 o classIndex
 public int classIndex()
Returns the class attribute's index.

Returns:
the class index as an integer
Throws: UnassignedDatasetException
if instance doesn't have access to a dataset
 o classIsMissing
 public boolean classIsMissing()
Tests if an instance's class is missing.

Returns:
true if the instance's class is missing
Throws: UnassignedClassException
if the class is not set or the instance doesn't have access to a dataset
 o classValue
 public double classValue()
Returns an instance's class value in internal format. (ie. as a floating-point number)

Returns:
the corresponding value as a double (If the corresponding attribute is nominal (or a string) then it returns the value's index as a double).
Throws: UnassignedClassException
if the class is not set or the instance doesn't have access to a dataset
 o copy
 public Object copy()
Produces a shallow copy of this instance. The copy has access to the same dataset. (if you want to make a copy that doesn't have access to the dataset, use new Instance(instance)

Returns:
the shallow copy
 o dataset
 public Instances dataset()
Returns the dataset this instance has access to. (ie. obtains information about attribute types from) Null if the instance doesn't have access to a dataset.

Returns:
the dataset the instance has accesss to
 o deleteAttributeAt
 public void deleteAttributeAt(int position)
Deletes an attribute at the given position (0 to numAttributes() - 1). Only succeeds if the instance does not have access to any dataset because otherwise inconsistencies could be introduced.

Parameters:
pos - the attribute's position
Throws: RuntimeException
if the instance has access to a dataset
 o enumerateAttributes
 public Enumeration enumerateAttributes()
Returns an enumeration of all the attributes.

Returns:
enumeration of all the attributes
Throws: UnassignedDatasetException
if the instance doesn't have access to a dataset
 o equalHeaders
 public boolean equalHeaders(Instance inst)
Tests if the headers of two instances are equivalent.

Parameters:
instance - another instance
Returns:
true if the header of the given instance is equivalent to this instance's header
Throws: UnassignedDatasetException
if instance doesn't have access to any dataset
 o index
 public int index(int position)
Returns the index of the attribute stored at the given position. Just returns the given value.

Parameters:
position - the position
Returns:
the index of the attribute stored at the given position
 o insertAttributeAt
 public void insertAttributeAt(int position)
Inserts an attribute at the given position (0 to numAttributes()). Only succeeds if the instance does not have access to any dataset because otherwise inconsistencies could be introduced.

Parameters:
pos - the attribute's position
Throws: RuntimeException
if the instance has accesss to a dataset
Throws: IllegalArgumentException
if the position is out of range
 o isMissing
 public boolean isMissing(int attIndex)
Tests if a specific value is "missing".

Parameters:
attIndex - the attribute's index
 o isMissingSparse
 public boolean isMissingSparse(int indexOfIndex)
Tests if a specific value is "missing". Does the same thing as isMissing() if applied to an Instance.

Parameters:
indexOfIndex - the index of the attribute's index
 o isMissing
 public boolean isMissing(Attribute att)
Tests if a specific value is "missing". The given attribute has to belong to a dataset.

Parameters:
att - the attribute
 o isMissingValue
 public static boolean isMissingValue(double val)
Tests if the given value codes "missing".

Parameters:
val - the value to be tested
Returns:
true if val codes "missing"
 o mergeInstance
 public Instance mergeInstance(Instance inst)
Merges this instance with the given instance and returns the result. Dataset is set to null.

Parameters:
inst - the instance to be merged with this one
Returns:
the merged instances
 o missingValue
 public static double missingValue()
Returns the double that codes "missing".

Returns:
the double that codes "missing"
 o numAttributes
 public int numAttributes()
Returns the number of attributes.

Returns:
the number of attributes as an integer
 o numClasses
 public int numClasses()
Returns the number of class labels.

Returns:
the number of class labels as an integer if the class attribute is nominal, 1 otherwise.
Throws: UnassignedDatasetException
if instance doesn't have access to any dataset
 o numValues
 public int numValues()
Returns the number of values present. Always the same as numAttributes().

Returns:
the number of values
 o replaceMissingValues
 public void replaceMissingValues(double array[])
Replaces all missing values in the instance with the values contained in the given array. A deep copy of the vector of attribute values is performed before the values are replaced.

Parameters:
array - containing the means and modes
Throws: IllegalArgumentException
if numbers of attributes are unequal
 o setClassMissing
 public void setClassMissing()
Sets the class value of an instance to be "missing". A deep copy of the vector of attribute values is performed before the value is set to be missing.

Throws: UnassignedClassException
if the class is not set
Throws: UnassignedDatasetException
if the instance doesn't have access to a dataset
 o setClassValue
 public void setClassValue(double value)
Sets the class value of an instance to the given value (internal floating-point format). A deep copy of the vector of attribute values is performed before the value is set.

Parameters:
value - the new attribute value (If the corresponding attribute is nominal (or a string) then this is the new value's index as a double).
Throws: UnassignedClassException
if the class is not set
Throws: UnaddignedDatasetException
if the instance doesn't have access to a dataset
 o setClassValue
 public final void setClassValue(String value)
Sets the class value of an instance to the given value. A deep copy of the vector of attribute values is performed before the value is set.

Parameters:
value - the new class value (If the class is a string attribute and the value can't be found, the value is added to the attribute).
Throws: UnassignedClassException
if the class is not set
Throws: UnassignedDatasetException
if the dataset is not set
Throws: IllegalArgumentException
if the attribute is not nominal or a string, or the value couldn't be found for a nominal attribute
 o setDataset
 public final void setDataset(Instances instances)
Sets the reference to the dataset. Does not check if the instance is compatible with the dataset. Note: the dataset does not know about this instance. If the structure of the dataset's header gets changed, this instance will not be adjusted automatically.

Parameters:
instances - the reference to the dataset
 o setMissing
 public final void setMissing(int attIndex)
Sets a specific value to be "missing". Performs a deep copy of the vector of attribute values before the value is set to be missing.

Parameters:
attIndex - the attribute's index
 o setMissing
 public final void setMissing(Attribute att)
Sets a specific value to be "missing". Performs a deep copy of the vector of attribute values before the value is set to be missing. The given attribute has to belong to a dataset.

Parameters:
att - the attribute
 o setValue
 public void setValue(int attIndex,
                      double value)
Sets a specific value in the instance to the given value (internal floating-point format). Performs a deep copy of the vector of attribute values before the value is set.

Parameters:
attIndex - the attribute's index
value - the new attribute value (If the corresponding attribute is nominal (or a string) then this is the new value's index as a double).
 o setValueSparse
 public void setValueSparse(int indexOfIndex,
                            double value)
Sets a specific value in the instance to the given value (internal floating-point format). Performs a deep copy of the vector of attribute values before the value is set. Does exactly the same thing as setValue().

Parameters:
indexOfIndex - the index of the attribute's index
value - the new attribute value (If the corresponding attribute is nominal (or a string) then this is the new value's index as a double).
 o setValue
 public final void setValue(int attIndex,
                            String value)
Sets a value of a nominal or string attribute to the given value. Performs a deep copy of the vector of attribute values before the value is set.

Parameters:
attIndex - the attribute's index
value - the new attribute value (If the attribute is a string attribute and the value can't be found, the value is added to the attribute).
Throws: UnassignedDatasetException
if the dataset is not set
Throws: IllegalArgumentException
if the selected attribute is not nominal or a string, or the supplied value couldn't be found for a nominal attribute
 o setValue
 public final void setValue(Attribute att,
                            double value)
Sets a specific value in the instance to the given value (internal floating-point format). Performs a deep copy of the vector of attribute values before the value is set, so if you are planning on calling setValue many times it may be faster to create a new instance using toDoubleArray. The given attribute has to belong to a dataset.

Parameters:
att - the attribute
value - the new attribute value (If the corresponding attribute is nominal (or a string) then this is the new value's index as a double).
 o setValue
 public final void setValue(Attribute att,
                            String value)
Sets a value of an nominal or string attribute to the given value. Performs a deep copy of the vector of attribute values before the value is set, so if you are planning on calling setValue many times it may be faster to create a new instance using toDoubleArray. The given attribute has to belong to a dataset.

Parameters:
att - the attribute
value - the new attribute value (If the attribute is a string attribute and the value can't be found, the value is added to the attribute).
Throws: IllegalArgumentException
if the the attribute is not nominal or a string, or the value couldn't be found for a nominal attribute
 o setWeight
 public final void setWeight(double weight)
Sets the weight of an instance.

Parameters:
weight - the weight
 o stringValue
 public final String stringValue(int attIndex)
Returns the value of a nominal (or string) attribute for the instance.

Parameters:
attIndex - the attribute's index
Returns:
the value as a string
Throws: IllegalArgumentException
if the attribute is not a nominal (or string) attribute.
Throws: UnassignedDatasetException
if the instance doesn't belong to a dataset.
 o stringValue
 public final String stringValue(Attribute att)
Returns the value of a nominal (or string) attribute for the instance.

Parameters:
att - the attribute
Returns:
the value as a string
Throws: IllegalArgumentException
if the attribute is not a nominal (or string) attribute.
Throws: UnassignedDatasetException
if the instance doesn't belong to a dataset.
 o toDoubleArray
 public double[] toDoubleArray()
Returns the values of each attribute as an array of doubles.

Returns:
an array containing all the instance attribute values
 o toString
 public String toString()
Returns the description of one instance. If the instance doesn't have access to a dataset, it returns the internal floating-point values. Quotes string values that contain whitespace characters.

Returns:
the instance's description as a string
Overrides:
toString in class Object
 o toString
 public final String toString(int attIndex)
Returns the description of one value of the instance as a string. If the instance doesn't have access to a dataset, it returns the internal floating-point value. Quotes string values that contain whitespace characters, or if they are a question mark.

Parameters:
attIndex - the attribute's index
Returns:
the value's description as a string
 o toString
 public final String toString(Attribute att)
Returns the description of one value of the instance as a string. If the instance doesn't have access to a dataset it returns the internal floating-point value. Quotes string values that contain whitespace characters, or if they are a question mark. The given attribute has to belong to a dataset.

Parameters:
att - the attribute
Returns:
the value's description as a string
 o value
 public double value(int attIndex)
Returns an instance's attribute value in internal format.

Parameters:
attIndex - the attribute's index
Returns:
the specified value as a double (If the corresponding attribute is nominal (or a string) then it returns the value's index as a double).
 o valueSparse
 public double valueSparse(int indexOfIndex)
Returns an instance's attribute value in internal format. Does exactly the same thing as value() if applied to an Instance.

Parameters:
indexOfIndex - the index of the attribute's index
Returns:
the specified value as a double (If the corresponding attribute is nominal (or a string) then it returns the value's index as a double).
 o value
 public double value(Attribute att)
Returns an instance's attribute value in internal format. The given attribute has to belong to a dataset.

Parameters:
att - the attribute
Returns:
the specified value as a double (If the corresponding attribute is nominal (or a string) then it returns the value's index as a double).
 o weight
 public final double weight()
Returns the instance's weight.

Returns:
the instance's weight as a double
 o main
 public static void main(String options[])
Main method for testing this class.


All Packages  Class Hierarchy  This Package  Previous  Next  Index  WEKA's home