exampleset.java

一个很好的LIBSVM的JAVA源码。对于要研究和改进SVM算法的学者。可以参考。来自数据挖掘工具YALE工具包。

/*
 *  YALE - Yet Another Learning Environment
 *  Copyright (C) 2001-2004
 *      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.21 2004/09/17 12:57:38 ingomierswa Exp $
 */
public interface ExampleSet extends ResultObject, Cloneable {


    // -------------------- names of special attributes -----------
    public static final String ID_NAME          = "id";
    public static final String LABEL_NAME       = "label";
    public static final String PREDICTION_NAME  = "prediction";
    public static final String CLUSTER_NAME     = "cluster";
    public static final String WEIGHT_NAME      = "weight";
    public static final String BATCH_NAME       = "batch";

    // -------------------- 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. This can be a regular attribute or a special attribute. */
    public Attribute getAttribute(String name);

    /** Returns true if this example set contains the given attribute. */
    public boolean contains(Attribute attribute);

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

    /** Adds all attributes in the collection. Ignores all attributes which had been already added. */
    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. Special attributes are also delivered by {@link #getAttribute(String name)}. */
    public void setSpecialAttribute(String name, Attribute attribute);

    /** Returns a collection of all keys of special attributes. */
    public Collection getSpecialAttributeNames();

    // ---------- 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);

    /** 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;

    /** Creates a new (single) special attribute with given name and value type.
     *  If the example set already has a special attribute with this name, it is overwritten. */
    public Attribute createSpecialAttribute(String name, int valueType) 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.io.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);

    // ------------------- Statistics ---------------
    
    /** Recalculate all attribute statistics. */
    public void recalculateAllAttributeStatistics();

    /** Recalculate the attribute statistics of the given attribute. */
    public void recalculateAttributeStatistics(Attribute attribute);
}