1 /******************************************************************************
2 ** $Header: svn+ssh://jmmcg@svn.code.sf.net/p/libjmmcg/code/trunk/libjmmcg/core/ave_deviation_meter.hpp 2055 2017-05-13 19:35:47Z jmmcg $
3 **
4 ** Copyright (c) 2002 by J.M.McGuiness, coder@hussar.me.uk
5 **
6 ** This library is free software; you can redistribute it and/or
7 ** modify it under the terms of the GNU Lesser General Public
8 ** License as published by the Free Software Foundation; either
9 ** version 2.1 of the License, or (at your option) any later version.
10 **
11 ** This library is distributed in the hope that it will be useful,
12 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
13 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 ** Lesser General Public License for more details.
15 **
16 ** You should have received a copy of the GNU Lesser General Public
17 ** License along with this library; if not, write to the Free Software
18 ** Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20
21 #include "ttypes.hpp"
22
23 #include <cstdlib>
24 #include <iomanip>
25 #include <limits>
26
27 namespace jmmcg {
28
29 /// A class used to compute the arithmetic mean and mean-average deviation [1] of a series of events.
30 /**
31 Note that if this class is used in a multi-threaded manner, it is not thread-safe, so these invariants are not guaranteed.
32
33 [1] <a href="http://mathbits.com/MathBits/TISection/Statistics1/MAD.html"/>
34
35 \see invariant()
36 */
37 template<typename MeteredObjType>
38 class ave_deviation_meter {
39 public:
40 typedef MeteredObjType value_type; ///< The type of the object upon which the events will be recorded.
41
42 constexpr ave_deviation_meter() noexcept(true) FORCE_INLINE;
43 explicit constexpr ave_deviation_meter(const value_type val) noexcept(true) FORCE_INLINE;
44 constexpr ave_deviation_meter(value_type const val, double const dev) noexcept(true) FORCE_INLINE;
45 ave_deviation_meter(ave_deviation_meter const &rm) noexcept(true) FORCE_INLINE;
46 ~ave_deviation_meter() noexcept(true) FORCE_INLINE;
47
48 ave_deviation_meter & __fastcall operator=(ave_deviation_meter const &rm) noexcept(true);
49
50 ave_deviation_meter & __fastcall operator+=(ave_deviation_meter const &rm) noexcept(true);
51
52 /// Record a new event that occurred.
53 /**
54 This will update the minimum, maximum, running arithmetic mean and average-deviation measurements.
55 */
56 ave_deviation_meter & __fastcall update(value_type const new_val) noexcept(true);
57
58 /// Return the minimum of the samples taken.
59 constexpr value_type __fastcall FORCE_INLINE min() const noexcept(true);
60 /// Return the arithmetic mean of the samples taken.
61 constexpr value_type __fastcall FORCE_INLINE arithmetic_mean() const noexcept(true);
62 /// Return the maximum of the samples taken.
63 constexpr value_type __fastcall FORCE_INLINE max() const noexcept(true);
64 /// Return the total of all of the samples taken.
65 constexpr value_type __fastcall FORCE_INLINE total() const noexcept(true);
66
67 /// Return the average deviation of the samples taken.
68 /**
69 Note that when using this value you should round to one significant figure.
70 \return The average deviation.
71 */
72 constexpr double __fastcall FORCE_INLINE deviation() const noexcept(true);
73 /// Return the average deviation, as a percent of the mean, of the samples taken.
74 /**
75 Note that when using this value you should round to one significant figure.
76 \return The average deviation as a percentage.
77 */
78 constexpr double __fastcall FORCE_INLINE deviation_percentage() const noexcept(true);
79 /// Return the average deviation as a percentage of the arithmetic mean.
80 constexpr unsigned short FORCE_INLINE percent() const noexcept(true);
81
82 tstring __fastcall to_string() const noexcept(false);
83
84 tstring __fastcall to_csv() const noexcept(false);
85
86 private:
87 /**
88 I'd like to use std::atomic with program-consistency for these values, just to make their behaviour clearer.
89 */
90 unsigned long num_samples_;
91 value_type minimum_, maximum_, total_;
92 double arithmetic_mean_;
93 double ave_deviation;
94
95 void invariant() const noexcept(true);
96 };
97
98 template<typename MeteredObjType>
99 inline tostream & __fastcall FORCE_INLINE
100 operator<<(tostream &os, ave_deviation_meter<MeteredObjType> const &p) noexcept(false);
101
102 /// An algorithm to estimate the average deviation returned after a functor is computed N times.
103 /**
104 \param computations The number of times the functor fn should be computed.
105 \param fn The functor to be computed. It should take no arguments and return ave_deviation_meter::value_type.
106 \return The computed ave_deviation_meter.
107 */
108 template<class MeteredObjType, class Fn>
109 inline ave_deviation_meter<MeteredObjType>
110 estimate_average_deviation(typename ave_deviation_meter<MeteredObjType>::value_type const computations, Fn fn);
111
112 /// An algorithm to compute the ave_deviation_meter of a functor when a specific average deviation is requested.
113 /**
114 \param target_deviation The maximum, target average deviation, as a percentage number, that should be achieved.
115 \param max_computations The maximum number of times the functor fn should be computed, to ensure termination.
116 \param fn The functor to be computed. It should take no arguments and return ave_deviation_meter::value_type.
117 \return The computed ave_deviation_meter and a boolean that if set indicates that the target_deviation could not be achieved within max_computations attempts.
118 */
119 template<class MeteredObjType, class Fn>
120 inline std::pair<ave_deviation_meter<MeteredObjType>, bool>
121 compute_average_deviation(double const target_deviation, typename ave_deviation_meter<MeteredObjType>::value_type const max_computations, Fn fn);
122
123 }
124
125 #include "ave_deviation_meter_impl.hpp"