batchwindowlearner.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.operator.learner;

import edu.udo.cs.yale.MethodNotSupportedException;
import edu.udo.cs.yale.operator.Operator;
import edu.udo.cs.yale.operator.OperatorChain;
import edu.udo.cs.yale.operator.IOObject;
import edu.udo.cs.yale.operator.IOContainer;
import edu.udo.cs.yale.operator.IODescription;
import edu.udo.cs.yale.operator.IllegalInputException;
import edu.udo.cs.yale.operator.OperatorException;
import edu.udo.cs.yale.operator.FatalException;
import edu.udo.cs.yale.operator.learner.Learner;
import edu.udo.cs.yale.operator.learner.Model;
import edu.udo.cs.yale.operator.parameter.*;
import edu.udo.cs.yale.operator.performance.PerformanceCriterion;
import edu.udo.cs.yale.operator.performance.PerformanceVector;
import edu.udo.cs.yale.operator.performance.PerformanceEvaluator;
import edu.udo.cs.yale.example.Attribute;
import edu.udo.cs.yale.example.Example;
import edu.udo.cs.yale.example.ExampleSet;
import edu.udo.cs.yale.example.ExampleReader;
import edu.udo.cs.yale.example.BatchedExampleSet;
import edu.udo.cs.yale.tools.LogService;
import edu.udo.cs.yale.tools.ResultService;
import edu.udo.cs.yale.tools.ParameterService;
import edu.udo.cs.yale.tools.param.OperatorParams;

import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

/** A <code>BatchWindowLearner</code> is an operator that encapsulates the 
 *  learning step of a machine learning method at one time step (batch) 
 *  within a simulated time series experiment, for example within a 
 *  concept drift simulation.
 *     An example experiment setup can be found in the documentation
 *  of the {@link edu.udo.cs.yale.operator.time.ConceptDriftSimulator}.
 *
 *  <!-- ===== The following information is automatically generated for the Yale Tutorial:
 *
 *  <h4>Parameters:</h4>
 *  <ul>
 *    <li><b>[model_file]</b>:
 *             If this value is set, the model is saved to a file and can
 *             be used in other experiments using a {@link edu.udo.cs.yale.operator.ModelLoader}.</li>
 *    <li><b>[minimum_window_size]</b>:
 *             ...</li>
 *    <li><b>[maximum_window_size]</b>:
 *             ... maximum size of the time window on the training examples 
 *             ... default = unlimited
 *                 (only serves to reduce run-time, with hopefully minimal 
 *                 effect on performance)
 *             ...</li>
 *  </ul>
 *
 *  <h4>Operator-Input</h4>
 *  <ol>
 *    <li>{@link BatchedExampleSet}:
 *              the training set, whose examples must have a batch index
 *              attribute value, which is why the example set must be of
 *              class <tt>BatchedExampleSet</tt> instead of just class
 *              <tt>ExampleSet</tt>.  ... </li>
 *  </ol>
 *
 *  <h4>Operator-Output</h4>
 *  <ol>
 *    <li>{@link Model}:
 *              ...</li>
 *  </ol>
 *
 *  <h4>Enclosed Operators</h4>
 *  A <code>BatchWindowLearner</code> operator chain needs to enclose at least
 *  one operator and may enclose arbitrarily many operators.
 *  <ol>
 *    <li>First operator: classifier learner that is able to estimate its
 *        performance (e.g. a <code>SVMLightLearner</code> or a <code>MySVMLearner</code>),
 *        and that (preferably) estimates it on the last batch only.</li>
 *  </ol>
 *
 *  <h4>Example configuration of this operator in an experiment chain (Yale configuration file in XML format):</h4>
 *  <pre>
 *  </pre>
 *
 *  ===== -->
 *
 *  @see edu.udo.cs.yale.operator.learner.BatchWeightLearner
 *  @see edu.udo.cs.yale.operator.time.ConceptDriftSimulator
 *  @see edu.udo.cs.yale.operator.time.ConceptDriftAdaptor
 *
 *  @yale.xmlclass BatchWindowLearner
 *  @yale.cite Klinkenberg/Joachims/2000a
 *
 *  @author Ralf Klinkenberg
 *  @version $Id: BatchWindowLearner.java,v 2.15 2003/09/04 14:56:57 klinkenb Exp $
 */
public class  BatchWindowLearner extends OperatorChain {
    // History:
    //   RK/2002/06/23:  first operator version;
    //   RK/2002/12/19:  bug fix in 'getMinNumberOfInnerOperators()' and 'getMaxNumberOfInnerOperators()';
    //                   merged with SF+IM's adaptations for the Yale GUI (different handling of fatal errors
    //                   and operator parameters);
    //   RK/2003/03/24:  merger of RK's Yale 1.0 version into Yale 2.0 completed;
    //   RK/2003/05/15:  parameter 'minimum_window_size' added;


    // public class  BatchWindowLearner extends BatchLearner {

    private static final Class[] INPUT_CLASSES = { BatchedExampleSet.class };       // in super class BatchLearner
    // private static final Class[] OUTPUT_CLASSES = { PerformanceVector.class };   // in super class ValidationChain
    //// output classes defined in method 'getOuputClasses' below

    protected String       modelFile;                            // in super class Learner
    // protected Operator  modelApplierAndPerformanceEvaluator;  // ...

    protected int          maximumWindowSize;                    // maximum size of the adaptive window (limited only for run time reasons and/or to avoid unreasonably large windows)
    protected int          minimumWindowSize;                    // minimum size of the adaptive window (limited only for run time reasons and/or to avoid unreasonably small windows)

    /** xi-alpha performance estimation of the enclosed SVM^light or mySVM (classification error, recall, and precision). */
    protected PerformanceVector  performanceEstimation;

    /** returns the minimum number of inner operators, here always 1, an enclosed learner. */
    public int getMinInnerOps() { return 1; }
    /** returns the maximum number of inner operators, here (almost) unlimnited. */
    // public int getMaxInnerOps() { return Integer.MAX_VALUE; }                    // in super class OperatorChain


    /** checks the correctness of the input and output classes requested and provided,
     *  respectively, by the encapsulated inner operators of this special <tt>OperatorChain</tt>.
     *  These input and output classes are OK, if the first inner operator returns a model and
     *  the (first or) last inner operator returns a performance vector.
     *  The method returns the output classes of the (first or) last encapsulated inner operator.
     */
    public Class[]  checkIO(Class[] input) throws IllegalInputException {    // adapted from super class ValidationChain
	// ----- old + new ----
	Operator  learner   = getLearner();
	Operator  evaluator = getEvaluator();

	// ----- old -----
	// input = learner.getIODescription().getOutputClasses(input);
	// if (!IODescription.containsClass(Model.class, input))
	//     throw new IllegalInputException(getName() + ": " + learner.getName() + " doesn't provide model");
	//
	// input = evaluator.getIODescription().getOutputClasses(input);       // TMP / TO DO: consider input of _this_ operator
	// if (!IODescription.containsClass(PerformanceVector.class, input))   // TMP / TO DO:   a la checkIO(...), s.u.
	//     throw new IllegalInputException(getName() + ": " + evaluator.getName() + " doesn't provide performance vector");

	// ----- new -----
  	//input = learner.getIODescription().getOutputClasses(input);
 	input = learner.checkIO(input);
 	if (!IODescription.containsClass(Model.class, input))
 	    throw new IllegalInputException(getName() + ": " + learner.getName() + " doesn't provide model", this);
 	//input = evaluator.getIODescription().getOutputClasses(input);
 
 	// GUT?
 	Class[] newInput = new Class[input.length+1];
 	for (int i = 0; i < input.length; i++) {
 	    newInput[i] = input[i];
 	}
 	newInput[newInput.length-1] = ExampleSet.class;
 	input = evaluator.checkIO(newInput);
 	// ???
 	if (!IODescription.containsClass(PerformanceVector.class, input))
 	    throw new IllegalInputException(getName() + ": " + evaluator.getName() + " doesn't provide performance vector", this);

	// ----- old -----
	return input;
    }
    // ----- old -----
    // ... checks above still incomplete ...
    // ... better:  check operators 0 .. getNumberOfOperators()-1 as a chain !!??   // TMP / TO DO



    /** returns the first encapsulated inner operator (or operator chain),
     *  i.e. the learning operator (chain).
     */
    protected Operator getLearner() { return getOperator(0); }    // from super class ValidationChain


    /** returns the first (? or last ?) encapsulated inner operator (or operator chain),
     *  i.e. the application and evaluation operator (chain)
     *  (or the performance estimating learning chain).
     */
    protected Operator getEvaluator() {                           // adapted from super class ValidationChain
	Operator  evaluator;

	evaluator = getOperator(0);
	    return evaluator;
    }	



    /** returns the second encapsulated inner operator (or operator chain),
     *  i.e. the model application and performance evaluation operator (chain).
     */
    // protected Operator  getModelApplierAndPerformanceEvaluator() { return getOperator(1); }
    //// ... evtl.:  if(getNumberOfOperators() < 2)  return null;   // or: exception ...


    /* As long as no JavaDoc comment is specified here, JavaDoc copies the comment 
     * from the corresponding method of the super class. 
     */
    public void initApply() throws OperatorException {
	super.initApply();

	// ----- old -----
	// modelFile = getParameter("model_file");   // in super class Learner
	// minimumWindowSize = getParameterAsInt ("minimum_window_size", 1, Integer.MAX_VALUE, 1);
	// //// legal range 1 .. MAX_INT, default 1
	// maximumWindowSize = getParameterAsInt ("maximum_window_size", 1, Integer.MAX_VALUE, Integer.MAX_VALUE);
	// //// legal range 1 .. MAX_INT, default MAX_INT
	//
	// ----- new -----
 	modelFile = getParameterAsString("model_file");   // in super class 'Learner'
 	minimumWindowSize = getParameterAsInt ("minimum_window_size");
 	maximumWindowSize = getParameterAsInt ("maximum_window_size");
	// ----- end -----

	LogService.logMessage ("BatchWindowLearner '" + getName() 
			       + "': Minimum window size = " + minimumWindowSize,
			       LogService.TASK);
	LogService.logMessage ("BatchWindowLearner '" + getName() 
			       + "': Maximum window size = " + maximumWindowSize,
			       LogService.TASK);
	if (maximumWindowSize < minimumWindowSize) {
	    throw new FatalException("BatchWindowLearner '" + getName() + 
				     "': The value of 'maximum_window_size' " +
				     "may not be smaller than the value of " +
				     "'minimum_window_size'.");
	}
	if (!(((Learner) getLearner()).canEstimatePerformance())) {
	    throw new FatalException("BatchWindowLearner '" + getName() + 
				     "': The enclosed learner must be able " +
				     "to estimate its performance based on " +