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

  1///////////////////////////////////////////////////////////////////////////////
  2// pot_tail_mean.hpp
  3//
  4//  Copyright 2006 Daniel Egloff, Olivier Gygi. Distributed under the Boost
  5//  Software License, Version 1.0. (See accompanying file
  6//  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  7
  8#ifndef BOOST_ACCUMULATORS_STATISTICS_POT_TAIL_MEAN_HPP_DE_01_01_2006
  9#define BOOST_ACCUMULATORS_STATISTICS_POT_TAIL_MEAN_HPP_DE_01_01_2006
 10
 11#include <vector>
 12#include <limits>
 13#include <numeric>
 14#include <functional>
 15#include <boost/range.hpp>
 16#include <boost/parameter/keyword.hpp>
 17#include <boost/tuple/tuple.hpp>
 18#include <boost/mpl/if.hpp>
 19#include <boost/mpl/placeholders.hpp>
 20#include <boost/type_traits/is_same.hpp>
 21#include <boost/accumulators/framework/accumulator_base.hpp>
 22#include <boost/accumulators/framework/extractor.hpp>
 23#include <boost/accumulators/numeric/functional.hpp>
 24#include <boost/accumulators/framework/parameters/sample.hpp>
 25#include <boost/accumulators/statistics_fwd.hpp>
 26#include <boost/accumulators/statistics/peaks_over_threshold.hpp>
 27#include <boost/accumulators/statistics/weighted_peaks_over_threshold.hpp>
 28#include <boost/accumulators/statistics/pot_quantile.hpp>
 29#include <boost/accumulators/statistics/tail_mean.hpp>
 30
 31namespace boost { namespace accumulators
 32{
 33
 34namespace impl
 35{
 36    ///////////////////////////////////////////////////////////////////////////////
 37    // pot_tail_mean_impl
 38    //
 39    /**
 40        @brief Estimation of the (coherent) tail mean based on the peaks over threshold method (for both left and right tails)
 41
 42        Computes an estimate for the (coherent) tail mean
 43        \f[
 44            \widehat{CTM}_{\alpha} = \hat{q}_{\alpha} - \frac{\bar{\beta}}{\xi-1}(1-\alpha)^{-\xi},
 45        \f]
 46        where \f$\bar[u]\f$, \f$\bar{\beta}\f$ and \f$\xi\f$ are the parameters of the
 47        generalized Pareto distribution that approximates the right tail of the distribution (or the
 48        mirrored left tail, in case the left tail is used). In the latter case, the result is mirrored
 49        back, yielding the correct result.
 50    */
 51    template<typename Sample, typename Impl, typename LeftRight>
 52    struct pot_tail_mean_impl
 53      : accumulator_base
 54    {
 55        typedef typename numeric::functional::average<Sample, std::size_t>::result_type float_type;
 56        // for boost::result_of
 57        typedef float_type result_type;
 58
 59        pot_tail_mean_impl(dont_care)
 60          : sign_((is_same<LeftRight, left>::value) ? -1 : 1)
 61        {
 62        }
 63
 64        template<typename Args>
 65        result_type result(Args const &args) const
 66        {
 67            typedef
 68                typename mpl::if_<
 69                    is_same<Impl, weighted>
 70                  , tag::weighted_peaks_over_threshold<LeftRight>
 71                  , tag::peaks_over_threshold<LeftRight>
 72                >::type
 73            peaks_over_threshold_tag;
 74
 75            typedef
 76                typename mpl::if_<
 77                    is_same<Impl, weighted>
 78                  , tag::weighted_pot_quantile<LeftRight>
 79                  , tag::pot_quantile<LeftRight>
 80                >::type
 81            pot_quantile_tag;
 82
 83            extractor<peaks_over_threshold_tag> const some_peaks_over_threshold = {};
 84            extractor<pot_quantile_tag> const some_pot_quantile = {};
 85
 86            float_type beta_bar = some_peaks_over_threshold(args).template get<1>();
 87            float_type xi_hat   = some_peaks_over_threshold(args).template get<2>();
 88
 89            return some_pot_quantile(args) - this->sign_ * beta_bar/( xi_hat - 1. ) * std::pow(
 90                is_same<LeftRight, left>::value ? args[quantile_probability] : 1. - args[quantile_probability]
 91              , -xi_hat);
 92        }
 93    private:
 94        short sign_; // if the fit parameters from the mirrored left tail extreme values are used, mirror back the result
 95    };
 96} // namespace impl
 97
 98///////////////////////////////////////////////////////////////////////////////
 99// tag::pot_tail_mean
100// tag::pot_tail_mean_prob
101//
102namespace tag
103{
104    template<typename LeftRight>
105    struct pot_tail_mean
106      : depends_on<peaks_over_threshold<LeftRight>, pot_quantile<LeftRight> >
107    {
108        /// INTERNAL ONLY
109        ///
110        typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, unweighted, LeftRight> impl;
111    };
112    template<typename LeftRight>
113    struct pot_tail_mean_prob
114      : depends_on<peaks_over_threshold_prob<LeftRight>, pot_quantile_prob<LeftRight> >
115    {
116        /// INTERNAL ONLY
117        ///
118        typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, unweighted, LeftRight> impl;
119    };
120    template<typename LeftRight>
121    struct weighted_pot_tail_mean
122      : depends_on<weighted_peaks_over_threshold<LeftRight>, weighted_pot_quantile<LeftRight> >
123    {
124        /// INTERNAL ONLY
125        ///
126        typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, weighted, LeftRight> impl;
127    };
128    template<typename LeftRight>
129    struct weighted_pot_tail_mean_prob
130      : depends_on<weighted_peaks_over_threshold_prob<LeftRight>, weighted_pot_quantile_prob<LeftRight> >
131    {
132        /// INTERNAL ONLY
133        ///
134        typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, weighted, LeftRight> impl;
135    };
136}
137
138// pot_tail_mean<LeftRight>(with_threshold_value) -> pot_tail_mean<LeftRight>
139template<typename LeftRight>
140struct as_feature<tag::pot_tail_mean<LeftRight>(with_threshold_value)>
141{
142    typedef tag::pot_tail_mean<LeftRight> type;
143};
144
145// pot_tail_mean<LeftRight>(with_threshold_probability) -> pot_tail_mean_prob<LeftRight>
146template<typename LeftRight>
147struct as_feature<tag::pot_tail_mean<LeftRight>(with_threshold_probability)>
148{
149    typedef tag::pot_tail_mean_prob<LeftRight> type;
150};
151
152// weighted_pot_tail_mean<LeftRight>(with_threshold_value) -> weighted_pot_tail_mean<LeftRight>
153template<typename LeftRight>
154struct as_feature<tag::weighted_pot_tail_mean<LeftRight>(with_threshold_value)>
155{
156    typedef tag::weighted_pot_tail_mean<LeftRight> type;
157};
158
159// weighted_pot_tail_mean<LeftRight>(with_threshold_probability) -> weighted_pot_tail_mean_prob<LeftRight>
160template<typename LeftRight>
161struct as_feature<tag::weighted_pot_tail_mean<LeftRight>(with_threshold_probability)>
162{
163    typedef tag::weighted_pot_tail_mean_prob<LeftRight> type;
164};
165
166// for the purposes of feature-based dependency resolution,
167// pot_tail_mean<LeftRight> and pot_tail_mean_prob<LeftRight> provide
168// the same feature as tail_mean
169template<typename LeftRight>
170struct feature_of<tag::pot_tail_mean<LeftRight> >
171  : feature_of<tag::tail_mean>
172{
173};
174
175template<typename LeftRight>
176struct feature_of<tag::pot_tail_mean_prob<LeftRight> >
177  : feature_of<tag::tail_mean>
178{
179};
180
181// So that pot_tail_mean can be automatically substituted
182// with weighted_pot_tail_mean when the weight parameter is non-void.
183template<typename LeftRight>
184struct as_weighted_feature<tag::pot_tail_mean<LeftRight> >
185{
186    typedef tag::weighted_pot_tail_mean<LeftRight> type;
187};
188
189template<typename LeftRight>
190struct feature_of<tag::weighted_pot_tail_mean<LeftRight> >
191  : feature_of<tag::pot_tail_mean<LeftRight> >
192{
193};
194
195// So that pot_tail_mean_prob can be automatically substituted
196// with weighted_pot_tail_mean_prob when the weight parameter is non-void.
197template<typename LeftRight>
198struct as_weighted_feature<tag::pot_tail_mean_prob<LeftRight> >
199{
200    typedef tag::weighted_pot_tail_mean_prob<LeftRight> type;
201};
202
203template<typename LeftRight>
204struct feature_of<tag::weighted_pot_tail_mean_prob<LeftRight> >
205  : feature_of<tag::pot_tail_mean_prob<LeftRight> >
206{
207};
208
209}} // namespace boost::accumulators
210
211#endif