content: /*
   * Copyright (c) 2010 Pentaho Corporation.  All rights reserved. 
   * This software was developed by Pentaho Corporation and is provided under the terms 
   * of the GNU Lesser General Public License, Version 2.1. You may not use 
   * this file except in compliance with the license. If you need a copy of the license, 
   * please go to http://www.gnu.org/licenses/lgpl-2.1.txt. The Original Code is Time Series 
   * Forecasting.  The Initial Developer is Pentaho Corporation.
   *
   * Software distributed under the GNU Lesser Public License is distributed on an "AS IS" 
   * basis, WITHOUT WARRANTY OF ANY KIND, either express or  implied. Please refer to 
   * the license for the specific language governing your rights and limitations.
   */
  
  /*
   *    OverlayForecaster.java
   *    Copyright (C) 2011 Pentaho Corporation
   */
  
  package weka.classifiers.timeseries.core;
  
  import java.io.PrintStream;
  import java.util.List;
  
  import weka.classifiers.evaluation.NumericPrediction;
  import weka.core.Instances;
  
  /**
   * Interface to a forecaster that has been trained with data containing 
   * "overlay" attributes. These are attributes whose values will be supplied
   * externally for future time periods to be forecasted. 
   * 
   * @author Mark Hall (mhall{[at]}pentaho{[dot]}com)
   * @version $Revision: 49983 $
   */
  public interface OverlayForecaster {
    
    /**
     * Produce a forecast for the target field(s). Assumes that the model has been built
     * and/or primed so that a forecast can be generated. Also assumes that
     * the forecaster has been told which attributes are to be considered
     * "overlay" attributes in the data. Overlay data is data that the
     * forecaster will be provided with when making a forecast into the future - i.e.
     * it will be given the values of these attributes for future instances. The
     * overlay data provided to this method should have the same structure as
     * the original data used to train the forecaster - i.e. all original fields
     * should be present, including the targets and time stamp field (if supplied).
     * The values of targets will of course be missing ('?') since we want to forecast
     * those. The time stamp values (if a time stamp is in use) may be provided, in which
     * case the forecaster will use the time stamp values in the overlay instances. If
     * the time stamp values are missing, then date arithmetic (for date time stamps) will
     * be used to advance the time value beyond the last seen training value;
     * similarly, for artificial time stamps or non-date time stamps, the computed
     * time delta will be used to increment beyond the last seen training value.
     * 
     * The number of instances in the overlay data should typically match the number
     * of steps that have been requested for forecasting. If these differ, then
     * overlay.numInstances() will be the number of steps forecasted.
     * 
     * @param numSteps number of forecasted values to produce for each target. E.g.
     * a value of 5 would produce a prediction for t+1, t+2, ..., t+5.
     * @param overlay instances in the same format as the training data containing
     * values for overlay attributes for the time steps to be forecasted
     * @param progress an optional varargs parameter supplying progress objects
     * to report/log to
     * @return a List of Lists (one for each step) of forecasted values for each target
     * @throws Exception if the forecast can't be produced for some reason.
     */
    List<List<NumericPrediction>> forecast(int numSteps, Instances overlay,
        PrintStream... progress) throws Exception;
    
    /**
     * Returns true if this forecaster has been trained with data containing
     * overlay fields, and thus will expect to be provided with future values
     * for these fields when making a forecast.
     * 
     * @return true if this forecaster expects to be provided with overlay data
     * when making a forecast.
     */
    boolean isUsingOverlayData();
    
    /**
     * Set the fields to consider as overlay fields
     * 
     * @param overlayFields a comma-separated list of field names
     * @throws Exception if there is a problem setting the overlay fields
     */
    void setOverlayFields(String overlayFields) throws Exception;
    
    /**
     * Get a comma-separated list of fields that considered to be overlay
     * fields
     * 
     * @return a list of field names
     */
    String getOverlayFields();
  }
  