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

#ifndef _theplu_yat_regression_onedimensional_
#define _theplu_yat_regression_onedimensional_

// $Id: OneDimensional.h 728 2007-01-04 16:07:16Z 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.   
  ///
  /// @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$ \frac
       {\sum{(\hat{y_i}-y_i)^2}}{1} \f$
    */
    virtual double chisq(void) const=0;
    
    /**
       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 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 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
       given \f$ x \f$ and the squared standard error (see
       standard_error2()) of the model estimation in \f$ x \f$,
       respectively.
       
       @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 u_int n) const;

    /**
       r-squared is defined as \f$ \frac{Var(Y|x)}{Var(Y)} \f$ or the
       fraction of the variance explained by the regression model.
    */
    double r_squared(void) const;

    /**
       @return variance of residuals
    */
    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_;

  };

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

#endif