/*
* RapidMiner
*
* Copyright (C) 2001-2008 by Rapid-I and the contributors
*
* Complete list of developers available at our web site:
*
* http://rapid-i.com
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see http://www.gnu.org/licenses/.
*/
package com.rapidminer.operator.performance;
import com.rapidminer.tools.math.Averagable;
/**
* <p>Each <tt>PerformanceCriterion</tt> contains a method to compute this
* criterion on a given set of examples, each which has to have a real and a
* predicted label.</p>
*
* <p>PerformanceCriteria must implement the <tt>compareTo</tt> method in a way
* that allows <tt>Collections</tt> to sort the criteria in ascending order
* and determine the best as the maximum.</p>
*
* @author Ingo Mierswa
* @version $Id: PerformanceCriterion.java,v 2.22 2006/03/27 13:22:02
* ingomierswa Exp $
*/
public abstract class PerformanceCriterion extends Averagable implements Comparable<PerformanceCriterion> {
/**
*
*/
private static final long serialVersionUID = -6805251141256540352L;
public PerformanceCriterion() {}
/** Clone constructor. */
public PerformanceCriterion(PerformanceCriterion o) {
super(o);
}
/** Returns a description of the performance criterion. This description is
* used for GUI purposes and automatic parameter type creation for the
* {@link PerformanceEvaluator} operator. */
public abstract String getDescription();
/**
* Returns the number of data points which was used to determine the
* criterion value. If the criterion does not use example weights (or no
* weight was given) then the returned value will be an integer. Otherwise,
* the returned value is the sum of all example weights.
*/
public abstract double getExampleCount();
/**
* <p>Returns the fitness depending on the value. The fitness values will be
* used for all optimization purposes (feature space transformations, parameter
* optimizations...) and must always be maximized. Hence, if your criterion
* is better the smaller the value is you should return something like
* (-1 * value) or (1 / value).</p>
*
* <p>Subclasses should use
* {@link #getAverage()} instead of {@link #getMikroAverage()} in this method
* since usually the makro average (if available) should be optmized instead
* of the mikro average. The mikro average should only be used in the (rare)
* cases where no makro average is available but this is automatically done
* returned by {@link #getAverage()} in these cases.</p>
*/
public abstract double getFitness();
/**
* Returns the maximum fitness. The default implementation resturns
* POSITIVE_INFINITY, subclasses may override this to allow feature
* operators to end the optimization if the maximum was reached.
*/
public double getMaxFitness() {
return Double.POSITIVE_INFINITY;
}
/**
* The semantics of this method follow the specification in the interface
* <tt>java.lang.Comparable</tt> in the following way: Two objects of this
* class are equal if their <b>getFitness()</b> values are equal. The
* return value is 0 in this case. If the specified object is not an object
* of this class, a ClassCastException is thrown. If the given object has
* fitness bigger than this object, the return value is -1. If the given
* object has fitness smaller than this object, 1 is returned. No
* characteristics beside the fitness are used to compare two objects of
* this class.
*
* @param o
* Object of this class to compare this object to.
* @return -1, 0 or 1 if the given object is greater than, equal to, or less
* than this object.
*/
public int compareTo(PerformanceCriterion o) {
if (!this.getClass().equals(o.getClass()))
throw new RuntimeException("Mismatched criterion class:" + this.getClass() + ", " + o.getClass());
if (!o.getName().equals(this.getName()))
throw new RuntimeException("Mismatched criterion type:" + this.getName() + ", " + o.getName());
return Double.compare(this.getFitness(), o.getFitness());
}
}