learner.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.OperatorException;
import edu.udo.cs.yale.operator.UserError;
import edu.udo.cs.yale.operator.parameter.*;
import edu.udo.cs.yale.operator.learner.Model;
import edu.udo.cs.yale.operator.Operator;
import edu.udo.cs.yale.operator.IOObject;
import edu.udo.cs.yale.operator.performance.PerformanceCriterion;
import edu.udo.cs.yale.operator.performance.PerformanceVector;
import edu.udo.cs.yale.example.ExampleSet;
import edu.udo.cs.yale.example.Example;
import edu.udo.cs.yale.example.Attribute;
import edu.udo.cs.yale.tools.LogService;
import edu.udo.cs.yale.tools.Ontology;

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

/**
 *  A <tt>Learner</tt> is an operator that encapsulates the learning step of a machine learning 
 *  method. Some Learners may be capable of estimating the performance of the generated model.
 *  In that case, they additionally return a 
 *  {@link edu.udo.cs.yale.operator.performance.PerformanceVector}.
 *
 *  <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>
 *  </ul>
 *
 *  <h4>Operator-Input</h4>
 *  <ol>
 *    <li><tt>ExampleSet</tt></li> the training set
 *  </ol>
 *  <h4>Operator-Output</h4>
 *  <ol>
 *    <li><tt>Model</tt></li>
 *  </ol>
 *
 *  @see edu.udo.cs.yale.operator.ModelLoader
 *  @author Ingo
 *  @version $Id: Learner.java,v 2.5 2003/08/28 14:31:06 fischer Exp $
 */
public abstract class Learner extends Operator {

    public static final String[] TASK_TYPES = { "auto", "regression", "pattern" };
    public static final int  AUTO       = 0;
    public static final int  REGRESSION = 1;
    public static final int  PATTERN    = 2;

    private static final Class[] INPUT_CLASSES = { ExampleSet.class };

    private String modelFile;

    public void initApply() throws OperatorException {
	super.initApply();
	modelFile = getParameterAsString("model_file");
    }

    /** Trains a model. This method is called by apply() and is implemented by subclasses.
     */
    public abstract Model learn(ExampleSet exampleSet) throws OperatorException;

    /** Returns true iff the learner can generate a performance vector during training. */
    public boolean canEstimatePerformance() { return false; }
    
    public PerformanceVector getEstimatedPerformance() { return null; }


    /** Trains a model useing an ExampleSet from the input. The model is saved in <tt>model_file</tt>
     *  if given.
     */
    public IOObject[] apply() throws OperatorException {
	ExampleSet exampleSet = (ExampleSet)getInput(ExampleSet.class);

	Attribute  labelAttribute = exampleSet.getLabel();
	if (labelAttribute == null) {
	    throw new UserError(this, 105, new Object[0]); 
	}

	if (exampleSet.getNumberOfAttributes()==0) {
	    throw new UserError(this, 106, new Object[0]);
	}

	Model model = learn(exampleSet);

	try {
	    if (modelFile != null) model.writeModel(getExperiment().resolveFileName(modelFile));
	} catch (IOException e) {
	    throw new UserError(this, e, 303, new Object[] {modelFile, e.getMessage() });
	}

	PerformanceVector perfVector = getEstimatedPerformance();
	if (perfVector == null) {
	    return new IOObject[] { model };
	} else {
	    return new IOObject[] { model, perfVector };
	}
    }

    
    public Class[] getInputClasses() { return INPUT_CLASSES; }

    public Class[] getOutputClasses() { 
	return canEstimatePerformance() ? 
	    new Class[] { Model.class, PerformanceVector.class } : 
	    new Class[] { Model.class };
    }

    /** Returns <tt>true</tt>, if the learning task at hand is a classification task, and <tt>false</tt>
     *  otherwise.  A learning task is a classification task (and no regression task), if
     *  <code>userOptionTaskType</code> is not <code>AUTO</code>, it determines the task type.
     *  If it does not match the type of the label, a warning is issues. Otherwise the task type
     *  is classification iff the label attribute is nominal. */
    protected boolean taskIsClassification(int userOptionTaskType, 
					   ExampleSet exampleSet) throws OperatorException {
	Attribute  labelAttribute = exampleSet.getLabel();
	boolean  labelIsNominal = Ontology.ATTRIBUTE_VALUE_TYPE.isA(labelAttribute.getValueType(), Ontology.NOMINAL);
	
	switch (userOptionTaskType) {
	case REGRESSION:
	    if (labelIsNominal)
		LogService.logMessage(getName() + ": Applying regression to nominal data.", LogService.WARNING);
	    return false;
		
	case PATTERN:
	    if (!labelIsNominal) {
		LogService.logMessage(getName() + ": Applying classification to numerical data.", LogService.WARNING);
	    }
	    if (labelAttribute.getNumberOfClasses() != 2) {
		LogService.logMessage(getName() + ": Class attribute should have exactly two values, but has " + 
				      labelAttribute.getNumberOfClasses() +
				      " class values. (Ignore warning in MultiClassLearner!)", LogService.WARNING);
	    }
	    return true;
	case AUTO:
	default:
	    if (labelIsNominal) { 
		if (labelAttribute.getNumberOfClasses() != 2) {
		    LogService.logMessage(getName() + ": Class attribute should have exactly two values, but has " + 
					  labelAttribute.getNumberOfClasses() +
					  " class values. (Ignore warning in MultiClassLearner!)", LogService.WARNING);
		}
		return true;
	    } else {
		return false;
	    }
	}
    }

    public List getParameterTypes() {
	List types = super.getParameterTypes();
	types.add(new ParameterTypeFile("model_file", "If this parameter is set, the model is written to a file.", true));
	return types;
    }

}