exampletable.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.tools.LogService;
import edu.udo.cs.yale.tools.att.AttributeSet;
import edu.udo.cs.yale.operator.OperatorException;
import edu.udo.cs.yale.operator.UserError;

import java.io.File;
import java.util.List;
import java.util.Iterator;
import java.util.ArrayList;
import java.util.LinkedList;
import java.util.ListIterator;

/** This class is the core data supplier for example sets.
 *  Several example sets can use the same data and access the attribute values
 *  by reference.
 * 
 *  @author Simon, Ingo
 *  @version $Id: ExampleTable.java,v 2.14 2003/07/24 09:52:52 fischer Exp $
 */
public abstract class ExampleTable {

    private int currentlyHighestBlockNr = 1000;

    /** List of instances of {@link Attribute}. The <i>i</i>-th entry in the list belongs to the <i>i</i>-th data column.
     *  Whenever attributes are removed from the list of attributes (e.g. they were intermediate predicted
     *  labels used only within a validation chain), the succeeding entries do not move up, but the entry is
     *  replaced by a null entry and this index is added to {@link ExampleTable#unusedColumnList} as an Integer. */
    private List attributes = new ArrayList();

    /** List of Integers referencing indices of columns that were removed,
     *  e.g. predicted labels that were used within a validation chain but 
     *  are not needed any longer. Any of the columns in this list may be
     *  used when a new attribute is created. The list is used as a queue.*/
    private List unusedColumnList = new LinkedList();

    /** Marks the example table as sparse. */
    private boolean sparse = false;

    /** Returns the number of examples. */
    public abstract int getSize();

    /** Returns an Iterator for example data given as <code>DataRow</code>
     *  objects. */
    public abstract DataRowReader getDataReader();

    /** Creates a new ExampleTable.
     *  @param attributes List of {@link Attribute}. The indices of the attibutes
     *  are set to values reflecting their position in the list. */
    public ExampleTable(List attributes) {
	addAttributes(attributes);
    }

    // ------------------------------------------------------------

    /** If sparse is true, the ExampleTable is marked as sparse.
     *  This has no actual influence on the behavior of the class. It is nothing more
     *  than a hint for operators that may use it. */
    public void setSparse(boolean sparse) {
	this.sparse = sparse;
    }

    /** Returns true if the used data representation is sparse. */
    public boolean isSparse() {
	return sparse;
    }

    /** Returns a new array containing all {@link Attribute}s.*/
    public Attribute[] getAttributes() {
	Attribute[] attribute = new Attribute[attributes.size()];
	attributes.toArray(attribute);
	return attribute;
    }

    /** Returns the attribute of the column number <i>i</i>.
     *  Attention: This value may return null if the column was marked unused. */
    public Attribute getAttribute(int i) {
	return (Attribute)attributes.get(i);
    }

    /** Returns the attribute with the given name. */
    public Attribute findAttribute(String name) throws OperatorException {
	if (name == null) return null;
	Iterator i = attributes.iterator();
	while (i.hasNext()) {
	    Attribute att = (Attribute)i.next();
	    if (att != null) {
		if (att.getName().equals(name))
		    return att;
	    }
	}
	throw new UserError(null, 111, name);
    }

    /** Adds all {@link Attribute}s in <code>newAttributes</code> to the end of the list of
     *  attributes, creating new data columns if necessary. */
    public void addAttributes(List newAttributes) {
	Iterator i = newAttributes.iterator();
	while(i.hasNext()) 
	    addAttribute((Attribute)i.next());
    }

    /** Adds the attribute to the list of attributes assigning it a free column index. */
    public int addAttribute(Attribute a) {
	int index = -1;
	if (unusedColumnList.size() > 0) {
	    index = ((Integer)unusedColumnList.remove(0)).intValue();
	    LogService.logMessage("Reusing data column "+index+".", LogService.MINIMUM);
	    attributes.set(index, a);
	} else {
	    index = attributes.size();
	    attributes.add(a);
	}
	a.setIndex(index);
	return index;
    }

    /** Equivalent to calling <code>removeAttribute(attribute.getIndex())</code>. */
    public void removeAttribute(Attribute attribute) {
	removeAttribute(attribute.getIndex());
    }

    /** Sets the attribute with the given index to null. Afterwards, this column
     *  can be reused. Callers must make sure, that no other example set contains a
     *  reference to this column. Otherwise its data will be messed up. Ususally
     *  this is only possible if an operator generates intermediate attributes,
     *  like a validation chain or a feature generator. 
     *  If the attribute already was removed, this method returns silently. */
    public void removeAttribute(int index) {
	Attribute a = (Attribute)attributes.get(index);
	if (a == null) return;
	LogService.logMessage("Removing attribute '"+a.getName() + "'. Column "+a.getIndex() + " will be reused.", LogService.MINIMUM);
	attributes.set(index, null);
	unusedColumnList.add(new Integer(index));
    }

    /** Returns the number of attributes. Attention: Callers that use a for-loop 
     *  and retrieving {@link Attribute}s by calling {@link ExampleTable#getAttribute(int)}
     *  must keep in mind, that some of these attributes may be null. */
    protected int getNumberOfAttributes() {
	return attributes.size();
    }

    /** Returns the number of non null attributes. 
     *  Attention: Since there are null attributes in the list, the return value of this method
     *  must not be used in a for-loop!
     *  @see ExampleTable#getNumberOfAttributes(). */
    public int getAttributeCount() {
	return attributes.size() - unusedColumnList.size();
    }

    /** Gets the currently highest used block number. */
    public int getHighestBlockNr() {
	return currentlyHighestBlockNr;
    }

    /** Returns a new unused blockNr.
     *  BUG:  Achtung, wenn Attributdatei Blocknummer enthaelt. Wird hier nicht beruecksichtigt. */
    public int getNextFreeBlockNr() {
	return ++currentlyHighestBlockNr;
    }

    /** Returns the last attribute index belonging to the block starting
     *  at startindex. */
    public int getBlockEndIndex(int startindex) {
  	int blockNr = getAttribute(startindex).getBlockNr();
	if (blockNr != Attribute.UNDEFINED_BLOCK_NR) {
	    for (int i = startindex+1; i < getNumberOfAttributes(); i++) {
		Attribute att = getAttribute(i);
		if ((att == null) || (att.getBlockNr() != blockNr)) return i-1;
	    }
	    return getNumberOfAttributes()-1;
	} else {
	    return startindex;
	}
    }


    /** Returns an Attribute equal to <code>attribute</code>*/
    public Attribute getAttribute(Attribute attribute) {
    	for (int i = 0; i < getNumberOfAttributes(); i++) {
    	    Attribute a = getAttribute(i);
	    if ((a != null) && a.equals(attribute))
		return a;
    	}
  	return null;
    }

    // ------------------------------------------------------------

    /** Returns a new example set with all attributes of the given attribute set. */
    public ExampleSet createExampleSet(AttributeSet attributeSet) {
	ExampleSet exampleSet = new SimpleExampleSet(this, attributeSet.getRegularAttributes());
	Iterator i = attributeSet.getSpecialNames().iterator();
	while (i.hasNext()) {
	    String name = (String)i.next();
	    exampleSet.setSpecialAttribute(name, attributeSet.getSpecialAttribute(name));
	}
	return exampleSet;
    }

    /** Returns a new example set with all attributes switched on. */
    public ExampleSet createCompleteExampleSet(Attribute label, 
					       Attribute predictedLabel,
					       Attribute weight,
					       Attribute idAttribute) {
	return new SimpleExampleSet(this, label, predictedLabel, weight, idAttribute);
    }

    // ------------------------------------------------------------

    public String toString() {
	return "ExampleTable: " + attributes.size() + " attributes:" + attributes;
    }
}