QuantLib: a free/open-source library for quantitative finance
fully annotated source code - version 1.34
Loading...
Searching...
No Matches
incrementalstatistics.hpp
Go to the documentation of this file.
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
54 public:
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(*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(*begin, *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>,
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>,
171 };
172
173}
174
175
176#endif
Statistics tool based on incremental accumulation.
Size samples() const
number of samples collected
Size downsideSamples() const
number of negative samples collected
Real weightSum() const
sum of data weights
void add(Real value, Real weight=1.0)
adds a datum to the set, possibly with a weight
boost::accumulators::accumulator_set< Real, boost::accumulators::stats< boost::accumulators::tag::count, boost::accumulators::tag::weighted_moment< 2 >, boost::accumulators::tag::sum_of_weights >, Real > downside_accumulator_set
boost::accumulators::accumulator_set< Real, boost::accumulators::stats< boost::accumulators::tag::count, boost::accumulators::tag::min, boost::accumulators::tag::max, boost::accumulators::tag::weighted_mean, boost::accumulators::tag::weighted_variance, boost::accumulators::tag::weighted_skewness, boost::accumulators::tag::weighted_kurtosis, boost::accumulators::tag::sum_of_weights >, Real > accumulator_set
void addSequence(DataIterator begin, DataIterator end)
adds a sequence of data to the set, with default weight
Real downsideWeightSum() const
sum of data weights for negative samples
void addSequence(DataIterator begin, DataIterator end, WeightIterator wbegin)
adds a sequence of data to the set, each with its weight
void reset()
resets the data to a null set
Classes and functions for error handling.
QL_REAL Real
real number
Definition: types.hpp:50
std::size_t Size
size of a container
Definition: types.hpp:58
Definition: any.hpp:35
null values