Package weka.core

# Class AbstractInstance

java.lang.Object
weka.core.AbstractInstance

All Implemented Interfaces:
  `Serializable`, `Copyable`, `Instance`, `RevisionHandler`

Direct Known Subclasses:
  `DenseInstance`, `SparseInstance`

public abstract class AbstractInstance extends Object implements Instance, Serializable, RevisionHandler
Abstract class providing common functionality for the original instance implementations.

Version:
  $Revision: 10649 $
Author:
  Eibe Frank (eibe@cs.waikato.ac.nz)
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static int`
  `s_numericAfterDecimalPoint`
  Default max number of digits after the decimal point for numeric values

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractInstance()`

- ## Method Summary

  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 in internal format.
  `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).
  `Enumeration<Attribute>`
  `enumerateAttributes()`
  Returns an enumeration of all the attributes.
  `boolean`
  `equalHeaders(Instance inst)`
  Tests if the headers of two instances are equivalent.
  `String`
  `equalHeadersMsg(Instance inst)`
  Checks if the headers of two instances are equivalent.
  `String`
  `getRevision()`
  Returns the revision string.
  `boolean`
  `hasMissingValue()`
  Tests whether an instance has a missing value.
  `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", given an index in the sparse representation.
  `int`
  `numClasses()`
  Returns the number of class labels.
  `final Instances`
  `relationalValue(int attIndex)`
  Returns the relational value of a relational attribute.
  `final Instances`
  `relationalValue(Attribute att)`
  Returns the relational value of a relational attribute.
  `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).
  `final void`
  `setClassValue(String value)`
  Sets the class value of an instance to the given value.
  `final void`
  `setDataset(Instances instances)`
  Sets the reference to the dataset.
  `final void`
  `setMissing(int attIndex)`
  Sets a specific value to be "missing".
  `final void`
  `setMissing(Attribute att)`
  Sets a specific value to be "missing".
  `final void`
  `setValue(int attIndex, String value)`
  Sets a value of a nominal or string attribute to the given value.
  `final void`
  `setValue(Attribute att, double value)`
  Sets a specific value in the instance to the given value (internal floating-point format).
  `final void`
  `setValue(Attribute att, String value)`
  Sets a value of an nominal or string attribute to the given value.
  `final void`
  `setWeight(double weight)`
  Sets the weight of an instance.
  `final String`
  `stringValue(int attIndex)`
  Returns the value of a nominal, string, date, or relational attribute for the instance as a string.
  `final String`
  `stringValue(Attribute att)`
  Returns the value of a nominal, string, date, or relational attribute for the instance as a string.
  `String`
  `toString()`
  Returns the description of one instance.
  `final String`
  `toString(int attIndex)`
  Returns the description of one value of the instance as a string.
  `final String`
  `toString(int attIndex, int afterDecimalPoint)`
  Returns the description of one value of the instance as a string.
  `final String`
  `toString(Attribute att)`
  Returns the description of one value of the instance as a string.
  `final String`
  `toString(Attribute att, int afterDecimalPoint)`
  Returns the description of one value of the instance as a string.
  `final String`
  `toStringMaxDecimalDigits(int afterDecimalPoint)`
  Returns the description of one instance with any numeric values printed at the supplied maximum number of decimal places.
  `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.
  `final double`
  `weight()`
  Returns the instance's weight.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface weka.core.Copyable

  `copy`

  ### Methods inherited from interface weka.core.Instance

  `copy, index, mergeInstance, numAttributes, numValues, replaceMissingValues, setValue, setValueSparse, toDoubleArray, toStringNoWeight, toStringNoWeight, value`

- ## Field Details

  - ### s_numericAfterDecimalPoint

    public static int s_numericAfterDecimalPoint
    Default max number of digits after the decimal point for numeric values

- ## Constructor Details

  - ### AbstractInstance

    public AbstractInstance()

- ## Method Details

  - ### attribute

    public Attribute attribute(int index)
    Returns the attribute with the given index.
    Specified by:
      `attribute` in interface `Instance`
    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

    public Attribute attributeSparse(int indexOfIndex)
    Returns the attribute with the given index in the sparse representation.
    Specified by:
      `attributeSparse` in interface `Instance`
    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

    public Attribute classAttribute()
    Returns class attribute.
    Specified by:
      `classAttribute` in interface `Instance`
    Returns:
      the class attribute
    Throws:
      `UnassignedDatasetException` - if the class is not set or the instance doesn't have access to a dataset

  - ### classIndex

    public int classIndex()
    Returns the class attribute's index.
    Specified by:
      `classIndex` in interface `Instance`
    Returns:
      the class index as an integer
    Throws:
      `UnassignedDatasetException` - if instance doesn't have access to a dataset

  - ### classIsMissing

    public boolean classIsMissing()
    Tests if an instance's class is missing.
    Specified by:
      `classIsMissing` in interface `Instance`
    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

    public double classValue()
    Returns an instance's class value in internal format. (ie. as a floating-point number)
    Specified by:
      `classValue` in interface `Instance`
    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

  - ### 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.
    Specified by:
      `dataset` in interface `Instance`
    Returns:
      the dataset the instance has accesss to

  - ### 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.
    Specified by:
      `deleteAttributeAt` in interface `Instance`
    Parameters:
      `position` - the attribute's position
    Throws:
      `RuntimeException` - if the instance has access to a dataset

  - ### enumerateAttributes

    public Enumeration<Attribute> enumerateAttributes()
    Returns an enumeration of all the attributes.
    Specified by:
      `enumerateAttributes` in interface `Instance`
    Returns:
      enumeration of all the attributes
    Throws:
      `UnassignedDatasetException` - if the instance doesn't have access to a dataset

  - ### equalHeaders

    public boolean equalHeaders(Instance inst)
    Tests if the headers of two instances are equivalent.
    Specified by:
      `equalHeaders` in interface `Instance`
    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

    public String equalHeadersMsg(Instance inst)
    Checks if the headers of two instances are equivalent. If not, then returns a message why they differ.
    Specified by:
      `equalHeadersMsg` in interface `Instance`
    Parameters:
      `dataset` - 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

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

  - ### 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.
    Specified by:
      `insertAttributeAt` in interface `Instance`
    Parameters:
      `position` - the attribute's position
    Throws:
      `RuntimeException` - if the instance has accesss to a dataset
      `IllegalArgumentException` - if the position is out of range

  - ### isMissing

    public boolean isMissing(int attIndex)
    Tests if a specific value is "missing".
    Specified by:
      `isMissing` in interface `Instance`
    Parameters:
      `attIndex` - the attribute's index
    Returns:
      true if the value is "missing"

  - ### isMissingSparse

    public boolean isMissingSparse(int indexOfIndex)
    Tests if a specific value is "missing", given an index in the sparse representation.
    Specified by:
      `isMissingSparse` in interface `Instance`
    Parameters:
      `indexOfIndex` - the index of the attribute's index
    Returns:
      true if the value is "missing"

  - ### isMissing

    public boolean isMissing(Attribute att)
    Tests if a specific value is "missing". The given attribute has to belong to a dataset.
    Specified by:
      `isMissing` in interface `Instance`
    Parameters:
      `att` - the attribute
    Returns:
      true if the value is "missing"

  - ### numClasses

    public int numClasses()
    Returns the number of class labels.
    Specified by:
      `numClasses` in interface `Instance`
    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

  - ### 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.
    Specified by:
      `setClassMissing` in interface `Instance`
    Throws:
      `UnassignedClassException` - if the class is not set
      `UnassignedDatasetException` - if the instance doesn't have access to a dataset

  - ### 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.
    Specified by:
      `setClassValue` in interface `Instance`
    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
      `UnaddignedDatasetException` - if the instance doesn't have access to a dataset

  - ### 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.
    Specified by:
      `setClassValue` in interface `Instance`
    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
      `IllegalArgumentException` - if the attribute is not nominal or a string, or the value couldn't be found for a nominal attribute

  - ### 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.
    Specified by:
      `setDataset` in interface `Instance`
    Parameters:
      `instances` - the reference to the dataset

  - ### 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.
    Specified by:
      `setMissing` in interface `Instance`
    Parameters:
      `attIndex` - the attribute's index

  - ### 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.
    Specified by:
      `setMissing` in interface `Instance`
    Parameters:
      `att` - the attribute

  - ### 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.
    Specified by:
      `setValue` in interface `Instance`
    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
      `IllegalArgumentException` - if the selected attribute is not nominal or a string, or the supplied value couldn't be found for a nominal attribute

  - ### 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.
    Specified by:
      `setValue` in interface `Instance`
    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

    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.
    Specified by:
      `setValue` in interface `Instance`
    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

  - ### setWeight

    public final void setWeight(double weight)
    Sets the weight of an instance.
    Specified by:
      `setWeight` in interface `Instance`
    Parameters:
      `weight` - the weight

  - ### relationalValue

    public final Instances relationalValue(int attIndex)
    Returns the relational value of a relational attribute.
    Specified by:
      `relationalValue` in interface `Instance`
    Parameters:
      `attIndex` - the attribute's index
    Returns:
      the corresponding relation as an Instances object
    Throws:
      `IllegalArgumentException` - if the attribute is not a relation-valued attribute
      `UnassignedDatasetException` - if the instance doesn't belong to a dataset.

  - ### relationalValue

    public final Instances relationalValue(Attribute att)
    Returns the relational value of a relational attribute.
    Specified by:
      `relationalValue` in interface `Instance`
    Parameters:
      `att` - the attribute
    Returns:
      the corresponding relation as an Instances object, null if missing
    Throws:
      `IllegalArgumentException` - if the attribute is not a relation-valued attribute
      `UnassignedDatasetException` - if the instance doesn't belong to a dataset.

  - ### stringValue

    public final String stringValue(int attIndex)
    Returns the value of a nominal, string, date, or relational attribute for the instance as a string.
    Specified by:
      `stringValue` in interface `Instance`
    Parameters:
      `attIndex` - the attribute's index
    Returns:
      the value as a string
    Throws:
      `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

    public final String stringValue(Attribute att)
    Returns the value of a nominal, string, date, or relational attribute for the instance as a string.
    Specified by:
      `stringValue` in interface `Instance`
    Parameters:
      `att` - the attribute
    Returns:
      the value as a string
    Throws:
      `IllegalArgumentException` - if the attribute is not a nominal, string, date, or relation-valued attribute.
      `UnassignedDatasetException` - if the instance doesn't belong to a dataset.

  - ### toStringMaxDecimalDigits

    public final 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.
    Specified by:
      `toStringMaxDecimalDigits` in interface `Instance`
    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

    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.
    Overrides:
      `toString` in class `Object`
    Returns:
      the instance's description as a string

  - ### 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.
    Specified by:
      `toString` in interface `Instance`
    Parameters:
      `attIndex` - the attribute's index
    Returns:
      the value's description as a string

  - ### toString

    public final 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.
    Specified by:
      `toString` in interface `Instance`
    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

    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.
    Specified by:
      `toString` in interface `Instance`
    Parameters:
      `att` - the attribute
    Returns:
      the value's description as a string

  - ### toString

    public final 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.
    Specified by:
      `toString` in interface `Instance`
    Parameters:
      `att` - the attribute
      `afterDecimalPoint` - the maximum number of decimal places to print
    Returns:
      the value's description as a string

  - ### value

    public double value(Attribute att)
    Returns an instance's attribute value in internal format. The given attribute has to belong to a dataset.
    Specified by:
      `value` in interface `Instance`
    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).

  - ### valueSparse

    public double valueSparse(int indexOfIndex)
    Returns an instance's attribute value in internal format, given an index in the sparse representation.
    Specified by:
      `valueSparse` in interface `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).

  - ### weight

    public final double weight()
    Returns the instance's weight.
    Specified by:
      `weight` in interface `Instance`
    Returns:
      the instance's weight as a double

  - ### getRevision

    public String getRevision()
    Returns the revision string.
    Specified by:
      `getRevision` in interface `RevisionHandler`
    Returns:
      the revision