content: /*
   *    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., 675 Mass Ave, Cambridge, MA 02139, USA.
   */
  
  /*
   *    ResultProducer.java
   *    Copyright (C) 1999 University of Waikato, Hamilton, New Zealand
   *
   */
  
  
  package weka.experiment;
  
  import weka.core.Instances;
  import java.io.Serializable;
  
  /**
   * This interface defines the methods required for an object 
   * that produces results for different randomizations of a dataset. <p>
   *
   * Possible implementations of ResultProducer: <br>
   * <ul>
   *   <li>Random test/train splits
   *   <li>CrossValidation splits
   *   <li>LearningCurve splits (multiple results per run?)
   *   <li>Averaging results of other result producers
  * </ul>
   *
   * @author Len Trigg (trigg@cs.waikato.ac.nz)
   * @version $Revision: 1.7 $
   */
  
  public interface ResultProducer extends Serializable {
    
    /**
     * Sets the dataset that results will be obtained for.
     *
     * @param instances a value of type 'Instances'.
     */
    void setInstances(Instances instances);
  
    /**
     * Sets the object to send results of each run to.
     *
     * @param listener a value of type 'ResultListener'
     */
    void setResultListener(ResultListener listener);
  
    /**
     * Sets a list of method names for additional measures to look for
     * in SplitEvaluators.
     * @param additionalMeasures a list of method names
     */
    void setAdditionalMeasures(String [] additionalMeasures);
  
    /**
     * Prepare to generate results. The ResultProducer should call
     * preProcess(this) on the ResultListener it is to send results to.
     *
     * @exception Exception if an error occurs during preprocessing.
     */
    void preProcess() throws Exception;
    
    /**
     * Perform any postprocessing. When this method is called, it indicates
     * that no more requests to generate results for the current experiment
     * will be sent. The ResultProducer should call
     * preProcess(this) on the ResultListener it is to send results to.
     *
     * @exception Exception if an error occurs
     */
    void postProcess() throws Exception;
    
    /**
     * Gets the results for a specified run number. Different run
     * numbers correspond to different randomizations of the data. Results
     * produced should be sent to the current ResultListener, but only
     * if the ResultListener says the result is required (it may already
     * have that result). A single run may produce multiple results.
     *
     * @param run the run number to generate results for.
     * @exception Exception if a problem occurs while getting the results
     */
    void doRun(int run) throws Exception;
    
    /**
     * Gets the keys for a specified run number. Different run
     * numbers correspond to different randomizations of the data. Keys
     * produced should be sent to the current ResultListener
     *
     * @param run the run number to get keys for.
     * @exception Exception if a problem occurs while getting the keys
     */
    void doRunKeys(int run) throws Exception;
  
    /**
     * Gets the names of each of the key columns produced for a single run.
     * The names should not contain spaces (use '_' instead for easy 
     * translation.)
     *
     * @return an array containing the name of each key column
     * @exception Exception if the key names could not be determined (perhaps
     * because of a problem from a nested sub-resultproducer)
     */
    String [] getKeyNames() throws Exception;
  
    /**
     * Gets the data types of each of the key columns produced for a single run.
     *
     * @return an array containing objects of the type of each key column. The 
     * objects should be Strings, or Doubles.
     * @exception Exception if the key types could not be determined (perhaps
     * because of a problem from a nested sub-resultproducer)
     */
    Object [] getKeyTypes() throws Exception;
  
    /**
     * Gets the names of each of the result columns produced for a single run.
     * The names should not contain spaces (use '_' instead for easy 
     * translation.)
     *
     * @return an array containing the name of each result column
     * @exception Exception if the result names could not be determined (perhaps
     * because of a problem from a nested sub-resultproducer)
     */
    String [] getResultNames() throws Exception;
  
    /**
     * Gets the data types of each of the result columns produced for a 
     * single run.
     *
     * @return an array containing objects of the type of each result column. 
     * The objects should be Strings, or Doubles.
     * @exception Exception if the result types could not be determined (perhaps
     * because of a problem from a nested sub-resultproducer)
     */
    Object [] getResultTypes() throws Exception;
  
    /**
     * Gets a description of the internal settings of the result
     * producer, sufficient for distinguishing a ResultProducer
     * instance from another with different settings (ignoring
     * those settings set through this interface). For example,
     * a cross-validation ResultProducer may have a setting for the
     * number of folds. For a given state, the results produced should
     * be compatible. Typically if a ResultProducer is an OptionHandler,
     * this string will represent those command line arguments required
     * to set the ResultProducer to that state.
     *
     * @return the description of the ResultProducer state, or null
     * if no state is defined
     */
    String getCompatibilityState();
  
  } // ResultProducer
  