/Src/Dependencies/Boost/boost/accumulators/statistics/density.hpp

  1
  2///////////////////////////////////////////////////////////////////////////////
  3// density.hpp
  4//
  5//  Copyright 2006 Daniel Egloff, Olivier Gygi. Distributed under the Boost
  6//  Software License, Version 1.0. (See accompanying file
  7//  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  8
  9#ifndef BOOST_ACCUMULATORS_STATISTICS_DENSITY_HPP_DE_01_01_2006
 10#define BOOST_ACCUMULATORS_STATISTICS_DENSITY_HPP_DE_01_01_2006
 11
 12#include <vector>
 13#include <limits>
 14#include <functional>
 15#include <boost/range.hpp>
 16#include <boost/parameter/keyword.hpp>
 17#include <boost/mpl/placeholders.hpp>
 18#include <boost/accumulators/framework/accumulator_base.hpp>
 19#include <boost/accumulators/framework/extractor.hpp>
 20#include <boost/accumulators/numeric/functional.hpp>
 21#include <boost/accumulators/framework/parameters/sample.hpp>
 22#include <boost/accumulators/framework/depends_on.hpp>
 23#include <boost/accumulators/statistics_fwd.hpp>
 24#include <boost/accumulators/statistics/count.hpp>
 25#include <boost/accumulators/statistics/max.hpp>
 26#include <boost/accumulators/statistics/min.hpp>
 27
 28namespace boost { namespace accumulators
 29{
 30
 31///////////////////////////////////////////////////////////////////////////////
 32// cache_size and num_bins named parameters
 33//
 34BOOST_PARAMETER_NESTED_KEYWORD(tag, density_cache_size, cache_size)
 35BOOST_PARAMETER_NESTED_KEYWORD(tag, density_num_bins, num_bins)
 36
 37namespace impl
 38{
 39    ///////////////////////////////////////////////////////////////////////////////
 40    // density_impl
 41    //  density histogram
 42    /**
 43        @brief Histogram density estimator
 44
 45        The histogram density estimator returns a histogram of the sample distribution. The positions and sizes of the bins
 46        are determined using a specifiable number of cached samples (cache_size). The range between the minimum and the
 47        maximum of the cached samples is subdivided into a specifiable number of bins (num_bins) of same size. Additionally,
 48        an under- and an overflow bin is added to capture future under- and overflow samples. Once the bins are determined,
 49        the cached samples and all subsequent samples are added to the correct bins. At the end, a range of std::pair is
 50        return, where each pair contains the position of the bin (lower bound) and the samples count (normalized with the
 51        total number of samples).
 52
 53        @param  density_cache_size Number of first samples used to determine min and max.
 54        @param  density_num_bins Number of bins (two additional bins collect under- and overflow samples).
 55    */
 56    template<typename Sample>
 57    struct density_impl
 58      : accumulator_base
 59    {
 60        typedef typename numeric::functional::average<Sample, std::size_t>::result_type float_type;
 61        typedef std::vector<std::pair<float_type, float_type> > histogram_type;
 62        typedef std::vector<float_type> array_type;
 63        // for boost::result_of
 64        typedef iterator_range<typename histogram_type::iterator> result_type;
 65
 66        template<typename Args>
 67        density_impl(Args const &args)
 68            : cache_size(args[density_cache_size])
 69            , cache(cache_size)
 70            , num_bins(args[density_num_bins])
 71            , samples_in_bin(num_bins + 2, 0.)
 72            , bin_positions(num_bins + 2)
 73            , histogram(
 74                num_bins + 2
 75              , std::make_pair(
 76                    numeric::average(args[sample | Sample()],(std::size_t)1)
 77                  , numeric::average(args[sample | Sample()],(std::size_t)1)
 78                )
 79              )
 80            , is_dirty(true)
 81        {
 82        }
 83
 84        template<typename Args>
 85        void operator ()(Args const &args)
 86        {
 87            this->is_dirty = true;
 88
 89            std::size_t cnt = count(args);
 90
 91            // Fill up cache with cache_size first samples
 92            if (cnt <= this->cache_size)
 93            {
 94                this->cache[cnt - 1] = args[sample];
 95            }
 96
 97            // Once cache_size samples have been accumulated, create num_bins bins of same size between
 98            // the minimum and maximum of the cached samples as well as an under- and and an overflow bin.
 99            // Store their lower bounds (bin_positions) and fill the bins with the cached samples (samples_in_bin).
100            if (cnt == this->cache_size)
101            {
102                float_type minimum = numeric::average((min)(args), (std::size_t)1);
103                float_type maximum = numeric::average((max)(args), (std::size_t)1);
104                float_type bin_size = numeric::average(maximum - minimum, this->num_bins );
105
106                // determine bin positions (their lower bounds)
107                for (std::size_t i = 0; i < this->num_bins + 2; ++i)
108                {
109                    this->bin_positions[i] = minimum + (i - 1.) * bin_size;
110                }
111
112                for (typename array_type::const_iterator iter = this->cache.begin(); iter != this->cache.end(); ++iter)
113                {
114                    if (*iter < this->bin_positions[1])
115                    {
116                        ++(this->samples_in_bin[0]);
117                    }
118                    else if (*iter >= this->bin_positions[this->num_bins + 1])
119                    {
120                        ++(this->samples_in_bin[this->num_bins + 1]);
121                    }
122                    else
123                    {
124                        typename array_type::iterator it = std::upper_bound(
125                            this->bin_positions.begin()
126                          , this->bin_positions.end()
127                          , *iter
128                        );
129
130                        std::size_t d = std::distance(this->bin_positions.begin(), it);
131                        ++(this->samples_in_bin[d - 1]);
132                    }
133                }
134            }
135            // Add each subsequent sample to the correct bin
136            else if (cnt > this->cache_size)
137            {
138                if (args[sample] < this->bin_positions[1])
139                {
140                    ++(this->samples_in_bin[0]);
141                }
142                else if (args[sample] >= this->bin_positions[this->num_bins + 1])
143                {
144                    ++(this->samples_in_bin[this->num_bins + 1]);
145                }
146                else
147                {
148                    typename array_type::iterator it = std::upper_bound(
149                        this->bin_positions.begin()
150                      , this->bin_positions.end()
151                      , args[sample]
152                    );
153
154                    std::size_t d = std::distance(this->bin_positions.begin(), it);
155                    ++(this->samples_in_bin[d - 1]);
156                }
157            }
158        }
159
160        /**
161            @pre The number of samples must meet or exceed the cache size
162        */
163        template<typename Args>
164        result_type result(Args const &args) const
165        {
166            if (this->is_dirty)
167            {
168                this->is_dirty = false;
169
170                // creates a vector of std::pair where each pair i holds
171                // the values bin_positions[i] (x-axis of histogram) and
172                // samples_in_bin[i] / cnt (y-axis of histogram).
173
174                for (std::size_t i = 0; i < this->num_bins + 2; ++i)
175                {
176                    this->histogram[i] = std::make_pair(this->bin_positions[i], numeric::average(this->samples_in_bin[i], count(args)));
177                }
178            }
179            // returns a range of pairs
180            return make_iterator_range(this->histogram);
181        }
182
183    private:
184        std::size_t            cache_size;      // number of cached samples
185        array_type             cache;           // cache to store the first cache_size samples
186        std::size_t            num_bins;        // number of bins
187        array_type             samples_in_bin;  // number of samples in each bin
188        array_type             bin_positions;   // lower bounds of bins
189        mutable histogram_type histogram;       // histogram
190        mutable bool is_dirty;
191    };
192
193} // namespace impl
194
195///////////////////////////////////////////////////////////////////////////////
196// tag::density
197//
198namespace tag
199{
200    struct density
201      : depends_on<count, min, max>
202      , density_cache_size
203      , density_num_bins
204    {
205        /// INTERNAL ONLY
206        ///
207        typedef accumulators::impl::density_impl<mpl::_1> impl;
208
209        #ifdef BOOST_ACCUMULATORS_DOXYGEN_INVOKED
210        /// tag::density::cache_size named parameter
211        /// tag::density::num_bins named parameter
212        static boost::parameter::keyword<density_cache_size> const cache_size;
213        static boost::parameter::keyword<density_num_bins> const num_bins;
214        #endif
215    };
216}
217
218///////////////////////////////////////////////////////////////////////////////
219// extract::density
220//
221namespace extract
222{
223    extractor<tag::density> const density = {};
224
225    BOOST_ACCUMULATORS_IGNORE_GLOBAL(density)
226}
227
228using extract::density;
229
230// So that density can be automatically substituted
231// with weighted_density when the weight parameter is non-void.
232template<>
233struct as_weighted_feature<tag::density>
234{
235    typedef tag::weighted_density type;
236};
237
238template<>
239struct feature_of<tag::weighted_density>
240  : feature_of<tag::density>
241{
242};
243
244}} // namespace boost::accumulators
245
246#endif