source: branches/0.4-stable/yat/regression/OneDimensional.h @ 1392

#ifndef _theplu_yat_regression_onedimensional_
#define _theplu_yat_regression_onedimensional_

// $Id: OneDimensional.h 1392 2008-07-28 19:35:30Z peter $

/*
  Copyright (C) 2004 Peter Johansson
  Copyright (C) 2005, 2006, 2007 Jari Häkkinen, Peter Johansson
  Copyright (C) 2008 Peter Johansson

  This file is part of the yat library, http://dev.thep.lu.se/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 VectorBase;
}
namespace regression {

  ///
  /// @brief Interface Class for One Dimensional fitting.   
  ///
  /// @see OneDimensionalWeighted.
  ///
  class OneDimensional 
  {

  public:
    ///
    /// @brief The default constructor
    ///
    OneDimensional(void);

    ///
    /// @brief The destructor
    ///
    virtual ~OneDimensional(void);
 
    /**
       @brief Chi-squared
       
       Chi-squared is defined as the \f$ 
       \sum{(\hat{y_i}-y_i)^2} \f$
    */
    double chisq(void) const;
    
    /**
       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::VectorBase& x, 
                     const utility::VectorBase& 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 expected squared
       deviation a new data point will have from value the model
       provides: \f$ E(Y|x - \hat{y}(x))^2 \f$ and is typically
       divided into the conditional variance ( see s2() )
       given \f$ x \f$ and the squared standard error ( see
       standard_error2() ) of the model estimation in \f$ x \f$.
       
       @return expected squared prediction error for a new data point
       in @a x
    */
    double prediction_error2(const double x) const; 

    ///
    /// @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 os Ostream printout is sent to
    /// @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 unsigned int n) const;

    /**
       r2 is defined as \f$ 1 - \frac{Var(Y|x)}{Var(Y)} \f$ or the
       fraction of the variance explained by the regression model.

       @see s2()
    */
    double r2(void) const;

    /**
       \f$ E(Y|x - E(Y|x))^2 \f$ 

       @return Conditional variance of Y
    */
    virtual double s2(void) const=0;

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

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

  protected:
    ///
    /// Variance of y
    ///
    double variance(void) const;

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

    ///
    /// @see chisq()
    ///
    double chisq_;
  };

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

#endif