source: trunk/yat/normalizer/Zscore.h @ 4049

#ifndef _theplu_yat_normalizer_z_score_
#define _theplu_yat_normalizer_z_score_

// $Id: Zscore.h 4049 2021-03-03 12:58:19Z peter $

/*
  Copyright (C) 2008 Jari Häkkinen, Peter Johansson
  Copyright (C) 2009, 2010, 2016 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 "utility.h"

#include "yat/statistics/Averager.h"
#include "yat/statistics/AveragerWeighted.h"

#include "yat/utility/concept_check.h"
#include "yat/utility/iterator_traits.h"

#include <boost/concept_check.hpp>

namespace theplu {
namespace yat {
namespace normalizer {

  /**
     \brief Zero mean and unity variance

     Shift and scale the values in a range as: \f$ y_i =
     \frac{x_i-m}{k*s} \f$ where \a m is the mean, \a s is the
     standard deviation, and \a k is set in constructor (default:
     1.0). After normalization, the range will have zero mean and
     variance = \f$ 1/k^2 \f$.

       Type Requirements:
       - \c InputIterator is \ref concept_data_iterator
       - \c InputIterator is \forward_traversal_iterator
       - \c OutputIterator is \writable_iterator
       - \c OutputIterator is \forward_traversal_iterator

     \since New in yat 0.5
   */
  class Zscore
  {
  public:
    /**
       \param k In the scaling step elements are divided by \c k times
       the standard deviation

       \since New in yat 0.19
     */
    explicit Zscore(double k=1.0);

    /**
       \return the k-factor set in constructor

       \since new in yat 0.19
     */
    double k(void) const;

    /**
       The element in range [result, result + (last-first)) is
       calculated as result[i] = (first[i] - m) / s where m and std
       are the mean and standard deviation, respectively, of the range
       [first, last).

       It is possible to centralize a range "in place"; it is
       permissible for the iterators \a first and \a result to be the
       same. \see std::transform
     */
    template<class InputIterator, class OutputIterator>
    void operator()(InputIterator first, InputIterator last,
                    OutputIterator result) const
    {
      BOOST_CONCEPT_ASSERT((utility::DataIteratorConcept<InputIterator>));
      BOOST_CONCEPT_ASSERT((utility::DataIteratorConcept<OutputIterator>));

      // needed for weighted_if_any2
      typename utility::weighted_if_any2<InputIterator, OutputIterator>::type tag;
      normalize(first, last, result, tag);
    }

  private:
    double k_;


    template<class ForwardIterator, class OutputIterator>
    void normalize(ForwardIterator first, ForwardIterator last,
                   OutputIterator result,
                   utility::unweighted_iterator_tag tag) const
    {
      // we need to traverse the input range once in calculating m
      // (and std) and a second time when assigning new values, so
      // single pass iterator will not suffice.
      BOOST_CONCEPT_ASSERT((boost_concepts::ForwardTraversal<ForwardIterator>));

      BOOST_CONCEPT_ASSERT((boost_concepts::WritableIterator<OutputIterator>));

      statistics::Averager a;
      add(a, first, last);
      double m = a.mean();
      double factor = 1.0 / (a.std() * k_);
      while (first!=last) {
        *result = (*first - m) * factor;
        ++first;
        ++result;
      }
    }

    template<class ForwardIterator, class OutputIterator>
    void normalize(ForwardIterator first, ForwardIterator last,
                   OutputIterator result,
                   utility::weighted_iterator_tag tag) const
    {
      // we need to traverse the input range once in calculating m
      // (and std) and a second time when assigning new values, so
      // single pass iterator will not suffice.
      BOOST_CONCEPT_ASSERT((boost_concepts::ForwardTraversal<ForwardIterator>));

      BOOST_CONCEPT_ASSERT((boost_concepts::WritableIterator<OutputIterator>));
      // we traverse output range twice
      BOOST_CONCEPT_ASSERT((boost_concepts::ForwardTraversal<OutputIterator>));
      detail::copy_weight_if_weighted(first, last, result);
      statistics::AveragerWeighted a;
      add(a, first, last);
      double m = a.mean();
      double factor = 1.0 / (a.std() * k_);
      utility::iterator_traits<ForwardIterator> in_trait;
      utility::iterator_traits<OutputIterator> out_trait;
      while (first!=last) {
        out_trait.data(result) = (in_trait.data(first) - m) * factor;
        ++first;
        ++result;
      }
    }
  };

}}} // end of namespace normalizer, yat and thep
#endif