batchedexampleset.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;

/** Objects of this class manage a set of examples having a batch index attribute
 *  like it is used in time-oriented experiments with batch-wise data processing.
 *  Iterators (<tt>ExampleReader</tt>) provided by this class only iterate examples
 *  within a specified range of a first and a last batch index to use. Examples with
 *  batch index attribute values outside this time range are skipped. This way this
 *  class allows to easily provide a time window on an example set (given the basic
 *  underlying example set, the batch index attribute, and the batch index value range
 *  to use).
 *
 *  <h4>Typical use of this class</h4>
 *  This class is typically used for time-oriented experiments, e.g. for simulated 
 *  concept drift scenarios (see e.g. class {@link edu.udo.cs.yale.operator.time.ConceptDriftSimulator}).
 *
 *  @see edu.udo.cs.yale.operator.time.ConceptDriftSimulator
 *  @yale.todo Class comments in English
 *  @author Ralf Klinkenberg
 *  @version $Id: BatchedExampleSet.java,v 2.6 2003/07/24 09:52:52 fischer Exp $
 */
public class BatchedExampleSet extends ExampleSetAdapter implements Cloneable {
    /* History:
     *   2002/04/22, Ralf Klinkenberg: class implemented for inductive learning scenarios.
     *   2002/06/23, Ralf Klinkenberg: method 'getOriginalExampleSet()' added for 'BatchTransductionWindowLearner'.
     */

    /** Condition for {@link BatchedExampleSet}. Filters all examples whose batch is outside the range.
     */
    private class BatchCondition implements Condition {
	public boolean  conditionOk (Example example) {
	    if (example.getValue(batchIndexAttribute) < ((double)firstBatch)) return false;
	    if (example.getValue(batchIndexAttribute) > ((double)lastBatch))  return false;
	    return true;
	}
    }

    /** Reference to the attribute to be used as batch index attribute. */
    private Attribute batchIndexAttribute;

    /** First batch = lower bound of batch index attribute value range for examples to be considered. */
    private int firstBatch;
    /** Last batch = upper bound of batch index attribute value range for examples to be considered. */
    private int lastBatch; 

    /** Example filter for iterator ConditionExampleReader. */
    private BatchCondition exampleSelectionCondition = new BatchCondition();

    /** This constructor creates a view on the ExampleSet hiding all examples whose 
     *  value of the batchIndexAttribute is outside the range [<tt>firstBatch</tt> .. <tt>lastBatch</tt>].
     *  @param firstBatch First batch inclusive
     *  @param lastBatch Last batch inclusive
     *  @throws IllegalArgumentException If batchIndexAttribute is null.
     */
    public BatchedExampleSet(ExampleSet exampleSet, Attribute batchIndexAttribute,
			     int firstBatch, int lastBatch) {
	super(exampleSet);
	if (batchIndexAttribute == null) 
	    throw new IllegalArgumentException("Batch index attribute must not be null!");
	this.batchIndexAttribute = batchIndexAttribute;
	this.firstBatch = firstBatch;
	this.lastBatch  = lastBatch;
    }

    /** Equivalent to calling new BatchedExampleSet(exampleSet, batchIndexAttribute, batch, batch) */
    public BatchedExampleSet(ExampleSet exampleSet, Attribute batchIndexAttribute, int batch) {
	this(exampleSet, batchIndexAttribute, batch, batch);
    }

    /** This constructor creates a view on the ExampleSet hiding all examples whose 
     *  value of the batchIndexAttribute is outside the range [<tt>firstBatch</tt> .. <tt>lastBatch</tt>].
     *  The special attribute named &qout;batch&quot; is used as the batch attribute.
     *  @param firstBatch First batch inclusive
     *  @param lastBatch Last batch inclusive
     *  @throws IllegalArgumentException Iff there is no special attribute named "batch"
     */
    public BatchedExampleSet(ExampleSet exampleSet,
			     int firstBatch, int lastBatch) {
	this(exampleSet, exampleSet.getSpecialAttribute("batch"), firstBatch, lastBatch);
    }

    /** Equivalent to calling BatchedExampleSet(exampleSet, batch, batch). */
    public BatchedExampleSet(ExampleSet exampleSet, int batch) {
	this(exampleSet, batch, batch);
    }


    /** Clone constructor. */
    protected BatchedExampleSet(BatchedExampleSet exampleSet) {
	super(exampleSet);
	this.batchIndexAttribute  = exampleSet.batchIndexAttribute;
	this.firstBatch           = exampleSet.firstBatch;
	this.lastBatch            = exampleSet.lastBatch;
    }

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

    /** Clones the example set. */
    public Object  clone() {
	return new BatchedExampleSet(this);
    }

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

    /** Returns an example iterator for reading (a <tt>ExampleReader</tt>, more precisely a
     *  <tt>BatchedExampleReader</tt>, which is a sub class of <tt>ConditionExampleReader</tt>).
     */
    public ExampleReader getExampleReader() {
	// this cannot happen
	if (exampleSelectionCondition == null) {
	    throw new RuntimeException("BatchedExampleSet.getExampleReader(): no example selection condition defined!");
//  	    LogService.logMessage ("BatchedExampleSet.getExampleReader(): no example selection condition defined!",
//  				   LogService.WARNING);
//  	    return super.getExampleReader();
	}
	return new ConditionExampleReader (super.getExampleReader(), exampleSelectionCondition);
    }

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

    /** Returns the batch index attribute used for the batch-oriented (= time-oriented) selection of examples. */
    public Attribute getBatchIndexAttribute() {
	return batchIndexAttribute;
    }

    /** Returns the first batch index value for which examples are selected. */
    public int getFirstBatch() {
	return firstBatch;
    }

    /** Returns the last batch index value for which examples are selected. */
    public int getLastBatch() {
	return lastBatch;
    }

}