instance.java

一个数据挖掘软件ALPHAMINERR的整个过程的JAVA版源代码

/*
 *    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 2 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, write to the Free Software
 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
/*
 *    Instance.java
 *    Copyright (C) 1999 Eibe Frank
 *
 */
package weka.core;
import java.io.Serializable;
import java.util.Enumeration;

/**
 * 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.
 * <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 Instance(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 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 ([e-mail])
 * @version $Revision$
 */
public class Instance implements Copyable, Serializable {
	/**
	 * 
	 */
	private static final long serialVersionUID = 6712692772983932211L;
	/** Constant representing a missing value. */
	protected static final double MISSING_VALUE = Double.NaN;
	/**
	 * The dataset the instance has access to. Null if the instance doesn't have
	 * access to any dataset. Only if an instance has access to a dataset, it
	 * knows about the actual attribute types.
	 */
	protected Instances m_Dataset;
	/** The instance's attribute values. */
	protected double[] m_AttValues;
	/** The instance's weight. */
	protected double m_Weight;

	/**
	 * 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)
	 * 
	 * @param instance
	 *            the instance from which the attribute values and the weight
	 *            are to be copied
	 */
	public Instance(Instance instance) {
		m_AttValues = instance.m_AttValues;
		m_Weight = instance.m_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
	 */
	public Instance(double weight, 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
	 */
	public Instance(int numAttributes) {
		m_AttValues = new double[numAttributes];
		for (int i = 0; i < m_AttValues.length; i++) {
			m_AttValues[i] = MISSING_VALUE;
		}
		m_Weight = 1;
		m_Dataset = null;
	}

	/**
	 * Returns the attribute with the given index.
	 * 
	 * @param index
	 *            the attribute's index
	 * @return the attribute at the given position
	 * @exception UnassignedDatasetException
	 *                if instance doesn't have access to a dataset
	 */
	public Attribute attribute(int index) {
		if (m_Dataset == null) {
			throw new UnassignedDatasetException("Instance doesn't have access to a dataset!");
		}
		return m_Dataset.attribute(index);
	}

	/**
	 * Returns the attribute with the given index. Does the same thing as
	 * attribute().
	 * 
	 * @param indexOfIndex
	 *            the index of the attribute's index
	 * @return the attribute at the given position
	 * @exception UnassignedDatasetException
	 *                if instance doesn't have access to a dataset
	 */
	public Attribute attributeSparse(int indexOfIndex) {
		if (m_Dataset == null) {
			throw new UnassignedDatasetException("Instance doesn't have access to a dataset!");
		}
		return m_Dataset.attribute(indexOfIndex);
	}

	/**
	 * Returns class attribute.
	 * 
	 * @return the class attribute
	 * @exception UnassignedDatasetException
	 *                if the class is not set or the instance doesn't have
	 *                access to a dataset
	 */
	public Attribute classAttribute() {
		if (m_Dataset == null) {
			throw new UnassignedDatasetException("Instance doesn't have access to a dataset!");
		}
		return m_Dataset.classAttribute();
	}

	/**
	 * Returns the class attribute's index.
	 * 
	 * @return the class index as an integer
	 * @exception UnassignedDatasetException
	 *                if instance doesn't have access to a dataset
	 */
	public int classIndex() {
		if (m_Dataset == null) {
			throw new UnassignedDatasetException("Instance doesn't have access to a dataset!");
		}
		return m_Dataset.classIndex();
	}

	/**
	 * Tests if an instance's class is missing.
	 * 
	 * @return true if the instance's class is missing
	 * @exception UnassignedClassException
	 *                if the class is not set or the instance doesn't have
	 *                access to a dataset
	 */
	public boolean classIsMissing() {
		if (classIndex() < 0) {
			throw new UnassignedClassException("Class is not set!");
		}
		return isMissing(classIndex());
	}

	/**
	 * Returns an instance's class value in internal format. (ie. as a
	 * floating-point number)
	 * 
	 * @return 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).
	 * @exception UnassignedClassException
	 *                if the class is not set or the instance doesn't have
	 *                access to a dataset
	 */
	public double classValue() {
		if (classIndex() < 0) {
			throw new UnassignedClassException("Class is not set!");
		}
		return value(classIndex());
	}

	/**
	 * 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 Instance(instance)</code>
	 * 
	 * @return the shallow copy
	 */
	public Object copy() {
		Instance result = new Instance(this);
		result.m_Dataset = m_Dataset;
		return result;
	}

	/**
	 * 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.
	 * 
	 * @return the dataset the instance has accesss to
	 */
	public Instances dataset() {
		return m_Dataset;
	}

	/**
	 * 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.
	 * 
	 * @param pos
	 *            the attribute's position
	 * @exception RuntimeException
	 *                if the instance has access to a dataset
	 */
	public void deleteAttributeAt(int position) {
		if (m_Dataset != null) {
			throw new RuntimeException("Instance has access to a dataset!");
		}
		forceDeleteAttributeAt(position);
	}

	/**
	 * Returns an enumeration of all the attributes.
	 * 
	 * @return enumeration of all the attributes
	 * @exception UnassignedDatasetException
	 *                if the instance doesn't have access to a dataset
	 */
	public Enumeration emerateAttributes() {
		if (m_Dataset == null) {
			throw new UnassignedDatasetException("Instance doesn't have access to a dataset!");
		}
		return m_Dataset.emerateAttributes();
	}

	/**
	 * Tests if the headers of two instances are equivalent.
	 * 
	 * @param instance
	 *            another instance
	 * @return true if the header of the given instance is equivalent to this
	 *         instance's header
	 * @exception UnassignedDatasetException
	 *                if instance doesn't have access to any dataset
	 */
	public boolean equalHeaders(Instance inst) {
		if (m_Dataset == null) {
			throw new UnassignedDatasetException("Instance doesn't have access to a dataset!");
		}
		return m_Dataset.equalHeaders(inst.m_Dataset);
	}

	/**
	 * 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
	 */
	public int index(int position) {
		return 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.
	 * 
	 * @param pos
	 *            the attribute's position
	 * @exception RuntimeException
	 *                if the instance has accesss to a dataset
	 * @exception IllegalArgumentException
	 *                if the position is out of range
	 */
	public void insertAttributeAt(int position) {
		if (m_Dataset != null) {
			throw new RuntimeException("Instance has accesss to a dataset!");
		}
		if ((position < 0) || (position > numAttributes())) {
			throw new IllegalArgumentException("Can't insert attribute: index out " + "of range");
		}
		forceInsertAttributeAt(position);
	}

	/**
	 * Tests if a specific value is "missing".
	 * 
	 * @param attIndex
	 *            the attribute's index
	 */
	public boolean isMissing(int attIndex) {
		try {
			if (Double.isNaN(m_AttValues[attIndex])) {
				return true;
			}