Evaluate average with hierarchical blocking error analysis. More...
#include <AverageStage.h>
Public Member Functions | |
| AverageStage (int blockFactor=2) | |
| Constructor. More... | |
| virtual | ~AverageStage () |
| Destructor. More... | |
| void | setBlockFactor (int blockFactor) |
| Reset the value of blockFactor. More... | |
| virtual void | clear () |
| Initialize all accumulators and recursively destroy all children. More... | |
| virtual void | sample (double value) |
| Add a sampled value to the ensemble. More... | |
| template<class Archive > | |
| void | serialize (Archive &ar, const unsigned int version) |
| Add a sampled value to the ensemble. More... | |
Accessors | |
| double | average () const |
| Return the average of all sampled values. More... | |
| double | variance () const |
| Return the variance of all sampled values. More... | |
| double | stdDeviation () const |
| Return the standard deviation of all sampled values. More... | |
| double | error () const |
| Return a naive estimate for the std deviation of the average. More... | |
| long | nSample () const |
| Return the number of sampled values in this sequence. More... | |
| long | stageInterval () const |
| Return the number of sampled values per block at this stage. More... | |
| bool | hasChild () const |
| Does this object have a child AverageStage for block averages? More... | |
| AverageStage & | child () |
| Return the child AverageStage by reference. More... | |
Detailed Description
Evaluate average with hierarchical blocking error analysis.
This class implements an algorithm to evaluate the average of a sequence, using a hierarchical blocking algorithm to estimate the error on the average. The algorithm is based on the calculation of variances for sequences of block averages for multiple levels of block sizes, as described in the following reference:
``Error estimates on averages of correlated data", H. Flyvbjerg and H.G. Petersen, J. Chem. Phys. 91, pgs. 461-466 (1989). The blocking algorithm is implemented here by a creating a linked list of AverageStage objects, each of which is responsible for computing the variance on block averages using a different level of blocking. Each object in this list is assigned an integer chainId. The first AverageStage object in the list, with chainId=0, calculates the average and variance for a "primary" sequence of measured values that are passed as parameters to its sample method. This first object is normally an instance of the Average class, which is a subclass of AverageStage that implements features that are only required by the primary stage. This object has a pointer to a child AverageStage with chainId=1 that calculates the variance of a secondary sequence in which each value is the average of blockFactor consecutive values in the primary sequence. The object with chainId=1 in turn has has a pointer to a child object with chainId=2 that calculates the variance of a sequence in which each value is the average of a block of blockFactor**2 consecutive values of the primary sequence, and so on. In general, the object with chainId=n, calculates the variance of a sequence in which each value is an average of blockFactor**n values of the primary sequence. Each value in the sequence analyzed by the object with chainId=n+1 is calculated by the parent object with chainId=n, by calculating an average of a block of blockFactor consecutive values of its own sequence and passing this block average as a parameter the sample() function of the object with chainId=n+1. New stages in this linked list are instantiated and to the list as needed as the length of the primary sequence grows: When an object with chainId=n has been passed a sequence of exactly blockFactor values, it creates a child AverageStage object with chainId=n+1 and passes the average of these first blockFactor values to the sample function of the child object as the first value in its sequence.
A value of the integer parameter blockFactor is passed to the constructor of the primary AverageStage object. This parameter is set to blockFactor=2 by default. Its value may be reset using the setBlockFactor() function before any data is sampled, but may not be changed thereafter.
Definition at line 66 of file AverageStage.h.
Constructor & Destructor Documentation
◆ AverageStage()
| Util::AverageStage::AverageStage | ( | int | blockFactor = 2 | ) |
Constructor.
This constructor creates a primary AverageStage object with stageId = 0 and stageInterval = 1. A private constructor is used to recursively create children of this object.
- Parameters
-
blockFactor ratio of block sizes of subsequent stages
Definition at line 20 of file AverageStage.cpp.
◆ ~AverageStage()
|
virtual |
Member Function Documentation
◆ setBlockFactor()
| void Util::AverageStage::setBlockFactor | ( | int | blockFactor | ) |
Reset the value of blockFactor.
- Exceptions
-
Exception if called when nSample > 0.
Definition at line 63 of file AverageStage.cpp.
References UTIL_THROW.
◆ clear()
|
virtual |
Initialize all accumulators and recursively destroy all children.
Reimplemented in Util::Average.
Definition at line 80 of file AverageStage.cpp.
Referenced by Util::Average::clear().
◆ sample()
|
virtual |
Add a sampled value to the ensemble.
- Parameters
-
value sampled value
Reimplemented in Util::Average.
Definition at line 95 of file AverageStage.cpp.
References sample().
Referenced by Util::Average::sample(), and sample().
◆ serialize()
| void Util::AverageStage::serialize | ( | Archive & | ar, |
| const unsigned int | version | ||
| ) |
Add a sampled value to the ensemble.
- Parameters
-
ar input or output archive version file version id
Definition at line 252 of file AverageStage.h.
References hasChild().
Referenced by Util::Average::loadParameters(), and Util::Average::serialize().
◆ average()
| double Util::AverageStage::average | ( | ) | const |
Return the average of all sampled values.
Definition at line 131 of file AverageStage.cpp.
Referenced by Util::Average::output().
◆ variance()
| double Util::AverageStage::variance | ( | ) | const |
Return the variance of all sampled values.
Definition at line 137 of file AverageStage.cpp.
Referenced by error(), Util::Average::output(), and stdDeviation().
◆ stdDeviation()
| double Util::AverageStage::stdDeviation | ( | ) | const |
Return the standard deviation of all sampled values.
- Returns
- sqrt(variance())
Definition at line 148 of file AverageStage.cpp.
References variance().
Referenced by Util::Average::output().
◆ error()
| double Util::AverageStage::error | ( | ) | const |
Return a naive estimate for the std deviation of the average.
- Returns
- sqrt(variance()/nSample())
Definition at line 166 of file AverageStage.cpp.
References variance().
Referenced by Util::Average::blockingError(), and Util::Average::output().
◆ nSample()
| long Util::AverageStage::nSample | ( | ) | const |
Return the number of sampled values in this sequence.
Definition at line 154 of file AverageStage.cpp.
Referenced by Util::Average::blockingError(), and Util::Average::output().
◆ stageInterval()
| long Util::AverageStage::stageInterval | ( | ) | const |
Return the number of sampled values per block at this stage.
Definition at line 160 of file AverageStage.cpp.
Referenced by Util::Average::output().
◆ hasChild()
|
inlineprotected |
Does this object have a child AverageStage for block averages?
Definition at line 237 of file AverageStage.h.
Referenced by serialize().
◆ child()
|
inlineprotected |
Return the child AverageStage by reference.
Definition at line 243 of file AverageStage.h.
The documentation for this class was generated from the following files:
