batchweightlearner.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.operator.parameter.*;
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.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.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>BatchWeightLearner</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 
 *                             another experiment using a {@link edu.udo.cs.yale.operator.ModelLoader}</li>
 *    <li><b>[weighting_scheme]</b>: This parameter may have one of the following values:
 *        <ul>
 *          <li><code>global</code>: In the global weighting scheme, the examples are globally weighted
 *              according to their age, i.e. the older an example is the smaller is its weight.
 *              The weighting function is an exponential decay function.</li>
 *          <li><code>local</code>: ...</li>
 *          <li><code>combined</code>:...
 *              ... <code>combined</code> = global * local ...</li>
 *        </ul>
 *        The default value is <code>global</code>.
 *        </li>
 *    <li><b>[minimal_weight]</b>: ... minimal_weight (0.0 ... 1.0) ... default = 0.0001 .. treshold, under 
 *                                 which example weights are considered equal to zero ... 
 *                                 (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 {@link BatchedExampleSet}
 *                                   instead of just {@link ExampleSet}. ... </li>
 *  </ol>
 *  <h4>Operator-Output</h4>
 *  <ol>
 *    <li>{@link Model}: ...</li>
 *  </ol>
 *  <h4>Enclosed Operators</h4>
 *  <ol>
 *    <li>First operator: classifier learner that is able to estimate its performance
 *        (e.g. a {@link SVMLightLearner} or a {@link MySVMLearner})</li>
 *    <li>Second operator (optional for <code>global</code> weighting scheme, 
 *        mandatory for <code>local</code> or <code>combined</code>
 *        weighting scheme): operator chain containing a model applier that is
 *        able to apply the model learnt by the above
 *        learner to an example set and a performance evaluator</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.BatchWindowLearner
 *  @see edu.udo.cs.yale.operator.time.ConceptDriftSimulator
 *  @see edu.udo.cs.yale.operator.time.ConceptDriftAdaptor
 *
 *  @yale.xmlclass BatchWeightLearner
 *  @yale.cite Klinkenberg/Rueping/2002a
 *
 *  @author Ralf Klinkenberg
 *  @version $Id: BatchWeightLearner.java,v 2.10 2003/09/04 14:56:50 klinkenb Exp $
 */
public class  BatchWeightLearner extends OperatorChain {
    // History:
    //   RK/2002/04/25:  first operator version with exponential global example weighting;
    //   RK/2002/05/25:  sigmoidal global example weighting added;
    //   RK/2002/06/10:  local example weighting added;
    //   RK/2002/09/21:  (local) zero-one-weighting added;
    //   RK/2002/09/25:  bug fix: replaced weighting scheme parameter key word 'combined_global_and_local' by 'combined',
    //                   because 'combined' was specified in the JavaDoc docomentation and used in all experiment config
    //                   files but not recognized up to now (but automatically replaced by the default value 'global');
    //   RK/2003/03/14:  merger of Yale 1.0 and Yale 2.0 file versions, i.e. RK's file version
    //                   merged with SF+IM's adaptations for the Yale GUI (different handling of fatal errors and operator parameters);
    //                   bug fix in 'getMinNumberOfInnerOperators()' and 'getMaxNumberOfInnerOperators()';
    //   RK/2003/03/24:  merger of Yale 1.0 and Yale 2.0 file versions completed;

    // public class  BatchWeightLearner 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

    private String                   modelFile;                                     // in super class Learner
    // private SVMApplier            modelApplier;                                  // RK/2002/05/25: temporary hack
    // private PerformanceEvaluator  batchEvaluator;                                // RK/2002/05/25: temporary hack
    private Operator                 modelApplierAndPerformanceEvaluator;           // RK/2002/06/09: replacement for temporary hack

    // weighting functions offerd by this operator
    public final static int  EXPONENTIAL_FUNCTION = 0;    // RK/2002/05/21: start w/ 0 or 1 ? see ConceptDriftSimulator !?
    public final static int  SIGMOIDAL_FUNCTION   = 1;
    public final static int  ZERO_ONE_FUNCTION    = 2;

    // weighting schemes offered by this operator for the batch-oriented example weighting
    public final static int  GLOBAL_EXAMPLE_WEIGHTING                     = 0;    // RK/2002/05/21: start w/ 0 or 1 ? see ConceptDriftSimulator !?
    public final static int  LOCAL_EXAMPLE_WEIGHTING                      = 1;
    public final static int  COMBINED_GLOBAL_AND_LOCAL_EXAMPLE_WEIGHTING  = 2;
    public final static int  ZERO_ONE_WEIGHTING                           = 3;
    /** names of the available weighting functions */
    private static final String[]  WEIGHTING_FUNCTION_TYPE_NAME = {"exponential","sigmoid","zero_one"};
    /** names of the weighting scheme types as they may be specified in the Yale configuration file. */
    // private static final String[]  WEIGHTING_SCHEME_TYPE_NAME   = {"global","local","combined_global_and_local","zero_one"};
    private static final String[]  WEIGHTING_SCHEME_TYPE_NAME   = {"global","local","combined","zero_one"};

    private int       weightingFunction; // function used for weighting (exponential vs. sigmoidal function)
    private int       weightingScheme;   // example weighting scheme: global vs. local vs. combined [:= gobal * local] vs. zero-one
    private double[]  lambda;            // parameter for exponential global weighting scheme (= exponential weight decay factor)
    private double[]  a, b;              // parameters for sigmoidal global weighting scheme
    private double    minimalWeight;     // treshold, under which example weights are considered equal to zero

    /** xi-alpha performance estimation of the enclosed mySVM (classification error, recall, and precision). */
    private PerformanceVector  performanceEstimation;

    /** xi-alpha performance estimation of the last /best mySVM (classification error) */   // from super class ValidationChain
    // private PerformanceCriterion  lastPerformance;
    // private IOContainer           learnResult;                                           // from super class ValidationChain


    /** 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 + new ---
	return input;
    }
    // ... 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).
     */
    private Operator getLearner() { return getOperator(0); }    // from super classe 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).
     */
    private Operator getEvaluator() {                           // adapted from super class ValidationChain
	// Class[]   input;      // operator input and output classes
	// Operator  learner;
	Operator  evaluator;

	// learner   = getLearner();
	evaluator = getOperator(0);
	// input = (learner.getIODescription()).getOutputClasses();           // TMP / TO DO: consider input of _this_ operator
	// if (IODescription.containsClass(PerformanceVector.class, input))   // TMP / TO DO:   a la checkIO(...), s.o.
	    return evaluator;

	// evaluator = getOperator(getNumberOfOperators()-1);                 // TMP
	// input = evaluator.getIODescription().getOutputClasses(input);
	// if (IODescription.containsClass(PerformanceVector.class, input))
	//     return evaluator;

	// return null;
    }	
    // ... better:  check operators 0 .. getNumberOfOperators()-1 as a chain !!   // TMP / TO DO

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


    public void initApply() throws OperatorException {
	super.initApply();
	//
	// ----- old -----
  	// modelFile = getParameter("model_file");                                      // in super class Learner
  	// minimalWeight = getParameterAsDouble ("minimal_weight", 0.0, 1.0, 0.0001);   // legal range 0.0 .. 1.0, default 0.0001
  	// weightingFunction = getParameterCategory ("weighting_function", WEIGHTING_FUNCTION_TYPE_NAME, EXPONENTIAL_FUNCTION);
  	// weightingScheme   = getParameterCategory ("weighting_scheme", WEIGHTING_SCHEME_TYPE_NAME, GLOBAL_EXAMPLE_WEIGHTING);
	// ----- new -----
	modelFile = getParameterAsString("model_file");                                      // in super class Learner
	minimalWeight = getParameterAsDouble ("minimal_weight");   // legal range 0.0 .. 1.0, default 0.0001
	weightingFunction = getParameterAsInt ("weighting_function");
	weightingScheme   = getParameterAsInt ("weighting_scheme");
	// ----- end of new -----
	//
	// LogFileService...  // ... log file message w/ recognized weighting scheme ... 
	//
	// lambda = new double[] {1.0, 4.0};                                      // TMP // later: read from config file
	// lambda = new double[] {0.1, 0.2, 0.6, 1.0, 2.0};                       // TMP // later: read from config file