Chris@16: ///////////////////////////////////////////////////////////////////////////////
Chris@16: // pot_tail_mean.hpp
Chris@16: //
Chris@16: //  Copyright 2006 Daniel Egloff, Olivier Gygi. Distributed under the Boost
Chris@16: //  Software License, Version 1.0. (See accompanying file
Chris@16: //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Chris@16: 
Chris@16: #ifndef BOOST_ACCUMULATORS_STATISTICS_POT_TAIL_MEAN_HPP_DE_01_01_2006
Chris@16: #define BOOST_ACCUMULATORS_STATISTICS_POT_TAIL_MEAN_HPP_DE_01_01_2006
Chris@16: 
Chris@16: #include <vector>
Chris@16: #include <limits>
Chris@16: #include <numeric>
Chris@16: #include <functional>
Chris@16: #include <boost/range.hpp>
Chris@16: #include <boost/parameter/keyword.hpp>
Chris@16: #include <boost/tuple/tuple.hpp>
Chris@16: #include <boost/mpl/if.hpp>
Chris@16: #include <boost/mpl/placeholders.hpp>
Chris@16: #include <boost/type_traits/is_same.hpp>
Chris@16: #include <boost/accumulators/framework/accumulator_base.hpp>
Chris@16: #include <boost/accumulators/framework/extractor.hpp>
Chris@16: #include <boost/accumulators/numeric/functional.hpp>
Chris@16: #include <boost/accumulators/framework/parameters/sample.hpp>
Chris@16: #include <boost/accumulators/statistics_fwd.hpp>
Chris@16: #include <boost/accumulators/statistics/peaks_over_threshold.hpp>
Chris@16: #include <boost/accumulators/statistics/weighted_peaks_over_threshold.hpp>
Chris@16: #include <boost/accumulators/statistics/pot_quantile.hpp>
Chris@16: #include <boost/accumulators/statistics/tail_mean.hpp>
Chris@16: 
Chris@16: namespace boost { namespace accumulators
Chris@16: {
Chris@16: 
Chris@16: namespace impl
Chris@16: {
Chris@16:     ///////////////////////////////////////////////////////////////////////////////
Chris@16:     // pot_tail_mean_impl
Chris@16:     //
Chris@16:     /**
Chris@16:         @brief Estimation of the (coherent) tail mean based on the peaks over threshold method (for both left and right tails)
Chris@16: 
Chris@16:         Computes an estimate for the (coherent) tail mean
Chris@16:         \f[
Chris@16:             \widehat{CTM}_{\alpha} = \hat{q}_{\alpha} - \frac{\bar{\beta}}{\xi-1}(1-\alpha)^{-\xi},
Chris@16:         \f]
Chris@16:         where \f$\bar[u]\f$, \f$\bar{\beta}\f$ and \f$\xi\f$ are the parameters of the
Chris@16:         generalized Pareto distribution that approximates the right tail of the distribution (or the
Chris@16:         mirrored left tail, in case the left tail is used). In the latter case, the result is mirrored
Chris@16:         back, yielding the correct result.
Chris@16:     */
Chris@16:     template<typename Sample, typename Impl, typename LeftRight>
Chris@16:     struct pot_tail_mean_impl
Chris@16:       : accumulator_base
Chris@16:     {
Chris@16:         typedef typename numeric::functional::fdiv<Sample, std::size_t>::result_type float_type;
Chris@16:         // for boost::result_of
Chris@16:         typedef float_type result_type;
Chris@16: 
Chris@16:         pot_tail_mean_impl(dont_care)
Chris@16:           : sign_((is_same<LeftRight, left>::value) ? -1 : 1)
Chris@16:         {
Chris@16:         }
Chris@16: 
Chris@16:         template<typename Args>
Chris@16:         result_type result(Args const &args) const
Chris@16:         {
Chris@16:             typedef
Chris@16:                 typename mpl::if_<
Chris@16:                     is_same<Impl, weighted>
Chris@16:                   , tag::weighted_peaks_over_threshold<LeftRight>
Chris@16:                   , tag::peaks_over_threshold<LeftRight>
Chris@16:                 >::type
Chris@16:             peaks_over_threshold_tag;
Chris@16: 
Chris@16:             typedef
Chris@16:                 typename mpl::if_<
Chris@16:                     is_same<Impl, weighted>
Chris@16:                   , tag::weighted_pot_quantile<LeftRight>
Chris@16:                   , tag::pot_quantile<LeftRight>
Chris@16:                 >::type
Chris@16:             pot_quantile_tag;
Chris@16: 
Chris@16:             extractor<peaks_over_threshold_tag> const some_peaks_over_threshold = {};
Chris@16:             extractor<pot_quantile_tag> const some_pot_quantile = {};
Chris@16: 
Chris@16:             float_type beta_bar = some_peaks_over_threshold(args).template get<1>();
Chris@16:             float_type xi_hat   = some_peaks_over_threshold(args).template get<2>();
Chris@16: 
Chris@16:             return some_pot_quantile(args) - this->sign_ * beta_bar/( xi_hat - 1. ) * std::pow(
Chris@16:                 is_same<LeftRight, left>::value ? args[quantile_probability] : 1. - args[quantile_probability]
Chris@16:               , -xi_hat);
Chris@16:         }
Chris@16:     private:
Chris@16:         short sign_; // if the fit parameters from the mirrored left tail extreme values are used, mirror back the result
Chris@16:     };
Chris@16: } // namespace impl
Chris@16: 
Chris@16: ///////////////////////////////////////////////////////////////////////////////
Chris@16: // tag::pot_tail_mean
Chris@16: // tag::pot_tail_mean_prob
Chris@16: //
Chris@16: namespace tag
Chris@16: {
Chris@16:     template<typename LeftRight>
Chris@16:     struct pot_tail_mean
Chris@16:       : depends_on<peaks_over_threshold<LeftRight>, pot_quantile<LeftRight> >
Chris@16:     {
Chris@16:         /// INTERNAL ONLY
Chris@16:         ///
Chris@16:         typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, unweighted, LeftRight> impl;
Chris@16:     };
Chris@16:     template<typename LeftRight>
Chris@16:     struct pot_tail_mean_prob
Chris@16:       : depends_on<peaks_over_threshold_prob<LeftRight>, pot_quantile_prob<LeftRight> >
Chris@16:     {
Chris@16:         /// INTERNAL ONLY
Chris@16:         ///
Chris@16:         typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, unweighted, LeftRight> impl;
Chris@16:     };
Chris@16:     template<typename LeftRight>
Chris@16:     struct weighted_pot_tail_mean
Chris@16:       : depends_on<weighted_peaks_over_threshold<LeftRight>, weighted_pot_quantile<LeftRight> >
Chris@16:     {
Chris@16:         /// INTERNAL ONLY
Chris@16:         ///
Chris@16:         typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, weighted, LeftRight> impl;
Chris@16:     };
Chris@16:     template<typename LeftRight>
Chris@16:     struct weighted_pot_tail_mean_prob
Chris@16:       : depends_on<weighted_peaks_over_threshold_prob<LeftRight>, weighted_pot_quantile_prob<LeftRight> >
Chris@16:     {
Chris@16:         /// INTERNAL ONLY
Chris@16:         ///
Chris@16:         typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, weighted, LeftRight> impl;
Chris@16:     };
Chris@16: }
Chris@16: 
Chris@16: // pot_tail_mean<LeftRight>(with_threshold_value) -> pot_tail_mean<LeftRight>
Chris@16: template<typename LeftRight>
Chris@16: struct as_feature<tag::pot_tail_mean<LeftRight>(with_threshold_value)>
Chris@16: {
Chris@16:     typedef tag::pot_tail_mean<LeftRight> type;
Chris@16: };
Chris@16: 
Chris@16: // pot_tail_mean<LeftRight>(with_threshold_probability) -> pot_tail_mean_prob<LeftRight>
Chris@16: template<typename LeftRight>
Chris@16: struct as_feature<tag::pot_tail_mean<LeftRight>(with_threshold_probability)>
Chris@16: {
Chris@16:     typedef tag::pot_tail_mean_prob<LeftRight> type;
Chris@16: };
Chris@16: 
Chris@16: // weighted_pot_tail_mean<LeftRight>(with_threshold_value) -> weighted_pot_tail_mean<LeftRight>
Chris@16: template<typename LeftRight>
Chris@16: struct as_feature<tag::weighted_pot_tail_mean<LeftRight>(with_threshold_value)>
Chris@16: {
Chris@16:     typedef tag::weighted_pot_tail_mean<LeftRight> type;
Chris@16: };
Chris@16: 
Chris@16: // weighted_pot_tail_mean<LeftRight>(with_threshold_probability) -> weighted_pot_tail_mean_prob<LeftRight>
Chris@16: template<typename LeftRight>
Chris@16: struct as_feature<tag::weighted_pot_tail_mean<LeftRight>(with_threshold_probability)>
Chris@16: {
Chris@16:     typedef tag::weighted_pot_tail_mean_prob<LeftRight> type;
Chris@16: };
Chris@16: 
Chris@16: // for the purposes of feature-based dependency resolution,
Chris@16: // pot_tail_mean<LeftRight> and pot_tail_mean_prob<LeftRight> provide
Chris@16: // the same feature as tail_mean
Chris@16: template<typename LeftRight>
Chris@16: struct feature_of<tag::pot_tail_mean<LeftRight> >
Chris@16:   : feature_of<tag::tail_mean>
Chris@16: {
Chris@16: };
Chris@16: 
Chris@16: template<typename LeftRight>
Chris@16: struct feature_of<tag::pot_tail_mean_prob<LeftRight> >
Chris@16:   : feature_of<tag::tail_mean>
Chris@16: {
Chris@16: };
Chris@16: 
Chris@16: // So that pot_tail_mean can be automatically substituted
Chris@16: // with weighted_pot_tail_mean when the weight parameter is non-void.
Chris@16: template<typename LeftRight>
Chris@16: struct as_weighted_feature<tag::pot_tail_mean<LeftRight> >
Chris@16: {
Chris@16:     typedef tag::weighted_pot_tail_mean<LeftRight> type;
Chris@16: };
Chris@16: 
Chris@16: template<typename LeftRight>
Chris@16: struct feature_of<tag::weighted_pot_tail_mean<LeftRight> >
Chris@16:   : feature_of<tag::pot_tail_mean<LeftRight> >
Chris@16: {
Chris@16: };
Chris@16: 
Chris@16: // So that pot_tail_mean_prob can be automatically substituted
Chris@16: // with weighted_pot_tail_mean_prob when the weight parameter is non-void.
Chris@16: template<typename LeftRight>
Chris@16: struct as_weighted_feature<tag::pot_tail_mean_prob<LeftRight> >
Chris@16: {
Chris@16:     typedef tag::weighted_pot_tail_mean_prob<LeftRight> type;
Chris@16: };
Chris@16: 
Chris@16: template<typename LeftRight>
Chris@16: struct feature_of<tag::weighted_pot_tail_mean_prob<LeftRight> >
Chris@16:   : feature_of<tag::pot_tail_mean_prob<LeftRight> >
Chris@16: {
Chris@16: };
Chris@16: 
Chris@16: }} // namespace boost::accumulators
Chris@16: 
Chris@16: #endif