accumulators/statistics/pot_tail_mean.hpp

0001 ///////////////////////////////////////////////////////////////////////////////
0002 // pot_tail_mean.hpp
0003 //
0004 //  Copyright 2006 Daniel Egloff, Olivier Gygi. Distributed under the Boost
0005 //  Software License, Version 1.0. (See accompanying file
0006 //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0007
0008 #ifndef BOOST_ACCUMULATORS_STATISTICS_POT_TAIL_MEAN_HPP_DE_01_01_2006
0009 #define BOOST_ACCUMULATORS_STATISTICS_POT_TAIL_MEAN_HPP_DE_01_01_2006
0010
0011 #include <vector>
0012 #include <limits>
0013 #include <numeric>
0014 #include <functional>
0015 #include <boost/range.hpp>
0016 #include <boost/parameter/keyword.hpp>
0017 #include <boost/tuple/tuple.hpp>
0018 #include <boost/mpl/if.hpp>
0019 #include <boost/mpl/placeholders.hpp>
0020 #include <boost/type_traits/is_same.hpp>
0021 #include <boost/accumulators/framework/accumulator_base.hpp>
0022 #include <boost/accumulators/framework/extractor.hpp>
0023 #include <boost/accumulators/numeric/functional.hpp>
0024 #include <boost/accumulators/framework/parameters/sample.hpp>
0025 #include <boost/accumulators/statistics_fwd.hpp>
0026 #include <boost/accumulators/statistics/peaks_over_threshold.hpp>
0027 #include <boost/accumulators/statistics/weighted_peaks_over_threshold.hpp>
0028 #include <boost/accumulators/statistics/pot_quantile.hpp>
0029 #include <boost/accumulators/statistics/tail_mean.hpp>
0030
0031 namespace boost { namespace accumulators
0032 {
0033
0034 namespace impl
0035 {
0036     ///////////////////////////////////////////////////////////////////////////////
0037     // pot_tail_mean_impl
0038     //
0039     /**
0040         @brief Estimation of the (coherent) tail mean based on the peaks over threshold method (for both left and right tails)
0041
0042         Computes an estimate for the (coherent) tail mean
0043         \f[
0044             \widehat{CTM}_{\alpha} = \hat{q}_{\alpha} - \frac{\bar{\beta}}{\xi-1}(1-\alpha)^{-\xi},
0045         \f]
0046         where \f$\bar[u]\f$, \f$\bar{\beta}\f$ and \f$\xi\f$ are the parameters of the
0047         generalized Pareto distribution that approximates the right tail of the distribution (or the
0048         mirrored left tail, in case the left tail is used). In the latter case, the result is mirrored
0049         back, yielding the correct result.
0050     */
0051     template<typename Sample, typename Impl, typename LeftRight>
0052     struct pot_tail_mean_impl
0053       : accumulator_base
0054     {
0055         typedef typename numeric::functional::fdiv<Sample, std::size_t>::result_type float_type;
0056         // for boost::result_of
0057         typedef float_type result_type;
0058
0059         pot_tail_mean_impl(dont_care)
0060           : sign_((is_same<LeftRight, left>::value) ? -1 : 1)
0061         {
0062         }
0063
0064         template<typename Args>
0065         result_type result(Args const &args) const
0066         {
0067             typedef
0068                 typename mpl::if_<
0069                     is_same<Impl, weighted>
0070                   , tag::weighted_peaks_over_threshold<LeftRight>
0071                   , tag::peaks_over_threshold<LeftRight>
0072                 >::type
0073             peaks_over_threshold_tag;
0074
0075             typedef
0076                 typename mpl::if_<
0077                     is_same<Impl, weighted>
0078                   , tag::weighted_pot_quantile<LeftRight>
0079                   , tag::pot_quantile<LeftRight>
0080                 >::type
0081             pot_quantile_tag;
0082
0083             extractor<peaks_over_threshold_tag> const some_peaks_over_threshold = {};
0084             extractor<pot_quantile_tag> const some_pot_quantile = {};
0085
0086             float_type beta_bar = some_peaks_over_threshold(args).template get<1>();
0087             float_type xi_hat   = some_peaks_over_threshold(args).template get<2>();
0088
0089             return some_pot_quantile(args) - this->sign_ * beta_bar/( xi_hat - 1. ) * std::pow(
0090                 is_same<LeftRight, left>::value ? args[quantile_probability] : 1. - args[quantile_probability]
0091               , -xi_hat);
0092         }
0093
0094         // make this accumulator serializeable
0095         template<class Archive>
0096         void serialize(Archive & ar, const unsigned int file_version)
0097         {
0098             ar & sign_;
0099         }
0100
0101     private:
0102         short sign_; // if the fit parameters from the mirrored left tail extreme values are used, mirror back the result
0103     };
0104 } // namespace impl
0105
0106 ///////////////////////////////////////////////////////////////////////////////
0107 // tag::pot_tail_mean
0108 // tag::pot_tail_mean_prob
0109 //
0110 namespace tag
0111 {
0112     template<typename LeftRight>
0113     struct pot_tail_mean
0114       : depends_on<peaks_over_threshold<LeftRight>, pot_quantile<LeftRight> >
0115     {
0116         /// INTERNAL ONLY
0117         ///
0118         typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, unweighted, LeftRight> impl;
0119     };
0120     template<typename LeftRight>
0121     struct pot_tail_mean_prob
0122       : depends_on<peaks_over_threshold_prob<LeftRight>, pot_quantile_prob<LeftRight> >
0123     {
0124         /// INTERNAL ONLY
0125         ///
0126         typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, unweighted, LeftRight> impl;
0127     };
0128     template<typename LeftRight>
0129     struct weighted_pot_tail_mean
0130       : depends_on<weighted_peaks_over_threshold<LeftRight>, weighted_pot_quantile<LeftRight> >
0131     {
0132         /// INTERNAL ONLY
0133         ///
0134         typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, weighted, LeftRight> impl;
0135     };
0136     template<typename LeftRight>
0137     struct weighted_pot_tail_mean_prob
0138       : depends_on<weighted_peaks_over_threshold_prob<LeftRight>, weighted_pot_quantile_prob<LeftRight> >
0139     {
0140         /// INTERNAL ONLY
0141         ///
0142         typedef accumulators::impl::pot_tail_mean_impl<mpl::_1, weighted, LeftRight> impl;
0143     };
0144 }
0145
0146 // pot_tail_mean<LeftRight>(with_threshold_value) -> pot_tail_mean<LeftRight>
0147 template<typename LeftRight>
0148 struct as_feature<tag::pot_tail_mean<LeftRight>(with_threshold_value)>
0149 {
0150     typedef tag::pot_tail_mean<LeftRight> type;
0151 };
0152
0153 // pot_tail_mean<LeftRight>(with_threshold_probability) -> pot_tail_mean_prob<LeftRight>
0154 template<typename LeftRight>
0155 struct as_feature<tag::pot_tail_mean<LeftRight>(with_threshold_probability)>
0156 {
0157     typedef tag::pot_tail_mean_prob<LeftRight> type;
0158 };
0159
0160 // weighted_pot_tail_mean<LeftRight>(with_threshold_value) -> weighted_pot_tail_mean<LeftRight>
0161 template<typename LeftRight>
0162 struct as_feature<tag::weighted_pot_tail_mean<LeftRight>(with_threshold_value)>
0163 {
0164     typedef tag::weighted_pot_tail_mean<LeftRight> type;
0165 };
0166
0167 // weighted_pot_tail_mean<LeftRight>(with_threshold_probability) -> weighted_pot_tail_mean_prob<LeftRight>
0168 template<typename LeftRight>
0169 struct as_feature<tag::weighted_pot_tail_mean<LeftRight>(with_threshold_probability)>
0170 {
0171     typedef tag::weighted_pot_tail_mean_prob<LeftRight> type;
0172 };
0173
0174 // for the purposes of feature-based dependency resolution,
0175 // pot_tail_mean<LeftRight> and pot_tail_mean_prob<LeftRight> provide
0176 // the same feature as tail_mean
0177 template<typename LeftRight>
0178 struct feature_of<tag::pot_tail_mean<LeftRight> >
0179   : feature_of<tag::tail_mean>
0180 {
0181 };
0182
0183 template<typename LeftRight>
0184 struct feature_of<tag::pot_tail_mean_prob<LeftRight> >
0185   : feature_of<tag::tail_mean>
0186 {
0187 };
0188
0189 // So that pot_tail_mean can be automatically substituted
0190 // with weighted_pot_tail_mean when the weight parameter is non-void.
0191 template<typename LeftRight>
0192 struct as_weighted_feature<tag::pot_tail_mean<LeftRight> >
0193 {
0194     typedef tag::weighted_pot_tail_mean<LeftRight> type;
0195 };
0196
0197 template<typename LeftRight>
0198 struct feature_of<tag::weighted_pot_tail_mean<LeftRight> >
0199   : feature_of<tag::pot_tail_mean<LeftRight> >
0200 {
0201 };
0202
0203 // So that pot_tail_mean_prob can be automatically substituted
0204 // with weighted_pot_tail_mean_prob when the weight parameter is non-void.
0205 template<typename LeftRight>
0206 struct as_weighted_feature<tag::pot_tail_mean_prob<LeftRight> >
0207 {
0208     typedef tag::weighted_pot_tail_mean_prob<LeftRight> type;
0209 };
0210
0211 template<typename LeftRight>
0212 struct feature_of<tag::weighted_pot_tail_mean_prob<LeftRight> >
0213   : feature_of<tag::pot_tail_mean_prob<LeftRight> >
0214 {
0215 };
0216
0217 }} // namespace boost::accumulators
0218
0219 #endif