Package weka.core

Interface Instance

  • All Superinterfaces:
    Copyable
    All Known Implementing Classes:
    AbstractInstance, BinarySparseInstance, DenseInstance, SparseInstance
    public interface Instance
extends Copyable
    Interface representing an instance. All values (numeric, date, nominal, string or relational) are internally stored as floating-point numbers in the original concrete class implementations (now called DenseInstance.java and SparseInstance.java), and the methods in this interface reflect this. If an attribute is nominal (or a string or relational), the stored value is the index of the corresponding nominal (or string or relational) 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 DenseInstance(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's attribute values must be safe, ie. a change of an instance's attribute values must not affect any other instances.

    Version:
    $Revision: 15070 $
    Author:
    Eibe Frank (eibe@cs.waikato.ac.nz)

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      Attribute attribute​(int index)
      Returns the attribute with the given index.
      Attribute attributeSparse​(int indexOfIndex)
      Returns the attribute with the given index in the sparse representation.
      Attribute classAttribute()
      Returns class attribute.
      int classIndex()
      Returns the class attribute's index.
      boolean classIsMissing()
      Tests if an instance's class is missing.
      double classValue()
      Returns an instance's class value as a floating-point number.
      Instance copy​(double[] values)
      Copies the instance but fills up its values based on the given array of doubles.
      Instances dataset()
      Returns the dataset this instance has access to.
      void deleteAttributeAt​(int position)
      Deletes an attribute at the given position (0 to numAttributes() - 1).
      java.util.Enumeration<Attribute> enumerateAttributes()
      Returns an enumeration of all the attributes.
      boolean equalHeaders​(Instance inst)
      Tests if the headers of two instances are equivalent.
      java.lang.String equalHeadersMsg​(Instance inst)
      Checks if the headers of two instances are equivalent.
      boolean hasMissingValue()
      Tests whether an instance has a missing value.
      int index​(int position)
      Returns the index of the attribute stored at the given position in the sparse representation.
      void insertAttributeAt​(int position)
      Inserts an attribute at the given position (0 to numAttributes()).
      boolean isMissing​(int attIndex)
      Tests if a specific value is "missing".
      boolean isMissing​(Attribute att)
      Tests if a specific value is "missing".
      boolean isMissingSparse​(int indexOfIndex)
      Tests if a specific value is "missing" in the sparse representation.
      Instance mergeInstance​(Instance inst)
      Merges this instance with the given instance and returns the result.
      int numAttributes()
      Returns the number of attributes.
      int numClasses()
      Returns the number of class labels.
      int numValues()
      Returns the number of values present in a sparse representation.
      Instances relationalValue​(int attIndex)
      Returns the relational value of a relational attribute.
      Instances relationalValue​(Attribute att)
      Returns the relational value of a relational attribute.
      void replaceMissingValues​(double[] array)
      Replaces all missing values in the instance with the values contained in the given array.
      void setClassMissing()
      Sets the class value of an instance to be "missing".
      void setClassValue​(double value)
      Sets the class value of an instance to the given value (internal floating-point format).
      void setClassValue​(java.lang.String value)
      Sets the class value of an instance to the given value.
      void setDataset​(Instances instances)
      Sets the reference to the dataset.
      void setMissing​(int attIndex)
      Sets a specific value to be "missing".
      void setMissing​(Attribute att)
      Sets a specific value to be "missing".
      void setValue​(int attIndex, double value)
      Sets a specific value in the instance to the given value (internal floating-point format).
      void setValue​(int attIndex, java.lang.String value)
      Sets a value of a nominal or string attribute to the given value.
      void setValue​(Attribute att, double value)
      Sets a specific value in the instance to the given value (internal floating-point format).
      void setValue​(Attribute att, java.lang.String value)
      Sets a value of an nominal or string attribute to the given value.
      void setValueSparse​(int indexOfIndex, double value)
      Sets a specific value in the instance to the given value (internal floating-point format), given an index into the sparse representation.
      void setWeight​(double weight)
      Sets the weight of an instance.
      java.lang.String stringValue​(int attIndex)
      Returns the value of a nominal, string, date, or relational attribute for the instance as a string.
      java.lang.String stringValue​(Attribute att)
      Returns the value of a nominal, string, date, or relational attribute for the instance as a string.
      double[] toDoubleArray()
      Returns the values of each attribute as an array of doubles.
      java.lang.String toString​(int attIndex)
      Returns the description of one value of the instance as a string.
      java.lang.String toString​(int attIndex, int afterDecimalPoint)
      Returns the description of one value of the instance as a string.
      java.lang.String toString​(Attribute att)
      Returns the description of one value of the instance as a string.
      java.lang.String toString​(Attribute att, int afterDecimalPoint)
      Returns the description of one value of the instance as a string.
      java.lang.String toStringMaxDecimalDigits​(int afterDecimalPoint)
      Returns the description of one instance with any numeric values printed at the supplied maximum number of decimal places.
      java.lang.String toStringNoWeight()
      Returns the description of one instance (without weight appended).
      java.lang.String toStringNoWeight​(int afterDecimalPoint)
      Returns the description of one instance (without weight appended).
      double value​(int attIndex)
      Returns an instance's attribute value in internal format.
      double value​(Attribute att)
      Returns an instance's attribute value in internal format.
      double valueSparse​(int indexOfIndex)
      Returns an instance's attribute value in internal format, given an index in the sparse representation.
      double weight()
      Returns the instance's weight.

    • Method Detail

      • attribute

        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

      • attributeSparse

        Attribute attributeSparse​(int indexOfIndex)
        Returns the attribute with the given index in the sparse representation. Same as attribute(int) for a DenseInstance.
        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

      • classAttribute

        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

      • classIndex

        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

      • classIsMissing

        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

      • classValue

        double classValue()
        Returns an instance's class value 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

      • copy

        Instance copy​(double[] values)
        Copies the instance but fills up its values based on the given array of doubles. The copy has access to the same dataset.
        Parameters:
        values - the array with new values
        Returns:
        the new instance

      • dataset

        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

      • deleteAttributeAt

        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:
        position - the attribute's position
        Throws:
        java.lang.RuntimeException - if the instance has access to a dataset

      • enumerateAttributes

        java.util.Enumeration<Attribute> 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

      • equalHeaders

        boolean equalHeaders​(Instance inst)
        Tests if the headers of two instances are equivalent.
        Parameters:
        inst - 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

      • equalHeadersMsg

        java.lang.String equalHeadersMsg​(Instance inst)
        Checks if the headers of two instances are equivalent. If not, then returns a message why they differ.
        Parameters:
        inst - another instance
        Returns:
        null if the header of the given instance is equivalent to this instance's header, otherwise a message with details on why they differ

      • hasMissingValue

        boolean hasMissingValue()
        Tests whether an instance has a missing value. Skips the class attribute if set.
        Returns:
        true if instance has a missing value.
        Throws:
        UnassignedDatasetException - if instance doesn't have access to any dataset

      • index

        int index​(int position)
        Returns the index of the attribute stored at the given position in the sparse representation. Identify function for an instance of type DenseInstance.
        Parameters:
        position - the position
        Returns:
        the index of the attribute stored at the given position

      • insertAttributeAt

        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:
        position - the attribute's position
        Throws:
        java.lang.RuntimeException - if the instance has accesss to a dataset
        java.lang.IllegalArgumentException - if the position is out of range

      • isMissing

        boolean isMissing​(int attIndex)
        Tests if a specific value is "missing".
        Parameters:
        attIndex - the attribute's index
        Returns:
        true if the value is "missing"

      • isMissingSparse

        boolean isMissingSparse​(int indexOfIndex)
        Tests if a specific value is "missing" in the sparse representation. Samse as isMissing(int) for a DenseInstance.
        Parameters:
        indexOfIndex - the index of the attribute's index
        Returns:
        true if the value is "missing"

      • isMissing

        boolean isMissing​(Attribute att)
        Tests if a specific value is "missing". The given attribute has to belong to a dataset.
        Parameters:
        att - the attribute
        Returns:
        true if the value is "missing"

      • mergeInstance

        Instance mergeInstance​(Instance inst)
        Merges this instance with the given instance and returns the result. Dataset is set to null. The returned instance is of the same type as this instance.
        Parameters:
        inst - the instance to be merged with this one
        Returns:
        the merged instances

      • numAttributes

        int numAttributes()
        Returns the number of attributes.
        Returns:
        the number of attributes as an integer

      • numClasses

        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

      • numValues

        int numValues()
        Returns the number of values present in a sparse representation.
        Returns:
        the number of values

      • replaceMissingValues

        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:
        java.lang.IllegalArgumentException - if numbers of attributes are unequal

      • setClassMissing

        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
        UnassignedDatasetException - if the instance doesn't have access to a dataset

      • setClassValue

        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
        UnassignedDatasetException - if the instance doesn't have access to a dataset

      • setClassValue

        void setClassValue​(java.lang.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
        UnassignedDatasetException - if the dataset is not set
        java.lang.IllegalArgumentException - if the attribute is not nominal or a string, or the value couldn't be found for a nominal attribute

      • setDataset

        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

      • setMissing

        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

      • setMissing

        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

      • setValue

        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).

      • setValueSparse

        void setValueSparse​(int indexOfIndex,
                    double value)
        Sets a specific value in the instance to the given value (internal floating-point format), given an index into the sparse representation. Performs a deep copy of the vector of attribute values before the value is set. Same as setValue(int, double) for a DenseInstance.
        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).

      • setValue

        void setValue​(int attIndex,
              java.lang.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
        java.lang.IllegalArgumentException - if the selected attribute is not nominal or a string, or the supplied value couldn't be found for a nominal attribute

      • setValue

        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).

      • setValue

        void setValue​(Attribute att,
              java.lang.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:
        java.lang.IllegalArgumentException - if the the attribute is not nominal or a string, or the value couldn't be found for a nominal attribute

      • setWeight

        void setWeight​(double weight)
        Sets the weight of an instance.
        Parameters:
        weight - the weight

      • relationalValue

        Instances relationalValue​(int attIndex)
        Returns the relational value of a relational attribute.
        Parameters:
        attIndex - the attribute's index
        Returns:
        the corresponding relation as an Instances object
        Throws:
        java.lang.IllegalArgumentException - if the attribute is not a relation-valued attribute
        UnassignedDatasetException - if the instance doesn't belong to a dataset.

      • relationalValue

        Instances relationalValue​(Attribute att)
        Returns the relational value of a relational attribute.
        Parameters:
        att - the attribute
        Returns:
        the corresponding relation as an Instances object
        Throws:
        java.lang.IllegalArgumentException - if the attribute is not a relation-valued attribute
        UnassignedDatasetException - if the instance doesn't belong to a dataset.

      • stringValue

        java.lang.String stringValue​(int attIndex)
        Returns the value of a nominal, string, date, or relational attribute for the instance as a string.
        Parameters:
        attIndex - the attribute's index
        Returns:
        the value as a string
        Throws:
        java.lang.IllegalArgumentException - if the attribute is not a nominal, string, date, or relation-valued attribute.
        UnassignedDatasetException - if the instance doesn't belong to a dataset.

      • stringValue

        java.lang.String stringValue​(Attribute att)
        Returns the value of a nominal, string, date, or relational attribute for the instance as a string.
        Parameters:
        att - the attribute
        Returns:
        the value as a string
        Throws:
        java.lang.IllegalArgumentException - if the attribute is not a nominal, string, date, or relation-valued attribute.
        UnassignedDatasetException - if the instance doesn't belong to a dataset.

      • toDoubleArray

        double[] toDoubleArray()
        Returns the values of each attribute as an array of doubles. Creates a fresh array object for this.
        Returns:
        an array containing all the instance attribute values

      • toStringNoWeight

        java.lang.String toStringNoWeight​(int afterDecimalPoint)
        Returns the description of one instance (without weight appended). If the instance doesn't have access to a dataset, it returns the internal floating-point values. Quotes string values that contain whitespace characters. This method is used by getRandomNumberGenerator() in Instances.java in order to maintain backwards compatibility with weka 3.4.
        Parameters:
        afterDecimalPoint - maximum number of digits after the decimal point for numeric values
        Returns:
        the instance's description as a string

      • toStringNoWeight

        java.lang.String toStringNoWeight()
        Returns the description of one instance (without weight appended). If the instance doesn't have access to a dataset, it returns the internal floating-point values. Quotes string values that contain whitespace characters. This method is used by getRandomNumberGenerator() in Instances.java in order to maintain backwards compatibility with weka 3.4.
        Returns:
        the instance's description as a string

      • toStringMaxDecimalDigits

        java.lang.String toStringMaxDecimalDigits​(int afterDecimalPoint)
        Returns the description of one instance with any numeric values printed at the supplied maximum number of decimal places. If the instance doesn't have access to a dataset, it returns the internal floating-point values. Quotes string values that contain whitespace characters.
        Parameters:
        afterDecimalPoint - the maximum number of digits permitted after the decimal point for a numeric value
        Returns:
        the instance's description as a string

      • toString

        java.lang.String toString​(int attIndex,
                          int afterDecimalPoint)
        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
        afterDecimalPoint - the maximum number of digits permitted after the decimal point for numeric values
        Returns:
        the value's description as a string

      • toString

        java.lang.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

      • toString

        java.lang.String toString​(Attribute att,
                          int afterDecimalPoint)
        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
        afterDecimalPoint - the maximum number of decimal places to print
        Returns:
        the value's description as a string

      • toString

        java.lang.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

      • value

        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).

      • valueSparse

        double valueSparse​(int indexOfIndex)
        Returns an instance's attribute value in internal format, given an index in the sparse representation. Same as value(int) for a DenseInstance.
        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).

      • value

        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).

      • weight

        double weight()
        Returns the instance's weight.
        Returns:
        the instance's weight as a double