Boost C++ Libraries

Our tour of the accumulator_set<> class template begins with the forward declaration:

template< typename Sample, typename Features, typename Weight = void >
struct accumulator_set;

The template parameters have the following meaning:

For example, the following line declares an accumulator_set<> that will accept a sequence of doubles one at a time and calculate the min and mean:

accumulator_set< double, features< tag::min, tag::mean > > acc;

Notice that we use the features<> template to specify a list of features to be calculated. features<> is an MPL sequence of features.

	Note
	features<> is a synonym of mpl::vector<>. In fact, we could use mpl::vector<> or any MPL sequence if we prefer, and the meaning would be the same.

Once we have defined an accumulator_set<>, we can then push data into it, and it will calculate the quantities you requested, as shown below.

// push some data into the accumulator_set ...
acc(1.2);
acc(2.3);
acc(3.4);

Since accumulator_set<> defines its accumulate function to be the function call operator, we might be tempted to use an accumulator_set<> as a UnaryFunction to a standard algorithm such as std::for_each. That's fine as long as we keep in mind that the standard algorithms take UnaryFunction objects by value, which involves making a copy of the accumulator_set<> object. Consider the following:

// The data for which we wish to calculate statistical properties:
std::vector< double > data( /* stuff */ );

// The accumulator set which will calculate the properties for us:    
accumulator_set< double, features< tag::min, tag::mean > > acc;

// Use std::for_each to accumulate the statistical properties:
acc = std::for_each( data.begin(), data.end(), acc );

Notice how we must assign the return value of std::for_each back to the accumulator_set<>. This works, but some accumulators are not cheap to copy. For example, the tail and tail_variate<> accumulators must store a std::vector<>, so copying these accumulators involves a dynamic allocation. We might be better off in this case passing the accumulator by reference, with the help of boost::bind() and boost::ref(). See below:

// The data for which we wish to calculate statistical properties:
std::vector< double > data( /* stuff */ );

// The accumulator set which will calculate the properties for us:
accumulator_set< double, features< tag::tail<left> > > acc(
    tag::tail<left>::cache_size = 4 );

// Use std::for_each to accumulate the statistical properties:
std::for_each( data.begin(), data.end(), bind<void>( ref(acc), _1 ) );

Notice now that we don't care about the return value of std::for_each() anymore because std::for_each() is modifying acc directly.

	Note
	To use boost::bind() and boost::ref(), you must #include <boost/bind.hpp> and <boost/ref.hpp>

Once we have declared an accumulator_set<> and pushed data into it, we need to be able to extract results from it. For each feature we can add to an accumulator_set<>, there is a corresponding extractor for fetching its result. Usually, the extractor has the same name as the feature, but in a different namespace. For example, if we accumulate the tag::min and tag::max features, we can extract the results with the min and max extractors, as follows:

// Calculate the minimum and maximum for a sequence of integers.
accumulator_set< int, features< tag::min, tag::max > > acc;
acc( 2 );
acc( -1 );
acc( 1 );

// This displays "(-1, 2)"
std::cout << '(' << min( acc ) << ", " << max( acc ) << ")\n";

The extractors are all declared in the boost::accumulators::extract namespace, but they are brought into the boost::accumulators namespace with a using declaration.

	Tip
	On the Windows platform, min and max are preprocessor macros defined in WinDef.h. To use the min and max extractors, you should either compile with NOMINMAX defined, or you should invoke the extractors like: (min)( acc ) and (max)( acc ). The parentheses keep the macro from being invoked.

Another way to extract a result from an accumulator_set<> is with the extract_result() function. This can be more convenient if there isn't an extractor object handy for a certain feature. The line above which displays results could equally be written as:

// This displays "(-1, 2)"
std::cout << '('  << extract_result< tag::min >( acc )
          << ", " << extract_result< tag::max >( acc ) << ")\n";

Finally, we can define our own extractor using the extractor<> class template. For instance, another way to avoid the min / max macro business would be to define extractors with names that don't conflict with the macros, like this:

extractor< tag::min > min_;
extractor< tag::min > max_;

// This displays "(-1, 2)"
std::cout << '(' << min_( acc ) << ", " << max_( acc ) << ")\n";

Some accumulators need initialization parameters. In addition, perhaps some auxiliary information needs to be passed into the accumulator_set<> along with each sample. Boost.Accumulators handles these cases with named parameters from the Boost.Parameter library.

For example, consider the tail and tail_variate<> features. tail keeps an ordered list of the largest N samples, where N can be specified at construction time. Also, the tail_variate<> feature, which depends on tail, keeps track of some data that is covariate with the N samples tracked by tail. The code below shows how this all works, and is described in more detail below.

// Define a feature for tracking covariate data
typedef tag::tail_variate< int, tag::covariate1, left > my_tail_variate_tag;

// This will calculate the left tail and my_tail_variate_tag for N == 2
// using the tag::tail<left>::cache_size named parameter
accumulator_set< double, features< my_tail_variate_tag > > acc(
    tag::tail<left>::cache_size = 2 );

// push in some samples and some covariates by using 
// the covariate1 named parameter
acc( 1.2, covariate1 =  12 );
acc( 2.3, covariate1 = -23 );
acc( 3.4, covariate1 =  34 );
acc( 4.5, covariate1 = -45 );

// Define an extractor for the my_tail_variate_tag feature
extractor< my_tail_variate_tag > my_tail_variate;

// Write the tail statistic to std::cout. This will print "4.5, 3.4, "
std::ostream_iterator< double > dout( std::cout, ", " );
std::copy( tail( acc ).begin(), tail( acc ).end(), dout );

// Write the tail_variate statistic to std::cout. This will print "-45, 34, "
std::ostream_iterator< int > iout( std::cout, ", " );
std::copy( my_tail_variate( acc ).begin(), my_tail_variate( acc ).end(), iout );

There are several things to note about the code above. First, notice that we didn't have to request that the tail feature be calculated. That is implicit because the tail_variate<> feature depends on the tail feature. Next, notice how the acc object is initialized: acc( tag::tail<left>::cache_size = 2 ). Here, cache_size is a named parameter. It is used to tell the tail and tail_variate<> accumulators how many samples and covariates to store. Conceptually, every construction parameter is made available to every accumulator in an accumulator set.

We also use a named parameter to pass covariate data into the accumulator set along with the samples. As with the constructor parameters, all parameters to the accumulate function are made available to all the accumulators in the set. In this case, only the accumulator for the my_tail_variate feature would be interested in the value of the covariate1 named parameter.

We can make one final observation about the example above. Since tail and tail_variate<> are multi-valued features, the result we extract for them is represented as an iterator range. That is why we can say tail( acc ).begin() and tail( acc ).end().

Even the extractors can accept named parameters. In a bit, we'll see a situation where that is useful.

Some accumulators, statistical accumulators in particular, deal with data that are weighted. Each sample pushed into the accumulator has an associated weight, by which the sample is conceptually multiplied. The Statistical Accumulators Library provides an assortment of these weighted statistical accumulators. And many unweighted statistical accumulators have weighted variants. For instance, the weighted variant of the sum accumulator is called weighted_sum, and is calculated by accumulating all the samples multiplied by their weights.

To declare an accumulator_set<> that accepts weighted samples, you must specify the type of the weight parameter as the 3rd template parameter, as follows:

// 3rd template parameter 'int' means this is a weighted
// accumulator set where the weights have type 'int'
accumulator_set< int, features< tag::sum >, int > acc;

When you specify a weight, all the accumulators in the set are replaced with their weighted equivalents. For example, the above accumulator_set<> declaration is equivalent to the following:

// Since we specified a weight, tag::sum becomes tag::weighted_sum
accumulator_set< int, features< tag::weighted_sum >, int > acc;

When passing samples to the accumulator set, you must also specify the weight of each sample. You can do that with the weight named parameter, as follows:

acc(1, weight = 2); //   1 * 2
acc(2, weight = 4); //   2 * 4
acc(3, weight = 6); // + 3 * 6
                    // -------
                    // =    28

You can then extract the result with the sum() extractor, as follows:

// This prints "28"
std::cout << sum(acc) << std::endl;

	Note
	When working with weighted statistical accumulators from the Statistical Accumulators Library, be sure to include the appropriate header. For instance, weighted_sum is defined in <boost/accumulators/statistics/weighted_sum.hpp>.

This section describes the function objects in the boost::numeric namespace, which is a sub-library that provides function objects and meta-functions corresponding to the infix operators in C++.

In the boost::numeric::operators namespace are additional operator overloads for some useful operations not provided by the standard library, such as multiplication of a std::complex<> with a scalar.

In the boost::numeric::functional namespace are function object equivalents of the infix operators. These function object types are heterogeneous, and so are more general than the standard ones found in the <functional> header. They use the Boost.Typeof library to deduce the return types of the infix expressions they evaluate. In addition, they look within the boost::numeric::operators namespace to consider any additional overloads that might be defined there.

In the boost::numeric namespace are global polymorphic function objects corresponding to the function object types defined in the boost::numeric::functional namespace. For example, boost::numeric::plus(a, b) is equivalent to boost::numeric::functional::plus<A, B>()(a, b), and both are equivalent to using namespace boost::numeric::operators; a + b;.

The Numeric Operators Sub-Library also gives several ways to sub-class and a way to sub-class and specialize operations. One way uses tag dispatching on the types of the operands. The other way is based on the compile-time properties of the operands.

This section describes how to extend the Accumulators Framework by defining new accumulators, features and extractors. Also covered are how to control the dependency resolution of features within an accumulator set.

Defining a New Accumulator

All new accumulators must satisfy the Accumulator Concept. Below is a sample class that satisfies the accumulator concept, which simply sums the values of all samples passed into it.

#include <boost/accumulators/framework/accumulator_base.hpp>
#include <boost/accumulators/framework/parameters/sample.hpp>

namespace boost {                           // Putting your accumulators in the
namespace accumulators {                    // impl namespace has some
namespace impl {                            // advantages. See below.

template<typename Sample>
struct sum_accumulator                      // All accumulators should inherit from
  : accumulator_base                        // accumulator_base.
{
    typedef Sample result_type;             // The type returned by result() below.

    template<typename Args>                 // The constructor takes an argument pack.
    sum_accumulator(Args const & args)
      : sum(args[sample | Sample()])        // Maybe there is an initial value in the
    {                                       // argument pack. ('sample' is defined in
    }                                       // sample.hpp, included above.)

    template<typename Args>                 // The accumulate function is the function
    void operator ()(Args const & args)     // call operator, and it also accepts an
    {                                       // argument pack.
        this->sum += args[sample];
    }

    result_type result(dont_care) const     // The result function will also be passed
    {                                       // an argument pack, but we don't use it here,
        return this->sum;                   // so we use "dont_care" as the argument type.
    }
private:
    Sample sum;
};

}}}

Much of the above should be pretty self-explanatory, except for the use of argument packs which may be confusing if you have never used the Boost.Parameter library before. An argument pack is a cluster of values, each of which can be accessed with a key. So args[sample] extracts from the pack the value associated with the sample key. And the cryptic args[sample | Sample()] evaluates to the value associated with the sample key if it exists, or a default-constructed Sample if it doesn't.

The example above demonstrates the most common attributes of an accumulator. There are other optional member functions that have special meaning. In particular:

Optional Accumulator Member Functions

on_drop(Args)

Defines an action to be taken when this accumulator is dropped. See the section on Droppable Accumulators.

Accessing Other Accumulators in the Set

Some accumulators depend on other accumulators within the same accumulator set. In those cases, it is necessary to be able to access those other accumulators. To make this possible, the accumulator_set<> passes a reference to itself when invoking the member functions of its contained accumulators. It can be accessed by using the special accumulator key with the argument pack. Consider how we might implement mean_accumulator:

// Mean == (Sum / Count)
template<typename Sample>
struct mean_accumulator : accumulator_base
{
    typedef Sample result_type;
    mean_accumulator(dont_care) {}

    template<typename Args>
    result_type result(Args const &args) const
    {
        return sum(args[accumulator]) / count(args[accumulator]);
    }
};

mean depends on the sum and count accumulators. (We'll see in the next section how to specify these dependencies.) The result of the mean accumulator is merely the result of the sum accumulator divided by the result of the count accumulator. Consider how we write that: sum(args[accumulator]) / count(args[accumulator]). The expression args[accumulator] evaluates to a reference to the accumulator_set<> that contains this mean_accumulator. It also contains the sum and count accumulators, and we can access their results with the extractors defined for those features: sum and count.

	Note
	Accumulators that inherit from accumulator_base get an empty operator (), so accumulators like mean_accumulator above need not define one.

All the member functions that accept an argument pack have access to the enclosing accumulator_set<> via the accumulator key, including the constructor. The accumulators within the set are constructed in an order determined by their interdependencies. As a result, it is safe for an accumulator to access one on which it depends during construction.

Infix Notation and the Numeric Operators Sub-Library

Although not necessary, it can be a good idea to put your accumulator implementations in the boost::accumulators::impl namespace. This namespace pulls in any operators defined in the boost::numeric::operators namespace with a using directive. The Numeric Operators Sub-Library defines some additional overloads that will make your accumulators work with all sorts of data types.

Consider mean_accumulator defined above. It divides the sum of the samples by the count. The type of the count is std::size_t. What if the sample type doesn't define division by std::size_t? That's the case for std::complex<>. You might think that if the sample type is std::complex<>, the code would not work, but in fact it does. That's because Numeric Operators Sub-Library defines an overloaded operator/ for std::complex<> and std::size_t. This operator is defined in the boost::numeric::operators namespace and will be found within the boost::accumulators::impl namespace. That's why it's a good idea to put your accumulators there.

Droppable Accumulators

The term "droppable" refers to an accumulator that can be removed from the accumulator_set<>. You can request that an accumulator be made droppable by using the droppable<> class template.

// calculate sum and count, make sum droppable:
accumulator_set< double, features< tag::count, droppable<tag::sum> > > acc;

// add some data
acc(3.0);
acc(2.0);

// drop the sum (sum is 5 here)
acc.drop<tag::sum>();

// add more data
acc(1.0);

// This will display "3" and "5"
std::cout << count(acc) << ' ' << sum(acc);

Any accumulators that get added to an accumulator set in order to satisfy dependencies on droppable accumulators are themselves droppable. Consider the following accumulator:

// Sum is not droppable. Mean is droppable. Count, brought in to 
// satisfy mean's dependencies, is implicitly droppable, too.
accumulator_set< double, features< tag::sum, droppable<tag::mean> > > acc;

mean depends on sum and count. Since mean is droppable, so too is count. However, we have explicitly requested that sum be not droppable, so it isn't. Had we left tag::sum out of the above declaration, the sum accumulator would have been implicitly droppable.

A droppable accumulator is reference counted, and is only really dropped after all the accumulators that depend on it have been dropped. This can lead to some surprising behavior in some situations.

// calculate sum and mean, make mean droppable. 
accumulator_set< double, features< tag::sum, droppable<tag::mean> > > acc;

// add some data
acc(1.0);
acc(2.0);

// drop the mean. mean's reference count
// drops to 0, so it's really dropped. So
// too, count's reference count drops to 0
// and is really dropped.
acc.drop<tag::mean>();

// add more data. Sum continues to accumulate!
acc(3.0);

// This will display "6 2 3"
std::cout << sum(acc) << ' '
          << count(acc) << ' '
          << mean(acc);

Note that at the point at which mean is dropped, sum is 3, count is 2, and therefore mean is 1.5. But since sum continues to accumulate even after mean has been dropped, the value of mean continues to change. If you want to remember the value of mean at the point it is dropped, you should save its value into a local variable.

The following rules more precisely specify how droppable and non-droppable accumulators behave within an accumulator set.

• There are two types of accumulators: droppable and non-droppable. The default is non-droppable.
• For any feature X, both X and droppable<X> satisfy the X dependency.
• If feature X depends on Y and Z, then droppable<X> depends on droppable<Y> and droppable<Z>.
• All accumulators have add_ref() and drop() member functions.
• For non-droppable accumulators, drop() is a no-op, and add_ref() invokes add_ref() on all accumulators corresponding to the features upon which the current accumulator depends.
• Droppable accumulators have a reference count and define add_ref() and drop() to manipulate the reference count.
• For droppable accumulators, add_ref() increments the accumulator's reference count, and also add_ref()'s the accumulators corresponding to the features upon which the current accumulator depends.
• For droppable accumulators, drop() decrements the accumulator's reference count, and also drop()'s the accumulators corresponding to the features upon which the current accumulator depends.
• The accumulator_set constructor walks the list of user-specified features and add_ref()'s the accumulator that corresponds to each of them. (Note: that means that an accumulator that is not user-specified but in the set merely to satisfy a dependency will be dropped as soon as all its dependencies have been dropped. Ones that have been user specified are not dropped until their dependencies have been dropped and the user has explicitly dropped the accumulator.)
• Droppable accumulators check their reference count in their accumulate member function. If the reference count is 0, the function is a no-op.
• Users are not allowed to drop a feature that is not user-specified and marked as droppable.

And as an optimization:

• If the user specifies the non-droppable feature X, which depends on Y and Z, then the accumulators for Y and Z can be safely made non-droppable, as well as any accumulators on which they depend.

namespace boost { namespace accumulators { namespace tag {

struct mean                         // Features should inherit from
  : depends_on< count, sum >        // depends_on<> to specify dependencies
{
    // Define a nested typedef called 'impl' that specifies which
    // accumulator implements this feature. 
    typedef accumulators::impl::mean_accumulator< mpl::_1 > impl;
};

}}}

// An MPL lambda expression that always evaluates to
// foo_accumulator:
typedef mpl::always< foo_accumulator > impl;

// Same as 'typedef mpl::always< foo_accumulator > impl;'
struct impl
{
    template< typename Sample, typename Weight >
    struct apply
    {
        typedef foo_accumulator type;
    };
};

namespace boost {
namespace accumulators {                // By convention, we put extractors
namespace extract {                     // in the 'extract' namespace

extractor< tag::mean > const mean = {}; // Simply define our extractor with
                                        // our feature tag, like this.
}
using extract::mean;                    // Pull the extractor into the
                                        // enclosing namespace.
}}

// An accumulator set for calculating the N-th moment, for N == 2 ...
accumulator_set< double, features< tag::moment<2> > > acc;

// ... add some data ...

// Display the 2nd moment ...
std::cout << "2nd moment is " << accumulators::moment<2>(acc) << std::endl;

namespace boost {
namespace accumulators {                // By convention, we put extractors
namespace extract {                     // in the 'extract' namespace

template<int N, typename AccumulatorSet>
typename mpl::apply<AccumulatorSet, tag::moment<N> >::type::result_type
moment(AccumulatorSet const &acc)
{
    return extract_result<tag::moment<N> >(acc);
}

}
using extract::moment;                  // Pull the extractor into the
                                        // enclosing namespace.
}}

namespace boost { namespace accumulators
{
    // For the purposes of feature-based dependency resolution,
    // fast_fubar provides the same feature as fubar
    template<>
    struct feature_of<tag::fast_fubar>
      : feature_of<tag::fubar>
    {
    };
}}

namespace boost { namespace accumulators
{
    struct fast {};     // OK to leave these tags empty
    struct accurate {};

    template<>
    struct as_feature<tag::fubar(accurate)>
    {
        typedef tag::fubar type;
    };

    template<>
    struct as_feature<tag::fubar(fast)>
    {
        typedef tag::fast_fubar type;
    };
}}

namespace boost { namespace numeric { namespace functional
{
    // Metafunction for looking up the tag associated with
    // a given numeric type T.
    template<typename T>
    struct tag
    {
        // by default, all types have void as a tag type
        typedef void type;
    };

    // Forward declaration looks up the tag types of each operand
    template<
        typename Left
      , typename Right
      , typename LeftTag = typename tag<Left>::type
      , typename RightTag = typename tag<Right>::type
    >
    struct fdiv;
}}}

namespace boost { namespace numeric { namespace functional
{
    // Tag type for MyDouble
    struct MyDoubleTag {};

    // Specialize tag<> for MyDouble.
    // This only needs to be done once.
    template<>
    struct tag<MyDouble>
    {
        typedef MyDoubleTag type;
    };

    // Specify how to divide a MyDouble by an integral count
    template<typename Left, typename Right>
    struct fdiv<Left, Right, MyDoubleTag, void>
    {
        // Define the type of the result
        typedef ... result_type;

        result_type operator()(Left & left, Right & right) const
        {
            return ...;
        }
    };
}}}

Accumulator Concept

In the following table, Acc is the type of an accumulator, acc and acc2 are objects of type Acc, and args is the name of an argument pack from the Boost.Parameter library.

Feature Concept

In the following table, F is the type of a feature and S is some scalar type.

The count feature is a simple counter that tracks the number of samples pushed into the accumulator set.

Header

#include <boost/accumulators/statistics/count.hpp>

Example

accumulator_set<int, features<tag::count> > acc;
acc(0);
acc(0);
acc(0);
assert(3 == count(acc));

See also

The covariance feature is an iterative Monte Carlo estimator for the covariance. It is specified as tag::covariance<variate-type, variate-tag>.

Headers

#include <boost/accumulators/statistics/covariance.hpp>
#include <boost/accumulators/statistics/variates/covariate.hpp>

Example

accumulator_set<double, stats<tag::covariance<double, tag::covariate1> > > acc;
acc(1., covariate1 = 2.);
acc(1., covariate1 = 4.);
acc(2., covariate1 = 3.);
acc(6., covariate1 = 1.);
assert(covariance(acc) == -1.75);

See also

The tag::density feature returns a histogram of the sample distribution. For more implementation details, see density_impl.

Header

#include <boost/accumulators/statistics/density.hpp>

Note

Results from the density accumulator can only be extracted after the number of samples meets or exceeds the cache size.

See also

The error_of<mean> feature calculates the error of the mean feature. It is equal to sqrt(variance / (count - 1)).

Header

#include <boost/accumulators/statistics/error_of.hpp>
#include <boost/accumulators/statistics/error_of_mean.hpp>

Example

accumulator_set<double, stats<tag::error_of<tag::mean> > > acc;
acc(1.1);
acc(1.2);
acc(1.3);
assert(0.057735 == error_of<tag::mean>(acc));

See also

Multiple quantile estimation with the extended P^2 algorithm. For further details, see extended_p_square_impl.

Header

#include <boost/accumulators/statistics/extended_p_square.hpp>

Example

boost::array<double> probs = {0.001,0.01,0.1,0.25,0.5,0.75,0.9,0.99,0.999};
accumulator_set<double, stats<tag::extended_p_square> >
    acc(tag::extended_p_square::probabilities = probs);

boost::lagged_fibonacci607 rng; // a random number generator
for (int i=0; i<10000; ++i)
    acc(rng());

BOOST_CHECK_CLOSE(extended_p_square(acc)[0], probs[0], 25);
BOOST_CHECK_CLOSE(extended_p_square(acc)[1], probs[1], 10);
BOOST_CHECK_CLOSE(extended_p_square(acc)[2], probs[2], 5);

for (std::size_t i=3; i < probs.size(); ++i)
{
    BOOST_CHECK_CLOSE(extended_p_square(acc)[i], probs[i], 2);
}

See also

Quantile estimation using the extended P^2 algorithm for weighted and unweighted samples. By default, the calculation is linear and unweighted, but quadratic and weighted variants are also provided. For further implementation details, see extended_p_square_quantile_impl.

All the variants share the tag::quantile feature and can be extracted using the quantile() extractor.

Header

#include <boost/accumulators/statistics/extended_p_square_quantile.hpp>

Example

typedef accumulator_set<double, stats<tag::extended_p_square_quantile> >
    accumulator_t;
typedef accumulator_set<double, stats<tag::weighted_extended_p_square_quantile>, double >
    accumulator_t_weighted;
typedef accumulator_set<double, stats<tag::extended_p_square_quantile(quadratic)> >
    accumulator_t_quadratic;
typedef accumulator_set<double, stats<tag::weighted_extended_p_square_quantile(quadratic)>, double >
    accumulator_t_weighted_quadratic;

// tolerance
double epsilon = 1;

// a random number generator
boost::lagged_fibonacci607 rng;

boost::array<double> probs = { 0.990, 0.991, 0.992, 0.993, 0.994,
                               0.995, 0.996, 0.997, 0.998, 0.999 };
accumulator_t acc(extended_p_square_probabilities = probs);
accumulator_t_weighted acc_weighted(extended_p_square_probabilities = probs);
accumulator_t_quadratic acc2(extended_p_square_probabilities = probs);
accumulator_t_weighted_quadratic acc_weighted2(extended_p_square_probabilities = probs);

for (int i=0; i<10000; ++i)
{
    double sample = rng();
    acc(sample);
    acc2(sample);
    acc_weighted(sample, weight = 1.);
    acc_weighted2(sample, weight = 1.);
}

for (std::size_t i = 0; i < probs.size() - 1; ++i)
{
    BOOST_CHECK_CLOSE(
        quantile(acc, quantile_probability = 0.99025 + i*0.001)
      , 0.99025 + i*0.001
      , epsilon
    );
    BOOST_CHECK_CLOSE(
        quantile(acc2, quantile_probability = 0.99025 + i*0.001)
      , 0.99025 + i*0.001
      , epsilon
    );
    BOOST_CHECK_CLOSE(
        quantile(acc_weighted, quantile_probability = 0.99025 + i*0.001)
      , 0.99025 + i*0.001
      , epsilon
    );
    BOOST_CHECK_CLOSE(
        quantile(acc_weighted2, quantile_probability = 0.99025 + i*0.001)
      , 0.99025 + i*0.001
      , epsilon
    );
}

See also

The kurtosis of a sample distribution is defined as the ratio of the 4th central moment and the square of the 2nd central moment (the variance) of the samples, minus 3. The term -3 is added in order to ensure that the normal distribution has zero kurtosis. For more implementation details, see kurtosis_impl

Header

#include <boost/accumulators/statistics/kurtosis.hpp>

Example

accumulator_set<int, stats<tag::kurtosis > > acc;

acc(2);
acc(7);
acc(4);
acc(9);
acc(3);

BOOST_CHECK_EQUAL( mean(acc), 5 );
BOOST_CHECK_EQUAL( accumulators::moment<2>(acc), 159./5. );
BOOST_CHECK_EQUAL( accumulators::moment<3>(acc), 1171./5. );
BOOST_CHECK_EQUAL( accumulators::moment<4>(acc), 1863 );
BOOST_CHECK_CLOSE( kurtosis(acc), -1.39965397924, 1e-6 );

See also

Calculates the maximum value of all the samples.

Header

#include <boost/accumulators/statistics/max.hpp>

Example

accumulator_set<int, stats<tag::max> > acc;

acc(1);
BOOST_CHECK_EQUAL(1, (max)(acc));

acc(0);
BOOST_CHECK_EQUAL(1, (max)(acc));

acc(2);
BOOST_CHECK_EQUAL(2, (max)(acc));

See also

Calculates the mean of samples, weights or variates. The calculation is either lazy (in the result extractor), or immediate (in the accumulator). The lazy implementation is the default. For more implementation details, see mean_impl or. immediate_mean_impl

Header

#include <boost/accumulators/statistics/mean.hpp>

Example

accumulator_set<
    int
  , stats<
        tag::mean
      , tag::mean_of_weights
      , tag::mean_of_variates<int, tag::covariate1>
    >
  , int
> acc;

acc(1, weight = 2, covariate1 = 3);
BOOST_CHECK_CLOSE(1., mean(acc), 1e-5);
BOOST_CHECK_EQUAL(1u, count(acc));
BOOST_CHECK_EQUAL(2, sum(acc));
BOOST_CHECK_CLOSE(2., mean_of_weights(acc), 1e-5);
BOOST_CHECK_CLOSE(3., (accumulators::mean_of_variates<int, tag::covariate1>(acc)), 1e-5);

acc(0, weight = 4, covariate1 = 4);
BOOST_CHECK_CLOSE(0.33333333333333333, mean(acc), 1e-5);
BOOST_CHECK_EQUAL(2u, count(acc));
BOOST_CHECK_EQUAL(2, sum(acc));
BOOST_CHECK_CLOSE(3., mean_of_weights(acc), 1e-5);
BOOST_CHECK_CLOSE(3.5, (accumulators::mean_of_variates<int, tag::covariate1>(acc)), 1e-5);

acc(2, weight = 9, covariate1 = 8);
BOOST_CHECK_CLOSE(1.33333333333333333, mean(acc), 1e-5);
BOOST_CHECK_EQUAL(3u, count(acc));
BOOST_CHECK_EQUAL(20, sum(acc));
BOOST_CHECK_CLOSE(5., mean_of_weights(acc), 1e-5);
BOOST_CHECK_CLOSE(5., (accumulators::mean_of_variates<int, tag::covariate1>(acc)), 1e-5);

accumulator_set<
    int
  , stats<
        tag::mean(immediate)
      , tag::mean_of_weights(immediate)
      , tag::mean_of_variates<int, tag::covariate1>(immediate)
    >
  , int
> acc2;

acc2(1, weight = 2, covariate1 = 3);
BOOST_CHECK_CLOSE(1., mean(acc2), 1e-5);
BOOST_CHECK_EQUAL(1u, count(acc2));
BOOST_CHECK_CLOSE(2., mean_of_weights(acc2), 1e-5);
BOOST_CHECK_CLOSE(3., (accumulators::mean_of_variates<int, tag::covariate1>(acc2)), 1e-5);

acc2(0, weight = 4, covariate1 = 4);
BOOST_CHECK_CLOSE(0.33333333333333333, mean(acc2), 1e-5);
BOOST_CHECK_EQUAL(2u, count(acc2));
BOOST_CHECK_CLOSE(3., mean_of_weights(acc2), 1e-5);
BOOST_CHECK_CLOSE(3.5, (accumulators::mean_of_variates<int, tag::covariate1>(acc2)), 1e-5);

acc2(2, weight = 9, covariate1 = 8);
BOOST_CHECK_CLOSE(1.33333333333333333, mean(acc2), 1e-5);
BOOST_CHECK_EQUAL(3u, count(acc2));
BOOST_CHECK_CLOSE(5., mean_of_weights(acc2), 1e-5);
BOOST_CHECK_CLOSE(5., (accumulators::mean_of_variates<int, tag::covariate1>(acc2)), 1e-5);

See also

Median estimation based on the P^2 quantile estimator, the density estimator, or the P^2 cumulative distribution estimator. For more implementation details, see median_impl, with_density_median_impl, and with_p_square_cumulative_distribution_median_impl.

The three median accumulators all satisfy the tag::median feature, and can all be extracted with the median() extractor.

Header

#include <boost/accumulators/statistics/median.hpp>

Example

// two random number generators
double mu = 1.;
boost::lagged_fibonacci607 rng;
boost::normal_distribution<> mean_sigma(mu,1);
boost::variate_generator<boost::lagged_fibonacci607&, boost::normal_distribution<> >
    normal(rng, mean_sigma);

accumulator_set<double, stats<tag::median(with_p_square_quantile) > > acc;
accumulator_set<double, stats<tag::median(with_density) > >
    acc_dens( density_cache_size = 10000, density_num_bins = 1000 );
accumulator_set<double, stats<tag::median(with_p_square_cumulative_distribution) > >
    acc_cdist( p_square_cumulative_distribution_num_cells = 100 );

for (std::size_t i=0; i<100000; ++i)
{
    double sample = normal();
    acc(sample);
    acc_dens(sample);
    acc_cdist(sample);
}

BOOST_CHECK_CLOSE(1., median(acc), 1.);
BOOST_CHECK_CLOSE(1., median(acc_dens), 1.);
BOOST_CHECK_CLOSE(1., median(acc_cdist), 3.);

See also

Calculates the minimum value of all the samples.

Header

#include <boost/accumulators/statistics/min.hpp>

Example

accumulator_set<int, stats<tag::min> > acc;

acc(1);
BOOST_CHECK_EQUAL(1, (min)(acc));

acc(0);
BOOST_CHECK_EQUAL(0, (min)(acc));

acc(2);
BOOST_CHECK_EQUAL(0, (min)(acc));

See also

Calculates the N-th moment of the samples, which is defined as the sum of the N-th power of the samples over the count of samples.

Header

#include <boost/accumulators/statistics/moment.hpp>

Example

accumulator_set<int, stats<tag::moment<2> > > acc1;

acc1(2); //    4
acc1(4); //   16
acc1(5); // + 25
         // = 45 / 3 = 15

BOOST_CHECK_CLOSE(15., accumulators::moment<2>(acc1), 1e-5);

accumulator_set<int, stats<tag::moment<5> > > acc2;

acc2(2); //     32
acc2(3); //    243
acc2(4); //   1024
acc2(5); // + 3125
         // = 4424 / 4 = 1106

BOOST_CHECK_CLOSE(1106., accumulators::moment<5>(acc2), 1e-5);

See also

Histogram calculation of the cumulative distribution with the P^2 algorithm. For more implementation details, see p_square_cumulative_distribution_impl

Header

#include <boost/accumulators/statistics/p_square_cumul_dist.hpp>

Example

// tolerance in %
double epsilon = 3;

typedef accumulator_set<double, stats<tag::p_square_cumulative_distribution> > accumulator_t;

accumulator_t acc(tag::p_square_cumulative_distribution::num_cells = 100);

// two random number generators
boost::lagged_fibonacci607 rng;
boost::normal_distribution<> mean_sigma(0,1);
boost::variate_generator<boost::lagged_fibonacci607&, boost::normal_distribution<> > normal(rng, mean_sigma);

for (std::size_t i=0; i<100000; ++i)
{
    acc(normal());
}

typedef iterator_range<std::vector<std::pair<double, double> >::iterator > histogram_type;
histogram_type histogram = p_square_cumulative_distribution(acc);

for (std::size_t i = 0; i < histogram.size(); ++i)
{
    // problem with small results: epsilon is relative (in percent), not absolute!
    if ( histogram[i].second > 0.001 )
        BOOST_CHECK_CLOSE( 0.5 * (1.0 + erf( histogram[i].first / sqrt(2.0) )), histogram[i].second, epsilon );
}

See also

Single quantile estimation with the P^2 algorithm. For more implementation details, see p_square_quantile_impl

Header

#include <boost/accumulators/statistics/p_square_quantile.hpp>

Example

typedef accumulator_set<double, stats<tag::p_square_quantile> > accumulator_t;

// tolerance in %
double epsilon = 1;

// a random number generator
boost::lagged_fibonacci607 rng;

accumulator_t acc0(quantile_probability = 0.001);
accumulator_t acc1(quantile_probability = 0.01 );
accumulator_t acc2(quantile_probability = 0.1  );
accumulator_t acc3(quantile_probability = 0.25 );
accumulator_t acc4(quantile_probability = 0.5  );
accumulator_t acc5(quantile_probability = 0.75 );
accumulator_t acc6(quantile_probability = 0.9  );
accumulator_t acc7(quantile_probability = 0.99 );
accumulator_t acc8(quantile_probability = 0.999);

for (int i=0; i<100000; ++i)
{
    double sample = rng();
    acc0(sample);
    acc1(sample);
    acc2(sample);
    acc3(sample);
    acc4(sample);
    acc5(sample);
    acc6(sample);
    acc7(sample);
    acc8(sample);
}

BOOST_CHECK_CLOSE( p_square_quantile(acc0), 0.001, 15*epsilon );
BOOST_CHECK_CLOSE( p_square_quantile(acc1), 0.01 , 5*epsilon );
BOOST_CHECK_CLOSE( p_square_quantile(acc2), 0.1  , epsilon );
BOOST_CHECK_CLOSE( p_square_quantile(acc3), 0.25 , epsilon );
BOOST_CHECK_CLOSE( p_square_quantile(acc4), 0.5  , epsilon );
BOOST_CHECK_CLOSE( p_square_quantile(acc5), 0.75 , epsilon );
BOOST_CHECK_CLOSE( p_square_quantile(acc6), 0.9  , epsilon );
BOOST_CHECK_CLOSE( p_square_quantile(acc7), 0.99 , epsilon );
BOOST_CHECK_CLOSE( p_square_quantile(acc8), 0.999, epsilon );

See also

Peaks Over Threshold method for quantile and tail mean estimation. For implementation details, see peaks_over_threshold_impl and peaks_over_threshold_prob_impl.

Both tag::peaks_over_threshold and tag::peaks_over_threshold_prob<> satisfy the tag::abstract_peaks_over_threshold feature, and can be extracted with the peaks_over_threshold() extractor. The result is a 3-tuple representing the fit parameters u_bar, beta_bar and xi_hat.

Header

#include <boost/accumulators/statistics/peaks_over_threshold.hpp>

Example

See example for pot_quantile.

See also

Quantile estimation based on Peaks over Threshold method (for both left and right tails). For implementation details, see pot_quantile_impl.

Both tag::pot_quantile<left-or-right> and tag::pot_quantile_prob<left-or-right> satisfy the tag::quantile feature and can be extracted using the quantile() extractor.

Header

#include <boost/accumulators/statistics/pot_quantile.hpp>

Example

// tolerance in %
double epsilon = 1.;

double alpha = 0.999;
double threshold_probability = 0.99;
double threshold = 3.;

// two random number generators
boost::lagged_fibonacci607 rng;
boost::normal_distribution<> mean_sigma(0,1);
boost::exponential_distribution<> lambda(1);
boost::variate_generator<boost::lagged_fibonacci607&, boost::normal_distribution<> > normal(rng, mean_sigma);
boost::variate_generator<boost::lagged_fibonacci607&, boost::exponential_distribution<> > exponential(rng, lambda);

accumulator_set<double, stats<tag::pot_quantile<right>(with_threshold_value)> > acc1(
    tag::peaks_over_threshold::threshold_value = threshold
);
accumulator_set<double, stats<tag::pot_quantile<right>(with_threshold_probability)> > acc2(
    tag::tail<right>::cache_size = 2000
  , tag::peaks_over_threshold_prob::threshold_probability = threshold_probability
);

threshold_probability = 0.995;
threshold = 5.;

accumulator_set<double, stats<tag::pot_quantile<right>(with_threshold_value)> > acc3(
    tag::peaks_over_threshold::threshold_value = threshold
);
accumulator_set<double, stats<tag::pot_quantile<right>(with_threshold_probability)> > acc4(
    tag::tail<right>::cache_size = 2000
  , tag::peaks_over_threshold_prob::threshold_probability = threshold_probability
);

for (std::size_t i = 0; i < 100000; ++i)
{
    double sample = normal();
    acc1(sample);
    acc2(sample);
}

for (std::size_t i = 0; i < 100000; ++i)
{
    double sample = exponential();
    acc3(sample);
    acc4(sample);
}

BOOST_CHECK_CLOSE( quantile(acc1, quantile_probability = alpha), 3.090232, epsilon );
BOOST_CHECK_CLOSE( quantile(acc2, quantile_probability = alpha), 3.090232, epsilon );

BOOST_CHECK_CLOSE( quantile(acc3, quantile_probability = alpha), 6.908, epsilon );
BOOST_CHECK_CLOSE( quantile(acc4, quantile_probability = alpha), 6.908, epsilon );

See also

Estimation of the (coherent) tail mean based on the peaks over threshold method (for both left and right tails). For implementation details, see pot_tail_mean_impl.

Both tag::pot_tail_mean<left-or-right> and tag::pot_tail_mean_prob<left-or-right> satisfy the tag::tail_mean feature and can be extracted using the tail_mean() extractor.

Header

#include <boost/accumulators/statistics/pot_tail_mean.hpp>

Example

// TODO

See also

The rolling count is the current number of elements in the rolling window.

Header

#include <boost/accumulators/statistics/rolling_count.hpp>

Example

accumulator_set<int, stats<tag::rolling_count> > acc(tag::rolling_window::window_size = 3);

BOOST_CHECK_EQUAL(0u, rolling_count(acc));

acc(1);
BOOST_CHECK_EQUAL(1u, rolling_count(acc));

acc(1);
BOOST_CHECK_EQUAL(2u, rolling_count(acc));

acc(1);
BOOST_CHECK_EQUAL(3u, rolling_count(acc));

acc(1);
BOOST_CHECK_EQUAL(3u, rolling_count(acc));

acc(1);
BOOST_CHECK_EQUAL(3u, rolling_count(acc));

See also

The rolling sum is the sum of the last N samples.

Header

#include <boost/accumulators/statistics/rolling_sum.hpp>

Example

accumulator_set<int, stats<tag::rolling_sum> > acc(tag::rolling_window::window_size = 3);

BOOST_CHECK_EQUAL(0, rolling_sum(acc));

acc(1);
BOOST_CHECK_EQUAL(1, rolling_sum(acc));

acc(2);
BOOST_CHECK_EQUAL(3, rolling_sum(acc));

acc(3);
BOOST_CHECK_EQUAL(6, rolling_sum(acc));

acc(4);
BOOST_CHECK_EQUAL(9, rolling_sum(acc));

acc(5);
BOOST_CHECK_EQUAL(12, rolling_sum(acc));