Repository /TunedIT/core.jar:org.tunedit.core.EvaluationProcedure

/*
 *  Copyright (C) 2009 by TunedIT. All rights reserved.
 *
 */
package org.tunedit.core;

import org.tunedit.core.exception.AlgorithmErrorException;
import org.tunedit.core.exception.EvaluationSetupException;
import org.tunedit.core.exception.TunedTesterException;


/**
 * Base class for all <i>evaluation procedures</i> that can be used in TunedTester
 * to evaluate a given <code>algorithm</code> in application to a given <code>dataset</code>.
 * The actual evaluation is implemented by overriding method {@link #run}.
 * 
 * @see #run
 * @author Marcin Wojnarski
 *
 */
public abstract class EvaluationProcedure {

	/** 
	 * <p>Evaluates a given algorithm in application to a given dataset
	 * and returns numeric result interpreted as a quality measure of the algorithm.
	 * Both the algorithm and dataset are located in TunedIT Repository
	 * and must be loaded with provided {@link #ResourceLoader}.
	 * Typically, evaluation procedure does not use ResourceLoader directly,
	 * but instead creates a {@link #StandardLoader},
	 * which offers more convenient access to resources 
	 * (StandardLoader is a wrapper for ResourceLoader).
	 * </p>
	 * 
	 * @return 
	 * Numeric value of quality measure of the algorithm.
	 * Currently only the first element of the returned array is used,
	 * so the procedure should return a one-element array of Doubles.
	 * Returned value must be a proper number. 
	 * Exception should be thrown in the case of any error that 
	 * makes calculation of numeric result impossible (see below for details).
	 * If NaN, Inf or <code>null</code> value is returned,
	 * it will be treated as an error of the evaluated algorithm.
	 * 
	 * @throws TunedTesterException
	 * if the testing environment (TunedTester) failed to provide access to resources.
	 * This exception is usually raised by ResourceLoader or StandardLoader
	 * and propagated upwords by evaluation procedure.
	 * 
	 * @throws EvaluationSetupException
	 * if evaluation procedure is not applicable to a given combination of algorithm and dataset.
	 * 
	 * @throws AlgorithmErrorException
	 * if the tested algorithm worked incorrectly and performed an illegal operation,
	 * e.g. raised an exception.
	 * AlgorithmErrorException is interpreted by TunedTester as a 
	 * failure of the algorithm, which is a special type of result
	 * and is logged in Knowledge Base (!), if only the user chose 
	 * to submit results of tests to TunedIT.
	 * Other exceptions are interpreted as failures of testing environment
	 * or inapplicability of evaluation procedure to a given test specification,
	 * hence they are only presented to the user and not sent to Knowledge Base.
	 * 
	 */
	@Deprecated
	public abstract Double[] run(ResourceName algorithm, ResourceName dataset, ResourceLoader loader) 
		throws TunedTesterException, EvaluationSetupException, AlgorithmErrorException;

	public Double[] run(ResourceName algorithm, ResourceName dataset, ResourceLoader loader, long seed) 
		throws TunedTesterException, EvaluationSetupException, AlgorithmErrorException{
		return run(algorithm, dataset, loader);
	}

}