source: trunk/yat/regression/OneDimensional.h @ 695

#ifndef _theplu_yat_regression_onedimensional_
#define _theplu_yat_regression_onedimensional_

// $Id: OneDimensional.h 695 2006-10-25 09:20:17Z peter $

/*
  Copyright (C) The authors contributing to this file.

  This file is part of the yat library, http://lev.thep.lu.se/trac/yat

  The yat library 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.

  The yat library 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.
*/

#include "yat/statistics/AveragerPair.h"

#include <ostream>

namespace theplu {
namespace yat {
namespace utility {
  class vector;
}
namespace regression {
  
  ///
  /// Abstract Base Class for One Dimensional fitting.   
  ///
  /// @todo document
  ///
  class OneDimensional 
  {
  
  public:
    ///
    /// Default Constructor.
    ///
    inline OneDimensional(void) {}

    ///
    /// Destructor
    ///
    virtual ~OneDimensional(void) {};
         
    /**
       This function computes the best-fit given a model (see
       specific class for details) by minimizing \f$
       \sum{(\hat{y_i}-y_i)^2} \f$, where \f$ \hat{y} \f$ is the fitted value.
    */
    virtual void fit(const utility::vector& x, const utility::vector& y)=0; 
    
    ///
    /// @return expected value in @a x accrding to the fitted model
    ///
    virtual double predict(const double x) const=0;

    /**
       The prediction error is defined as the square root of the
       expected squared deviation a new data point will have from
       value the model provides. The expected squared deviation is
       defined as \f$ E(Y|x - \hat{y}(x))^2 \f$ and is typically
       divided into two terms \f$ E(Y|x - E(Y|x))^2 \f$ and \f$
       E(E(Y|x) - \hat{y}(x))^2 \f$, which is the conditional variance
       in \f$ x \f$ and the squared standard error (see
       standard_error()) of the model estimation in \f$ x \f$,
       respectively.
    
       @return expected prediction error for a new data point in @a x
    */
    virtual double prediction_error(const double x) const=0;

    ///
    /// @brief print output to ostream @a os
    ///
    /// Printing estimated model to @a os in the points defined by @a
    /// min, @a max, and @a n. The values printed for each point is
    /// the x-value, the estimated y-value, and the estimated standard
    /// deviation of a new data poiunt will have from the y-value
    /// given the x-value (see prediction_error()).
    /// 
    /// @param n number of points printed
    /// @param min smallest x-value for which the model is printed
    /// @param max largest x-value for which the model is printed
    ///
    std::ostream& print(std::ostream& os,const double min, 
                        double max, const u_int n) const;

    /**
       The standard error is defined as \f$ \sqrt{E(Y|x -
       \hat{y}(x))^2 }\f$

       @return error of model value in @a x
    */
    virtual double standard_error(const double x) const=0;

  protected:
    ///
    /// Averager for pair of x and y
    ///
    statistics::AveragerPair ap_;

    ///
    /// mean squared deviation (model from data points)
    ///
    double msd_; 
  };

}}} // of namespaces regression, yat, and theplu

#endif