1/* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
3/*
4 Copyright (C) 2003 Ferdinando Ametrano
5 Copyright (C) 2000, 2001, 2002, 2003 RiskMap srl
6 Copyright (C) 2015 Peter Caspers
7
8 This file is part of QuantLib, a free-software/open-source library
9 for financial quantitative analysts and developers - http://quantlib.org/
10
11 QuantLib is free software: you can redistribute it and/or modify it
12 under the terms of the QuantLib license. You should have received a
13 copy of the license along with this program; if not, please email
14 <quantlib-dev@lists.sf.net>. The license is also available online at
15 <http://quantlib.org/license.shtml>.
16
17 This program is distributed in the hope that it will be useful, but WITHOUT
18 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
19 FOR A PARTICULAR PURPOSE. See the license for more details.
20*/
21
22/*! \file incrementalstatistics.hpp
23 \brief statistics tool based on incremental accumulation
24 in the meantime, this is just a wrapper to the boost
25 accumulator library, kept for backward compatibility
26*/
27
28#ifndef quantlib_incremental_statistics_hpp
29#define quantlib_incremental_statistics_hpp
30
31#include <ql/utilities/null.hpp>
32#include <ql/errors.hpp>
33#include <boost/accumulators/accumulators.hpp>
34#include <boost/accumulators/statistics/stats.hpp>
35#include <boost/accumulators/statistics/count.hpp>
36#include <boost/accumulators/statistics/sum.hpp>
37#include <boost/accumulators/statistics/min.hpp>
38#include <boost/accumulators/statistics/max.hpp>
39#include <boost/accumulators/statistics/weighted_mean.hpp>
40#include <boost/accumulators/statistics/weighted_variance.hpp>
41#include <boost/accumulators/statistics/weighted_skewness.hpp>
42#include <boost/accumulators/statistics/weighted_kurtosis.hpp>
43#include <boost/accumulators/statistics/weighted_moment.hpp>
44
45namespace QuantLib {
46
47 //! Statistics tool based on incremental accumulation
48 /*! It can accumulate a set of data and return statistics (e.g: mean,
49 variance, skewness, kurtosis, error estimation, etc.).
50 This class is a wrapper to the boost accumulator library.
51 */
52
53 class IncrementalStatistics {
54 public:
55 typedef Real value_type;
56 IncrementalStatistics();
57 //! \name Inspectors
58 //@{
59 //! number of samples collected
60 Size samples() const;
61
62 //! sum of data weights
63 Real weightSum() const;
64
65 /*! returns the mean, defined as
66 \f[ \langle x \rangle = \frac{\sum w_i x_i}{\sum w_i}. \f]
67 */
68 Real mean() const;
69
70 /*! returns the variance, defined as
71 \f[ \frac{N}{N-1} \left\langle \left(
72 x-\langle x \rangle \right)^2 \right\rangle. \f]
73 */
74 Real variance() const;
75
76 /*! returns the standard deviation \f$ \sigma \f$, defined as the
77 square root of the variance.
78 */
79 Real standardDeviation() const;
80
81 /*! returns the error estimate \f$ \epsilon \f$, defined as the
82 square root of the ratio of the variance to the number of
83 samples.
84 */
85 Real errorEstimate() const;
86
87 /*! returns the skewness, defined as
88 \f[ \frac{N^2}{(N-1)(N-2)} \frac{\left\langle \left(
89 x-\langle x \rangle \right)^3 \right\rangle}{\sigma^3}. \f]
90 The above evaluates to 0 for a Gaussian distribution.
91 */
92 Real skewness() const;
93
94 /*! returns the excess kurtosis, defined as
95 \f[ \frac{N^2(N+1)}{(N-1)(N-2)(N-3)}
96 \frac{\left\langle \left(x-\langle x \rangle \right)^4
97 \right\rangle}{\sigma^4} - \frac{3(N-1)^2}{(N-2)(N-3)}. \f]
98 The above evaluates to 0 for a Gaussian distribution.
99 */
100 Real kurtosis() const;
101
102 /*! returns the minimum sample value */
103 Real min() const;
104
105 /*! returns the maximum sample value */
106 Real max() const;
107
108 //! number of negative samples collected
109 Size downsideSamples() const;
110
111 //! sum of data weights for negative samples
112 Real downsideWeightSum() const;
113
114 /*! returns the downside variance, defined as
115 \f[ \frac{N}{N-1} \times \frac{ \sum_{i=1}^{N}
116 \theta \times x_i^{2}}{ \sum_{i=1}^{N} w_i} \f],
117 where \f$ \theta \f$ = 0 if x > 0 and
118 \f$ \theta \f$ =1 if x <0
119 */
120 Real downsideVariance() const;
121
122 /*! returns the downside deviation, defined as the
123 square root of the downside variance.
124 */
125 Real downsideDeviation() const;
126
127 //@}
128
129 //! \name Modifiers
130 //@{
131 //! adds a datum to the set, possibly with a weight
132 /*! \pre weight must be positive or null */
133 void add(Real value, Real weight = 1.0);
134 //! adds a sequence of data to the set, with default weight
135 template <class DataIterator>
136 void addSequence(DataIterator begin, DataIterator end) {
137 for (;begin!=end;++begin)
138 add(value: *begin);
139 }
140 //! adds a sequence of data to the set, each with its weight
141 /*! \pre weights must be positive or null */
142 template <class DataIterator, class WeightIterator>
143 void addSequence(DataIterator begin, DataIterator end,
144 WeightIterator wbegin) {
145 for (;begin!=end;++begin,++wbegin)
146 add(value: *begin, weight: *wbegin);
147 }
148 //! resets the data to a null set
149 void reset();
150 //@}
151 private:
152 typedef boost::accumulators::accumulator_set<
153 Real,
154 boost::accumulators::stats<
155 boost::accumulators::tag::count, boost::accumulators::tag::min,
156 boost::accumulators::tag::max,
157 boost::accumulators::tag::weighted_mean,
158 boost::accumulators::tag::weighted_variance,
159 boost::accumulators::tag::weighted_skewness,
160 boost::accumulators::tag::weighted_kurtosis,
161 boost::accumulators::tag::sum_of_weights>,
162 Real> accumulator_set;
163 accumulator_set acc_;
164 typedef boost::accumulators::accumulator_set<
165 Real, boost::accumulators::stats<
166 boost::accumulators::tag::count,
167 boost::accumulators::tag::weighted_moment<2>,
168 boost::accumulators::tag::sum_of_weights>,
169 Real> downside_accumulator_set;
170 downside_accumulator_set downsideAcc_;
171 };
172
173}
174
175
176#endif
177

source code of quantlib/ql/math/statistics/incrementalstatistics.hpp