accumulators/statistics/pot_quantile.hpp

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