exampleset.java

著名的开源仿真软件yale

/*
 *  YALE - Yet Another Learning Environment
 *  Copyright (C) 2002, 2003
 *      Simon Fischer, Ralf Klinkenberg, Ingo Mierswa, 
 *          Katharina Morik, Oliver Ritthoff
 *      Artificial Intelligence Unit
 *      Computer Science Department
 *      University of Dortmund
 *      44221 Dortmund,  Germany
 *  email: [e-mail]
 *  web:   http://yale.cs.uni-dortmund.de/
 *
 *  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., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 *  USA.
 */
package edu.udo.cs.yale.example;

import edu.udo.cs.yale.operator.ResultObject;
import edu.udo.cs.yale.operator.OperatorException;

import java.util.Collection;
import java.util.Set;
import java.io.File;
import java.io.IOException;

/**
 *  Interface definition for all example sets.
 *
 *  @version $Id: ExampleSet.java,v 2.10 2003/08/06 14:11:04 fischer Exp $
 */
public interface ExampleSet extends ResultObject, Cloneable {

    // -------------------- regular attributes --------------------

    /** Returns the number of attributes of the examples in this set. */
    public int getNumberOfAttributes();

    /** Returns the Attribute with the given index. */
    public Attribute getAttribute(int index);

    /** Returns the attribute with the given name. */
    public Attribute getAttribute(String name);

    /** Adds a new attribute.
     *  @throws RuntimeException Iff the ExampleSet already contains the attribute.  */
    public void addAttribute(Attribute attribute);

    /** Adds all attributes in the collection. */
    public void addAllAttributes(Collection c);

    /** Copies thie list of attributes from the given example set. */
    public void setAttributes(ExampleSet exampleSet);

    /** Removes an attribute. 
     *  @exception java.util.NoSuchElementException If the attribute does not exist. */
    public void removeAttribute(Attribute attribute);

    /** Removes the attribute with the given index. 
     *  @return The removed attribute */
    public Attribute removeAttribute(int index);

    /** Removes all attributes. */
    public void removeAllAttributes();

    // ---------- special attributes ------------

    /** Adds a special, i.e. named {@link Attribute} to the example set. Special attributes
     *  are labels, weights, etc., i.e. all non-regular attributes. If the attribute is 
     *  already defined, it is replaced. By convention, special attributes are named
     *  lowercase.*/
    public void setSpecialAttribute(String name, Attribute attribute);

    /** Returns a named special attribute previously added by
     *  {@link #setSpecialAttribute(String,Attribute)}. If no attribute with the given name
     *  is found, null is returned. */
    public Attribute getSpecialAttribute(String name);

    // ---------- convenience methods for special attributes ------------

    /** Returns the label attribute used for classification and regression. */
    public Attribute getLabel();

    /** Sets the label attribute used for classification and regression. */
    public void setLabel(Attribute label);

    /** Returns the weight attribute. */
    public Attribute getWeight();

    /** Seturns the weight attribute. */
    public void setWeight(Attribute weight);

    /** Creates a new weight attribute. 
     *  If the example set already has a weight attribute, it is overwritten. */
    public Attribute createWeightAttribute();

    /** Returns the label predicted by some model. */
    public Attribute getPredictedLabel();

    /** Sets the predicted label. */
    public void setPredictedLabel(Attribute predictedLabel);

    /** Creates a new predicted label the type of which is based on the label.
     *  If the example set already has a predicted label, it is overwritten. 
     *  @throws OperatorException If the label is not set and therefore we cannot determine the value type */
    public Attribute createPredictedLabel() throws OperatorException;

    /** Removes the predicted label. */
    public void clearPredictedLabel();

    /** Returns the cluster attribute. */
    public Attribute getCluster();

    /** Sets the cluster attribute. */
    public void setCluster(Attribute cluster);

    /** Creates a new cluster attribute of appropriate type.
     *  If the example set already has a cluster attribute, it is overwritten. */
    public Attribute createClusterAttribute() throws OperatorException;

    /** Returns the ID attribute, i.e. an attribute containing a unique integer for
     *  each example. May be null. */
    public Attribute getIdAttribute();

    /** Sets the ID attribute. */
    public void setIdAttribute(Attribute idAttribute);

    // -------------------- Attributes --------------------

    /** Returns the number of examples in this example set. */
    public int getSize();

    /** Returns a reader that can be used to iterate over all examples of this set. */
    public ExampleReader getExampleReader();

    /** Returns the underlying example table. */
    public ExampleTable getExampleTable();

    // -------------------- Misc --------------------

    /** Writes the data and the attribute description to a file. */
    public void writeToFile(File dataFile, File attFile) throws IOException;

    /** Writes the data and the attribute description to a file.
     *  @param format specified by {@link edu.udo.cs.yale.operator.SparseFormatExampleSource}.*/
    public void writeToFileSparse(int format, File dataFile, File attFile) throws IOException;

    /** Sets arbitrary user data, e.g. to cache certain performance values etc.
     *  Make sure to use a unique prefix for your keys. */
    public void setUserData(String key, Object data);

    /** Returns the user data set by setUserData()
     *  @see edu.udo.cs.yale.example.ExampleSet#setUserData(String,Object) */
    public Object getUserData(String key);

    /** Returns all askable keys of user data. */
    public Set getUserDataKeys();

    /** Clears all user data. This method must be called whenever attributes are added 
     *  or removed or the example set changes in a way that makes a new calculation of 
     *  such values necessary. */
    public void clearUserData();

    /** Returns the last attribute index belonging to the block starting
     *  at <i>startindex</i>. */
    public int getBlockEndIndex(int startindex);

    /** Clones the example set. */
    public Object clone();

    /** True if all attributes are equal. */
    public boolean equals(Object o);
}