accumulators.qbk

来自「Boost provides free peer-reviewed portab」· QBK 代码 · 共 1,514 行 · 第 1/5 页

[library Boost.Accumulators
    [quickbook 1.3]
    [authors [Niebler, Eric]]
    [copyright 2005 2006 Eric Niebler]
    [category math]
    [id accumulators]
    [dirname accumulators]
    [purpose 
        Incremental accumulation framework and statistical accumulator library.
    ]
    [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        [@http://www.boost.org/LICENSE_1_0.txt])
    ]
]

[/  Images   ]

[def _note_                  [$images/note.png]]
[def _alert_                 [$images/caution.png]]
[def _detail_                [$images/note.png]]
[def _tip_                   [$images/tip.png]]

[/  Links   ]

[def _sample_type_           '''<replaceable>sample-type</replaceable>''']
[def _weight_type_           '''<replaceable>weight-type</replaceable>''']
[def _variate_type_          '''<replaceable>variate-type</replaceable>''']
[def _variate_tag_           '''<replaceable>variate-tag</replaceable>''']
[def _left_or_right_         '''<replaceable>left-or-right</replaceable>''']
[def _implementation_defined_ '''<replaceable>implementation-defined</replaceable>''']
[def _boost_                 [@http://www.boost.org Boost]]
[def _mpl_                   [@../../libs/mpl/index.html MPL]]
[def _mpl_lambda_expression_ [@../../libs/mpl/doc/refmanual/lambda-expression.html MPL Lambda Expression]]
[def _parameter_             [@../../libs/parameter/index.html Boost.Parameter]]
[def _accumulator_set_       [classref boost::accumulators::accumulator_set `accumulator_set<>`]]
[def _accumulator_base_      [classref boost::accumulators::accumulator_base `accumulator_base`]]
[def _depends_on_            [classref boost::accumulators::depends_on `depends_on<>`]]
[def _feature_of_            [classref boost::accumulators::feature_of `feature_of<>`]]
[def _as_feature_            [classref boost::accumulators::as_feature `as_feature<>`]]
[def _features_              [classref boost::accumulators::features `features<>`]]
[def _external_              [classref boost::accumulators::external `external<>`]]
[def _droppable_             [classref boost::accumulators::droppable `droppable<>`]]
[def _droppable_accumulator_ [classref boost::accumulators::droppable_accumulator `droppable_accumulator<>`]]
[def _extractor_             [classref boost::accumulators::tag::extractor `extractor<>`]]
[def _tail_                  [classref boost::accumulators::tag::tail `tail`]]
[def _tail_variate_          [classref boost::accumulators::tag::tail_variate `tail_variate<>`]]
[def _extract_result_        [funcref boost::accumulators::extract_result `extract_result()`]]
[def _ZKB_                   [@http://www.zkb.com Z'''&uuml;'''rcher Kantonalbank]]

[section Preface]

[:["It is better to be approximately right than exactly wrong.]\n['-- Old adage]]

[h2 Description]

Boost.Accumulators is both a library for incremental statistical computation as
well as an extensible framework for incremental calculation in general. The library
deals primarily with the concept of an ['accumulator], which is a primitive
computational entity that accepts data one sample at a time and maintains some 
internal state. These accumulators may offload some of their computations on other
accumulators, on which they depend. Accumulators are grouped within an ['accumulator
set]. Boost.Accumulators resolves the inter-dependencies between accumulators in a
set and ensures that accumulators are processed in the proper order.

[endsect]

[section User's Guide]

This section describes how to use the Boost.Accumulators framework to create new
accumulators and how to use the existing statistical accumulators to perform incremental
statistical computation. For detailed information regarding specific components in
Boost.Accumulators, check the [link accumulators_framework_reference Reference] section.

[h2 Hello, World!]

Below is a complete example of how to use the Accumulators Framework and the 
Statistical Accumulators to perform an incremental statistical calculation. It
calculates the mean and 2nd moment of a sequence of doubles.

    #include <iostream>
    #include <boost/accumulators/accumulators.hpp>
    #include <boost/accumulators/statistics/stats.hpp>
    #include <boost/accumulators/statistics/mean.hpp>
    #include <boost/accumulators/statistics/moment.hpp>
    using namespace boost::accumulators;

    int main()
    {
        // Define an accumulator set for calculating the mean and the
        // 2nd moment ...
        accumulator_set<double, stats<tag::mean, tag::moment<2> > > acc;

        // push in some data ...
        acc(1.2);
        acc(2.3);
        acc(3.4);
        acc(4.5);

        // Display the results ...
        std::cout << "Mean:   " << mean(acc) << std::endl;
        std::cout << "Moment: " << moment<2>(acc) << std::endl;

        return 0;
    }

This program displays the following:

[pre
Mean:   2.85
Moment: 9.635
]

[section The Accumulators Framework]

The Accumulators Framework is framework for performing incremental calculations. Usage
of the framework follows the following pattern:

* Users build a computational object, called an ['_accumulator_set_], by selecting
  the computations in which they are interested, or authoring their own computational
  primitives which fit within the framework.
* Users push data into the _accumulator_set_ object one sample at a time.
* The _accumulator_set_ computes the requested quantities in the most efficient method
  possible, resolving dependencies between requested calculations, possibly cacheing
  intermediate results.

The Accumulators Framework defines the utilities needed for defining primitive
computational elements, called ['accumulators]. It also provides the _accumulator_set_
type, described above.

[h2 Terminology]

The following terms are used in the rest of the documentation.

[variablelist
    [[Sample]          [[#sample_type] A datum that is pushed into an _accumulator_set_.
                        The type of the sample is the ['sample type].]]
    [[Weight]          [[#weight_type] An optional scalar value passed along with the
                        sample specifying the weight of the sample. Conceptually, each
                        sample is multiplied with its weight. The type of the weight is
                        the ['weight type].]]
    [[Feature]         [An abstract primitive computational entity. When defining an
                        _accumulator_set_, users specify the features in which they are
                        interested, and the _accumulator_set_ figures out which
                        ['accumulators] would best provide those features. Features may
                        depend on other features. If they do, the accumulator set figures
                        out which accumulators to add to satisfy the dependencies.]]
    [[Accumulator]     [A concrete primitive computational entity. An accumulator is a
                        concrete implementation of a feature. It satisfies exactly one
                        abstract feature. Several different accumulators may provide the
                        same feature, but may represent different implementation strategies.]]
    [[Accumulator Set] [A collection of accumulators. An accumulator set is specified with
                        a sample type and a list of features. The accumulator set uses this
                        information to generate an ordered set of accumulators depending on
                        the feature dependency graph. An accumulator set accepts samples one
                        datum at a time, propogating them to each accumulator in order. At any
                        point, results can be extracted from the accumulator set.]]
    [[Extractor]       [A function or function object that can be used to extract a result
                        from an _accumulator_set_.]]
]

[h2 Overview]

Here is a list of the important types and functions in the Accumulator Framework and
a brief description of each.

[table Accumulators Toolbox
    [[Tool]              [Description]]
    [[_accumulator_set_] [This is the most important type in the Accumulators Framework.
                          It is a collection of accumulators. A datum pushed into an 
                          _accumulator_set_ is forwarded to each accumulator, in an order
                          determined by the dependency relationships between the
                          accumulators. Computational results can be extracted from an
                          accumulator at any time.]]
    [[_depends_on_     ] [Used to specify which other features a feature depends on.]]
    [[_feature_of_     ] [Trait used to tell the Accumulators Framework that, for the purpose
                          of feature-based dependency resolution, one feature should be
                          treated the same as another.]]
    [[_as_feature_     ] [Used to create an alias for a feature. For example, if there are
                          two features, fast_X and accurate_X, they can be mapped to
                          X(fast) and X(accurate) with _as_feature_. This is just syntactic
                          sugar.]]
    [[_features_       ] [An _mpl_ sequence. We can use _features_ as the second template
                          parameter when declaring an _accumulator_set_.]]
    [[_external_       ] [Used when declaring an _accumulator_set_. If the weight type is
                          specified with _external_, then the weight accumulators are
                          assumed to reside in a separate accumulator set which will be passed
                          in with a named parameter.]]
    [[_extractor_      ] [A class template useful for creating an extractor function object.
                          It is parameterized on a feature, and it has member functions for
                          extracting from an _accumulator_set_ the result corresponding to
                          that feature.]]
]

[section Using [^accumulator_set<>]]

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:

[variablelist
    [[`Sample`]     [The type of the data that will be accumulated.]]
    [[`Features`]   [An _mpl_ sequence of features to be calculated.]]
    [[`Weight`]     [The type of the (optional) weight paramter.]]
]

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>]]

[endsect]

[section Extracting Results]

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 )