source: trunk/yat/regression/OneDimensionalWeighted.h @ 702

#ifndef _theplu_yat_regression_onedimensioanlweighted_
#define _theplu_yat_regression_onedimensioanlweighted_

// $Id: OneDimensionalWeighted.h 702 2006-10-26 14:04:35Z 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/AveragerPairWeighted.h"

#include <ostream>

namespace theplu {
namespace yat {
namespace utility {
  class vector;
}
namespace regression {
  
  ///
  /// Abstract Base Class for One Dimensional fitting in a weighted
  /// fashion.
  ///
  class OneDimensionalWeighted 
  {
  
  public:
    ///
    /// Default Constructor.
    ///
    inline OneDimensionalWeighted(void){}

    ///
    /// Destructor
    ///
    virtual ~OneDimensionalWeighted(void) {};
         
    /**
       This function computes the best-fit given a model (see
       specific class for details) by minimizing \f$
       \sum{w_i(\hat{y_i}-y_i)^2} \f$, where \f$ \hat{y} \f$ is the
       fitted value. The weight \f$ w_i \f$ should be proportional
       to the inverse of the variance for \f$ y_i \f$
    */
    virtual void fit(const utility::vector& x, const utility::vector& y, 
                     const utility::vector& w)=0;

    /**
       @brief Mean Squared Error

       Mean Squared Error is defined as the weighted mean of the
       squared residiuals \f$ \frac{\sum w_i(y_i-\hat{y}_i)^2}{\sum
       w_i} \f$, which is minimized when fitting the regression model.
    */
    virtual double mse(void) const=0;

    ///
    /// @return expected value in @a x according 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,w - \hat{y}(x))^2) \f$ which is equal to
       \f$ E((Y|x,w - E(Y|x))^2) + 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_error()) of the model
       estimation in \f$ x \f$, respectively.
       
       The conditional variance is inversely proportional to the
       weight \f$ w \f$ and is calculated as \f$ Var(Y|x,w) =
       \frac{1}{w}\frac{\sum w_i(y_i-\hat{y}_i)^2\sum w_i^2}
       {\left(\sum w_i\right)^2} =\frac{\sum w_i^2}{w\sum w_i}mse\f$

       @return expected prediction error for a new data point in @a x
    */
    double prediction_error(const double x, const double w=1.0) const 
    { return sqrt(mse()+pow(standard_error(x),2)); }

    /**
       r-squared is defined as \f$ \frac{\sum
       w_i(y_i-\hat{y}_i)^2}{\sum w_i(y_i-m_y)^2} \f$ or the fraction
       of the variance explained by the regression model.
    */
    inline double r_squared(void) const 
    { return mse()/variance(); }

    /**
       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::AveragerPairWeighted ap_;

  private:
    inline double variance(double w=1) const
    { return ap_.y_averager().variance(); }


  };

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

#endif