boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>User's Guide</title> <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> <link rel="up" href="../accumulators.html" title="Chapter 1. Boost.Accumulators"> <link rel="prev" href="../accumulators.html" title="Chapter 1. Boost.Accumulators"> <link rel="next" href="acknowledgements.html" title="Acknowledgements"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> <td align="center"><a href="../../../index.html">Home</a></td> <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"> <a accesskey="p" href="../accumulators.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../accumulators.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="accumulators.user_s_guide"></a><a class="link" href="user_s_guide.html" title="User's Guide">User's Guide</a> </h2></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework">The Accumulators Framework</a></dt> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_statistical_accumulators_library">The Statistical Accumulators Library</a></dt> </dl></div> 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 <a class="link" href="reference.html#accumulators_framework_reference" title="Accumulators Framework Reference">Reference</a> section. <h3> <a name="accumulators.user_s_guide.h0"></a> <a name="accumulators.user_s_guide.hello__world_"></a><a class="link" href="user_s_guide.html#accumulators.user_s_guide.hello__world_">Hello, World!</a> </h3> 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. <pre class="programlisting">#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: " << accumulators::moment<2>(acc) << std::endl; return 0; } </pre> This program displays the following: <pre class="programlisting">Mean: 2.85 Moment: 9.635 </pre> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="accumulators.user_s_guide.the_accumulators_framework"></a><a class="link" href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework" title="The Accumulators Framework">The Accumulators Framework</a> </h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.using___accumulator_set___">Using <code class="literal">accumulator_set<></code></a></dt> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.extracting_results">Extracting Results</a></dt> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.passing_optional_parameters">Passing Optional Parameters</a></dt> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.weighted_samples">Weighted Samples</a></dt> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.numeric_operators_sub_library">Numeric Operators Sub-Library</a></dt> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.extending_the_accumulators_framework">Extending the Accumulators Framework</a></dt> <dt><a href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.concepts">Concepts</a></dt> </dl></div> The Accumulators Framework is framework for performing incremental calculations. Usage of the framework follows the following pattern: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> Users build a computational object, called an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>, by selecting the computations in which they are interested, or authoring their own computational primitives which fit within the framework. </li> <li class="listitem"> Users push data into the <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> object one sample at a time. </li> <li class="listitem"> The <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> computes the requested quantities in the most efficient method possible, resolving dependencies between requested calculations, possibly caching intermediate results. </li> </ul></div> The Accumulators Framework defines the utilities needed for defining primitive computational elements, called accumulators. It also provides the <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> type, described above. <h3> <a name="accumulators.user_s_guide.the_accumulators_framework.h0"></a> <a name="accumulators.user_s_guide.the_accumulators_framework.terminology"></a><a class="link" href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.terminology">Terminology</a> </h3> The following terms are used in the rest of the documentation. <div class="variablelist"> <dl class="variablelist"> <dt>Sample</dt> <dd> <a name="sample_type"></a>A datum that is pushed into an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>. The type of the sample is the sample type. </dd> <dt>Weight</dt> <dd> <a name="weight_type"></a>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. </dd> <dt>Feature</dt> <dd> An abstract primitive computational entity. When defining an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>, users specify the features in which they are interested, and the <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> 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. </dd> <dt>Accumulator</dt> <dd> 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. </dd> <dt>Accumulator Set</dt> <dd> 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, propagating them to each accumulator in order. At any point, results can be extracted from the accumulator set. </dd> <dt>Extractor</dt> <dd> A function or function object that can be used to extract a result from an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>. </dd> </dl> </div> <h3> <a name="accumulators.user_s_guide.the_accumulators_framework.h1"></a> <a name="accumulators.user_s_guide.the_accumulators_framework.overview"></a><a class="link" href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.overview">Overview</a> </h3> Here is a list of the important types and functions in the Accumulator Framework and a brief description of each. <div class="table"> <a name="accumulators.user_s_guide.the_accumulators_framework.t0"></a>Table 1.1. Accumulators Toolbox <div class="table-contents"><table class="table" summary="Accumulators Toolbox"> <colgroup> <col> <col> </colgroup> <thead><tr> <th> Tool </th> <th> Description </th> </tr></thead> <tbody> <tr> <td> <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> </td> <td> This is the most important type in the Accumulators Framework. It is a collection of accumulators. A datum pushed into an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> 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. </td> </tr> <tr> <td> <code class="computeroutput"><a class="link" href="../boost/accumulators/depends_on.html" title="Struct template depends_on">depends_on<></a></code> </td> <td> Used to specify which other features a feature depends on. </td> </tr> <tr> <td> <code class="computeroutput"><a class="link" href="../boost/accumulators/feature_of.html" title="Struct template feature_of">feature_of<></a></code> </td> <td> 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. </td> </tr> <tr> <td> <code class="computeroutput"><a class="link" href="../boost/accumulators/as_feature.html" title="Struct template as_feature">as_feature<></a></code> </td> <td> 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 <code class="computeroutput"><a class="link" href="../boost/accumulators/as_feature.html" title="Struct template as_feature">as_feature<></a></code>. This is just syntactic sugar. </td> </tr> <tr> <td> <code class="computeroutput"><a class="link" href="../boost/accumulators/features.html" title="Struct template features">features<></a></code> </td> <td> An <a href="../../../libs/mpl/index.html" target="_top">MPL</a> sequence. We can use <code class="computeroutput"><a class="link" href="../boost/accumulators/features.html" title="Struct template features">features<></a></code> as the second template parameter when declaring an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>. </td> </tr> <tr> <td> <code class="computeroutput">external<></code> </td> <td> Used when declaring an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>. If the weight type is specified with <code class="computeroutput">external<></code>, then the weight accumulators are assumed to reside in a separate accumulator set which will be passed in with a named parameter. </td> </tr> <tr> <td> <code class="computeroutput">extractor<></code> </td> <td> 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 <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> the result corresponding to that feature. </td> </tr> </tbody> </table></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="accumulators.user_s_guide.the_accumulators_framework.using___accumulator_set___"></a><a class="link" href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.using___accumulator_set___" title="Using accumulator_set<>">Using <code class="literal">accumulator_set<></code></a> </h4></div></div></div> Our tour of the <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> class template begins with the forward declaration: <pre class="programlisting">template< typename Sample, typename Features, typename Weight = void > struct accumulator_set; </pre> The template parameters have the following meaning: <div class="variablelist"> <dl class="variablelist"> <dt><code class="computeroutput">Sample</code></dt> <dd> The type of the data that will be accumulated. </dd> <dt><code class="computeroutput">Features</code></dt> <dd> An <a href="../../../libs/mpl/index.html" target="_top">MPL</a> sequence of features to be calculated. </dd> <dt><code class="computeroutput">Weight</code></dt> <dd> The type of the (optional) weight paramter. </dd> </dl> </div> For example, the following line declares an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> that will accept a sequence of doubles one at a time and calculate the min and mean: <pre class="programlisting">accumulator_set< double, features< tag::min, tag::mean > > acc; </pre> Notice that we use the <code class="computeroutput"><a class="link" href="../boost/accumulators/features.html" title="Struct template features">features<></a></code> template to specify a list of features to be calculated. <code class="computeroutput"><a class="link" href="../boost/accumulators/features.html" title="Struct template features">features<></a></code> is an MPL sequence of features. <div class="note"><table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> <code class="computeroutput"><a class="link" href="../boost/accumulators/features.html" title="Struct template features">features<></a></code> is a synonym of <code class="computeroutput">mpl::vector<></code>. In fact, we could use <code class="computeroutput">mpl::vector<></code> or any MPL sequence if we prefer, and the meaning would be the same. </td></tr> </table></div> Once we have defined an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>, we can then push data into it, and it will calculate the quantities you requested, as shown below. <pre class="programlisting">// push some data into the accumulator_set ... acc(1.2); acc(2.3); acc(3.4); </pre> Since <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> defines its accumulate function to be the function call operator, we might be tempted to use an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> as a UnaryFunction to a standard algorithm such as <code class="computeroutput">std::for_each</code>. 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 <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> object. Consider the following: <pre class="programlisting">// 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 ); </pre> Notice how we must assign the return value of <code class="computeroutput">std::for_each</code> back to the <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>. This works, but some accumulators are not cheap to copy. For example, the <code class="computeroutput"><a class="link" href="../boost/accumulators/tag/tail.html" title="Struct template tail">tail</a></code> and <code class="computeroutput"><a class="link" href="../boost/accumulators/tag/tail_variate.html" title="Struct template tail_variate">tail_variate<></a></code> accumulators must store a <code class="computeroutput">std::vector<></code>, 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 <code class="computeroutput">boost::bind()</code> and <code class="computeroutput">boost::ref()</code>. See below: <pre class="programlisting">// 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 ) ); </pre> Notice now that we don't care about the return value of <code class="computeroutput">std::for_each()</code> anymore because <code class="computeroutput">std::for_each()</code> is modifying <code class="computeroutput">acc</code> directly. <div class="note"><table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> To use <code class="computeroutput">boost::bind()</code> and <code class="computeroutput">boost::ref()</code>, you must <code class="computeroutput">#include</code> <code class="literal"><boost/bind.hpp></code> and <code class="literal"><boost/ref.hpp></code> </td></tr> </table></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="accumulators.user_s_guide.the_accumulators_framework.extracting_results"></a><a class="link" href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.extracting_results" title="Extracting Results">Extracting Results</a> </h4></div></div></div> Once we have declared an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> and pushed data into it, we need to be able to extract results from it. For each feature we can add to an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code>, 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 <code class="computeroutput">tag::min</code> and <code class="computeroutput">tag::max</code> features, we can extract the results with the <code class="computeroutput">min</code> and <code class="computeroutput">max</code> extractors, as follows: <pre class="programlisting">// 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"; </pre> The extractors are all declared in the <code class="computeroutput">boost::accumulators::extract</code> namespace, but they are brought into the <code class="computeroutput">boost::accumulators</code> namespace with a <code class="computeroutput">using</code> declaration. <div class="tip"><table border="0" summary="Tip"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td> <th align="left">Tip</th> </tr> <tr><td align="left" valign="top"> On the Windows platform, <code class="computeroutput">min</code> and <code class="computeroutput">max</code> are preprocessor macros defined in <code class="literal">WinDef.h</code>. To use the <code class="computeroutput">min</code> and <code class="computeroutput">max</code> extractors, you should either compile with <code class="computeroutput">NOMINMAX</code> defined, or you should invoke the extractors like: <code class="computeroutput">(min)( acc )</code> and <code class="computeroutput">(max)( acc )</code>. The parentheses keep the macro from being invoked. </td></tr> </table></div> Another way to extract a result from an <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> is with the <code class="computeroutput">extract_result()</code> 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: <pre class="programlisting">// This displays "(-1, 2)" std::cout << '(' << extract_result< tag::min >( acc ) << ", " << extract_result< tag::max >( acc ) << ")\n"; </pre> Finally, we can define our own extractor using the <code class="computeroutput">extractor<></code> class template. For instance, another way to avoid the <code class="computeroutput">min</code> / <code class="computeroutput">max</code> macro business would be to define extractors with names that don't conflict with the macros, like this: <pre class="programlisting">extractor< tag::min > min_; extractor< tag::min > max_; // This displays "(-1, 2)" std::cout << '(' << min_( acc ) << ", " << max_( acc ) << ")\n"; </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="accumulators.user_s_guide.the_accumulators_framework.passing_optional_parameters"></a><a class="link" href="user_s_guide.html#accumulators.user_s_guide.the_accumulators_framework.passing_optional_parameters" title="Passing Optional Parameters">Passing Optional Parameters</a> </h4></div></div></div> Some accumulators need initialization parameters. In addition, perhaps some auxiliary information needs to be passed into the <code class="computeroutput"><a class="link" href="../boost/accumulators/accumulator_set.html" title="Struct template accumulator_set">accumulator_set<></a></code> along with each sample. Boost.Accumulators handles these cases with named parameters from the <a href="../../../libs/parameter/index.html" target="_top">Boost.Parameter</a> library. For example, consider the <code class="computeroutput"><a class="link" href="../boost/accumulators/tag/tail.html" title="Struct template tail">tail</a></code> and <code class="computeroutput"><a class="link" href="../boost/accumulators/tag/tail_variate.html" title="Struct template tail_variate">tail_variate<></a></code> features. <code class="computeroutput"><a class="link" href="../boost/accumulators/tag/tail.html" title="Struct template tail">tail</a></code> keeps an ordered list of the largest <code class="literal">N</code> samples, where <code class="literal">N</code> can be specified at construction time. Also, the <code class="computeroutput"><a class="link" href="../boost/accumulators/tag/tail_variate.html" title="Struct template tail_variate">tail_variate<></a></code> feature, which depends on <code class="computeroutput"><a class="link" href="../boost/accumulators/tag/tail.html" title="Struct template tail">tail</a></code>, keeps track of some data that is covariate with the <code class="literal">N</code> samples tracked by <code class="computeroutput"><a class="link" href="../boost/accumulators/tag/tail.html" title="Struct template tail">tail</a></code>. The code below shows how this all works, and is described in more detail below. <pre class="programlisting">// 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<span