source: trunk/yat/statistics/Averager.h @ 2161

#ifndef _theplu_yat_statistics_averager_
#define _theplu_yat_statistics_averager_

// $Id: Averager.h 2161 2010-01-19 23:59:48Z peter $

/*
  Copyright (C) 2004 Jari Häkkinen, Peter Johansson
  Copyright (C) 2005, 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
  Copyright (C) 2007, 2008 Jari Häkkinen, Peter Johansson
  Copyright (C) 2009, 2010 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 3 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 yat. If not, see <http://www.gnu.org/licenses/>.
*/

#include "yat/utility/iterator_traits.h"

#include <boost/concept_check.hpp>

#include <cmath>

namespace theplu{
namespace yat{
namespace statistics{

  class ostream;

  ///
  /// @brief Class to calculate simple (first and second moments) averages.
  ///
  /// @see AveragerWeighted AveragerPair AveragerPairWeighted
  ///
  class Averager
  {
  public:

    ///
    /// Default constructor
    ///
    Averager(void);
    
    ///
    /// Constructor taking sum of \a x, sum of squared x, \a xx, and
    /// number of samples \a n.
    ///
    Averager(double x, double xx, long n);

    ///
    /// Copy constructor
    ///
    Averager(const Averager& a);

    ///
    /// Adding \a n (default=1) number of data point(s) with value \a d.
    ///
    void add(double d, long n=1);

    /**
       @brief Coeffient of variation

       Coeffient of variation (cv) is defined as ratio between the
       standard deviation and the mean: \f$ \frac{\sigma}{\mu} \f$.
       
       @return standard deviation divided by mean.
    */
    double cv(void) const;

    ///
    /// @return %Mean of presented data, \f$ \frac{1}{n}\sum x_i \f$
    ///
    double mean(void) const;

    ///
    /// @return Number of data points
    ///
    long n(void) const;

    ///
    /// @brief Rescales the object
    ///
    /// \f$ \forall x_i \rightarrow a*x_i \f$,
    ///
    void rescale(double a);

    ///
    /// @return Standard error, i.e. standard deviation of the mean
    /// \f$ \sqrt{variance()/n} \f$
    ///
    double standard_error(void) const;

    ///
    /// @brief The standard deviation is defined as the square root of
    /// the variance.
    ///
    /// @return The standard deviation, root of the variance().
    ///
    double std(void) const;

    ///
    /// @brief The standard deviation is defined as the square root of
    /// the variance.
    ///
    /// @return Standard deviation around \a m, root of the variance(m).
    ///
    double std(double m) const;

    ///
    /// @return The sum of x
    ///
    double sum_x(void)  const;

    ///
    /// @return The sum of squares
    ///
    double sum_xx(void) const;

    ///
    /// @return \f$ \sum_i (x_i-m)^2 \f$
    ///
    double sum_xx_centered(void)  const;

    ///
    /// @brief The variance with know mean
    ///
    /// The variance is calculated as
    /// \f$ \frac{1}{n}\sum (x_i-m)^2 \f$. 
    ///
    /// @return Variance when the mean is known to be \a m.
    ///
    double variance(double m) const;

    /**
       \brief The estimated variance
       
       The variance is calculated as \f$ \frac{1}{N}\sum_i
       (x_i-m)^2 \f$, where \f$ m \f$ is the mean.
       
       \return Estimation of variance
    */
    double variance(void) const;

    ///
    /// The variance is calculated using the \f$ (n-1) \f$ correction,
    /// which means it is the best unbiased estimator of the variance
    /// \f$ \frac{1}{N-1}\sum_i (x_i-m)^2 \f$, where \f$ m \f$ is the
    /// mean.
    ///
    /// @return unbiased estimation of variance
    ///
    double variance_unbiased(void) const;

    ///
    /// @brief Reset everything to zero
    ///
    void reset(void);

    ///
    /// @brief The assignment operator
    ///
    const Averager& operator=(const Averager&);

    ///
    /// Operator to add another Averager
    ///
    const Averager& operator+=(const Averager&);

  private:
    long  n_;
    double  x_, xx_;
  };
  

  /**
     \brief adding a range of values to Averager \a a

     \relates Averager
   */
  template <typename InputIterator>
  void add(Averager& a, InputIterator first, InputIterator last)
  {
    BOOST_CONCEPT_ASSERT((boost::InputIterator<InputIterator>));
    utility::check_iterator_is_unweighted(first);
    for ( ; first != last; ++first)
      a.add(*first);
  }

}}} // of namespace statistics, yat, and theplu

#endif