/*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/*
* DenseInstance.java
* Copyright (C) 1999-2012 University of Waikato, Hamilton, New Zealand
*
*/
package weka.core;
import java.util.ArrayList;
import java.util.Enumeration;
/**
* Class for handling an instance. All values (numeric, date, nominal, string or
* relational) are internally stored as floating-point numbers. 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.
* <p>
*
* Typical usage (code from the main() method of this class):
* <p>
*
* <code>
* ... <br>
*
* // Create empty instance with three attribute values <br>
* Instance inst = new DenseInstance(3); <br><br>
*
* // Set instance's values for the attributes "length", "weight", and "position"<br>
* inst.setValue(length, 5.3); <br>
* inst.setValue(weight, 300); <br>
* inst.setValue(position, "first"); <br><br>
*
* // Set instance's dataset to be the dataset "race" <br>
* inst.setDataset(race); <br><br>
*
* // Print the instance <br>
* System.out.println("The instance: " + inst); <br>
*
* ... <br>
* </code>
* <p>
*
* All methods that change an instance's attribute values are safe, ie. a change
* of an instance's attribute values 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)
* @version $Revision: 9028 $
*/
public class DenseInstance extends AbstractInstance {
/** for serialization */
static final long serialVersionUID = 1482635194499365122L;
/**
* Constructor that copies the attribute values and the weight from the given
* instance. It does NOT perform a deep copy of the attribute values if the
* instance provided is also of type DenseInstance (it simply copies the
* reference to the array of values), otherwise it does. Reference to the
* dataset is set to null. (ie. the instance doesn't have access to
* information about the attribute types)
*
* @param instance the instance from which the attribute values and the weight
* are to be copied
*/
// @ ensures m_Dataset == null;
public DenseInstance(/* @non_null@ */Instance instance) {
if (instance instanceof DenseInstance) {
m_AttValues = ((DenseInstance) instance).m_AttValues;
} else {
m_AttValues = instance.toDoubleArray();
}
m_Weight = instance.weight();
m_Dataset = null;
}
/**
* 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)
*
* @param weight the instance's weight
* @param attValues a vector of attribute values
*/
// @ ensures m_Dataset == null;
public DenseInstance(double weight, /* @non_null@ */double[] attValues) {
m_AttValues = attValues;
m_Weight = weight;
m_Dataset = null;
}
/**
* 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)
*
* @param numAttributes the size of the instance
*/
// @ requires numAttributes > 0; // Or maybe == 0 is okay too?
// @ ensures m_Dataset == null;
public DenseInstance(int numAttributes) {
m_AttValues = new double[numAttributes];
for (int i = 0; i < m_AttValues.length; i++) {
m_AttValues[i] = Utils.missingValue();
}
m_Weight = 1;
m_Dataset = null;
}
/**
* 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 <code>new DenseInstance(instance)</code>
*
* @return the shallow copy
*/
// @ also ensures \result != null;
// @ also ensures \result instanceof DenseInstance;
// @ also ensures ((DenseInstance)\result).m_Dataset == m_Dataset;
@Override
public/* @pure@ */Object copy() {
DenseInstance result = new DenseInstance(this);
result.m_Dataset = m_Dataset;
return result;
}
/**
* Returns the index of the attribute stored at the given position. Just
* returns the given value.
*
* @param position the position
* @return the index of the attribute stored at the given position
*/
@Override
public/* @pure@ */int index(int position) {
return position;
}
/**
* 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.
*
* @param inst the instance to be merged with this one
* @return the merged instances
*/
@Override
public Instance mergeInstance(Instance inst) {
int m = 0;
double[] newVals = new double[numAttributes() + inst.numAttributes()];
for (int j = 0; j < numAttributes(); j++, m++) {
newVals[m] = value(j);
}
for (int j = 0; j < inst.numAttributes(); j++, m++) {
newVals[m] = inst.value(j);
}
return new DenseInstance(1.0, newVals);
}
/**
* Returns the number of attributes.
*
* @return the number of attributes as an integer
*/
// @ ensures \result == m_AttValues.length;
@Override
public/* @pure@ */int numAttributes() {
return m_AttValues.length;
}
/**
* Returns the number of values present. Always the same as numAttributes().
*
* @return the number of values
*/
// @ ensures \result == m_AttValues.length;
@Override
public/* @pure@ */int numValues() {
return m_AttValues.length;
}
/**
* 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.
*
* @param array containing the means and modes
* @throws IllegalArgumentException if numbers of attributes are unequal
*/
@Override
public void replaceMissingValues(double[] array) {
if ((array == null) || (array.length != m_AttValues.length)) {
throw new IllegalArgumentException("Unequal number of attributes!");
}
freshAttributeVector();
for (int i = 0; i < m_AttValues.length; i++) {
if (isMissing(i)) {
m_AttValues[i] = array[i];
}
}
}
/**
* 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.
*
* @param attIndex the attribute's index
* @param 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).
*/
@Override
public void setValue(int attIndex, double value) {
freshAttributeVector();
m_AttValues[attIndex] = 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().
*
* @param indexOfIndex the index of the attribute's index
* @param 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).
*/
@Override
public void setValueSparse(int indexOfIndex, double value) {
freshAttributeVector();
m_AttValues[indexOfIndex] = value;
}
/**
* Returns the values of each attribute as an array of doubles.
*
* @return an array containing all the instance attribute values
*/
@Override
public double[] toDoubleArray() {
double[] newValues = new double[m_AttValues.length];
System.arraycopy(m_AttValues, 0, newValues, 0, m_AttValues.length);
return newValues;
}
/**
* 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.
*
* @return the instance's description as a string
*/
@Override
public String toStringNoWeight() {
return toStringNoWeight(AbstractInstance.s_numericAfterDecimalPoint);
}
/**
* 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.
*
* @param afterDecimalPoint maximum number of digits after the decimal point
* for numeric values
*
* @return the instance's description as a string
*/
@Override
public String toStringNoWeight(int afterDecimalPoint) {
StringBuffer text = new StringBuffer();
for (int i = 0; i < m_AttValues.length; i++) {
if (i > 0)
text.append(",");
text.append(toString(i, afterDecimalPoint));
}
return text.toString();
}
/**
* Returns an instance's attribute value in internal format.
*
* @param attIndex the attribute's index
* @return 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).
*/
@Override
public/* @pure@ */double value(int attIndex) {
return m_AttValues[attIndex];
}
/**
* Deletes an attribute at the given position (0 to numAttributes() - 1).
*
* @param position the attribute's position
*/
@Override
protected void forceDeleteAttributeAt(int position) {
double[] newValues = new double[m_AttValues.length - 1];
System.arraycopy(m_AttValues, 0, newValues, 0, position);
if (position < m_AttValues.length - 1) {
System.arraycopy(m_AttValues, position + 1, newValues, position,
m_AttValues.length - (position + 1));
}
m_AttValues = newValues;
}
/**
* Inserts an attribute at the given position (0 to numAttributes()) and sets
* its value to be missing.
*
* @param position the attribute's position
*/
@Override
protected void forceInsertAttributeAt(int position) {
double[] newValues = new double[m_AttValues.length + 1];
System.arraycopy(m_AttValues, 0, newValues, 0, position);
newValues[position] = Utils.missingValue();
System.arraycopy(m_AttValues, position, newValues, position + 1,
m_AttValues.length - position);
m_AttValues = newValues;
}
/**
* Clones the attribute vector of the instance and overwrites it with the
* clone.
*/
private void freshAttributeVector() {
m_AttValues = toDoubleArray();
}
/**
* Main method for testing this class.
*
* @param options the commandline options - ignored
*/
// @ requires options != null;
public static void main(String[] options) {
try {
// Create numeric attributes "length" and "weight"
Attribute length = new Attribute("length");
Attribute weight = new Attribute("weight");
// Create vector to hold nominal values "first", "second", "third"
ArrayList<String> my_nominal_values = new ArrayList<String>(3);
my_nominal_values.add("first");
my_nominal_values.add("second");
my_nominal_values.add("third");
// Create nominal attribute "position"
Attribute position = new Attribute("position", my_nominal_values);
// Create vector of the above attributes
ArrayList<Attribute> attributes = new ArrayList<Attribute>(3);
attributes.add(length);
attributes.add(weight);
attributes.add(position);
// Create the empty dataset "race" with above attributes
Instances race = new Instances("race", attributes, 0);
// Make position the class attribute
race.setClassIndex(position.index());
// 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);
// Print the first attribute
System.out.println("First attribute: " + inst.attribute(0));
// Print the class attribute
System.out.println("Class attribute: " + inst.classAttribute());
// Print the class index
System.out.println("Class index: " + inst.classIndex());
// Say if class is missing
System.out.println("Class is missing: " + inst.classIsMissing());
// Print the instance's class value in internal format
System.out.println("Class value (internal format): " + inst.classValue());
// Print a shallow copy of this instance
Instance copy = (Instance) inst.copy();
System.out.println("Shallow copy: " + copy);
// Set dataset for shallow copy
copy.setDataset(inst.dataset());
System.out.println("Shallow copy with dataset set: " + copy);
// Unset dataset for copy, delete first attribute, and insert it again
copy.setDataset(null);
copy.deleteAttributeAt(0);
copy.insertAttributeAt(0);
copy.setDataset(inst.dataset());
System.out.println("Copy with first attribute deleted and inserted: "
+ copy);
// Enumerate attributes (leaving out the class attribute)
System.out.println("Enumerating attributes (leaving out class):");
Enumeration enu = inst.enumerateAttributes();
while (enu.hasMoreElements()) {
Attribute att = (Attribute) enu.nextElement();
System.out.println(att);
}
// Headers are equivalent?
System.out.println("Header of original and copy equivalent: "
+ inst.equalHeaders(copy));
// Test for missing values
System.out.println("Length of copy missing: " + copy.isMissing(length));
System.out.println("Weight of copy missing: "
+ copy.isMissing(weight.index()));
System.out.println("Length of copy missing: "
+ Utils.isMissingValue(copy.value(length)));
// Prints number of attributes and classes
System.out.println("Number of attributes: " + copy.numAttributes());
System.out.println("Number of classes: " + copy.numClasses());
// Replace missing values
double[] meansAndModes = { 2, 3, 0 };
copy.replaceMissingValues(meansAndModes);
System.out.println("Copy with missing value replaced: " + copy);
// Setting and getting values and weights
copy.setClassMissing();
System.out.println("Copy with missing class: " + copy);
copy.setClassValue(0);
System.out.println("Copy with class value set to first value: " + copy);
copy.setClassValue("third");
System.out.println("Copy with class value set to \"third\": " + copy);
copy.setMissing(1);
System.out.println("Copy with second attribute set to be missing: "
+ copy);
copy.setMissing(length);
System.out.println("Copy with length set to be missing: " + copy);
copy.setValue(0, 0);
System.out.println("Copy with first attribute set to 0: " + copy);
copy.setValue(weight, 1);
System.out.println("Copy with weight attribute set to 1: " + copy);
copy.setValue(position, "second");
System.out.println("Copy with position set to \"second\": " + copy);
copy.setValue(2, "first");
System.out.println("Copy with last attribute set to \"first\": " + copy);
System.out.println("Current weight of instance copy: " + copy.weight());
copy.setWeight(2);
System.out.println("Current weight of instance copy (set to 2): "
+ copy.weight());
System.out.println("Last value of copy: " + copy.toString(2));
System.out.println("Value of position for copy: "
+ copy.toString(position));
System.out.println("Last value of copy (internal format): "
+ copy.value(2));
System.out.println("Value of position for copy (internal format): "
+ copy.value(position));
} catch (Exception e) {
e.printStackTrace();
}
}
/**
* Returns the revision string.
*
* @return the revision
*/
@Override
public String getRevision() {
return RevisionUtils.extract("$Revision: 9028 $");
}
}