Allow accumulator persistency (#18)

* Add, and update, documentation build targets.

* adding serialization to stats

* serialize rolling stats

Author: yuvalif

example/Jamfile.v2

@@ -8,4 +8,6 @@ exe example
     :
         <include>../../..
         <include>$(BOOST_ROOT)
+        <library>/boost/serialization
+        <cxxflags>"-Wno-deprecated-declarations"
     ;

example/main.cpp

@@ -6,13 +6,17 @@
 //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 #include <iostream>
+#include <fstream> // needed for de/serialization example (4)
 #include <algorithm>
 #include <boost/ref.hpp>
 #include <boost/bind.hpp>
 #include <boost/array.hpp>
 #include <boost/foreach.hpp>
 #include <boost/accumulators/accumulators.hpp>
 #include <boost/accumulators/statistics.hpp>
+// needed for de/serialization example (4)
+#include <boost/archive/text_oarchive.hpp>
+#include <boost/archive/text_iarchive.hpp>
 
 using namespace boost;
 using namespace boost::accumulators;
@@ -159,6 +163,85 @@ void example3()
     }
 }
 
+///////////////////////////////////////////////////////////////////////////////
+// example4
+//
+//  Show how accumulators could be persisted into a file, and then continued
+//  from where they were left of
+//
+void example4()
+{
+    accumulator_set<
+        double
+      , stats<tag::min, tag::mean(immediate), tag::sum, tag::moment<2>, tag::p_square_quantile, tag::kurtosis >
+    > acc(quantile_probability = 0.9);
+
+    {
+        // accumulate values from array
+        boost::array<double, 10> data = {-10., -8., -7., -6., -5., -4., -3., -2., -1., 0.};
+
+        acc = std::for_each(data.begin(), data.end(), acc);
+    }
+
+    std::cout << "  min        = " << (min)(acc) << std::endl;
+    std::cout << "  mean       = " << mean(acc) << std::endl;
+    std::cout << "  count      = " << count(acc) << std::endl;
+    std::cout << "  sum        = " << sum(acc) << std::endl;
+    std::cout << "  moment<2>  = " << accumulators::moment<2>(acc) << std::endl;
+    std::cout << "  p_square_quantile  = " << accumulators::p_square_quantile(acc) << std::endl;
+    std::cout << "  kurtosis   = " << accumulators::kurtosis(acc) << std::endl;
+
+    // save accumulator list into a file called "saved-stats"
+    const unsigned ACC_VER = 0;
+    const char* file_name = "saved-stats";
+    {
+        std::ofstream ofs(file_name);
+        boost::archive::text_oarchive oa(ofs);
+        acc.serialize(oa, ACC_VER);
+    }
+
+    // create a new accumulator set and initialize from data saved into the file
+    accumulator_set<
+        double
+      , stats<tag::min, tag::mean(immediate), tag::sum, tag::moment<2>, tag::p_square_quantile, tag::kurtosis >
+    > restored_acc(quantile_probability = 0.9);
+
+    {
+        std::ifstream ifs(file_name);
+        boost::archive::text_iarchive ia(ifs);
+        restored_acc.serialize(ia, ACC_VER);
+    }
+
+    // continue accumulating into both sets
+    {
+        // accumulate values from array
+        boost::array<double, 10> data = {10., 8., 7., 6., 5., 4., 3., 2., 1., 0.};
+
+        acc = std::for_each(data.begin(), data.end(), acc);
+        restored_acc = std::for_each(data.begin(), data.end(), restored_acc);
+    }
+
+    // validate that both return th same values
+    std::cout << std::endl << "Values in original set:" << std::endl;
+    std::cout << "  min""(acc)        = " << (min)(acc) << std::endl;
+    std::cout << "  mean(acc)       = " << mean(acc) << std::endl;
+    std::cout << "  count(acc)      = " << count(acc) << std::endl;
+    std::cout << "  sum(acc)        = " << sum(acc) << std::endl;
+    std::cout << "  moment<2>(acc)  = " << accumulators::moment<2>(acc) << std::endl;
+    std::cout << "  p_square_quantile(acc)  = " << accumulators::p_square_quantile(acc) << std::endl;
+    std::cout << "  kurtosis(acc)  = " << accumulators::kurtosis(acc) << std::endl;
+    
+    std::cout << std::endl << "Values in restored set:" << std::endl;
+    std::cout << "  min""(acc)        = " << (min)(restored_acc) << std::endl;
+    std::cout << "  mean(acc)       = " << mean(restored_acc) << std::endl;
+    std::cout << "  count(acc)      = " << count(restored_acc) << std::endl;
+    std::cout << "  sum(acc)        = " << sum(restored_acc) << std::endl;
+    std::cout << "  moment<2>(acc)  = " << accumulators::moment<2>(restored_acc) << std::endl;
+    std::cout << "  p_square_quantile(acc)  = " << accumulators::p_square_quantile(restored_acc) << std::endl;
+    std::cout << "  kurtosis(acc)  = " << accumulators::kurtosis(restored_acc) << std::endl;
+
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // main
 int main()
@@ -172,5 +255,8 @@ int main()
     std::cout << "\nExample 3:\n";
     example3();
 
+    std::cout << "\nExample 4:\n";
+    example4();
+
     return 0;
 }

include/boost/accumulators/framework/accumulator_set.hpp

@@ -94,6 +94,25 @@ namespace detail
     {
     };
 
+    // function object that serialize an accumulator
+    template<typename Archive>
+    struct serialize_accumulator
+    {
+        serialize_accumulator(Archive & _ar, const unsigned int _file_version) :
+            ar(_ar), file_version(_file_version)
+        {}
+
+        template<typename Accumulator>
+        void operator ()(Accumulator &accumulator)
+        {
+            accumulator.serialize(ar, file_version);
+        }
+
+    private:
+        Archive& ar;
+        const unsigned int file_version;
+    };
+
 } // namespace detail
 
 #ifdef _MSC_VER
@@ -420,6 +439,14 @@ struct accumulator_set
         );
     }
 
+    // make the accumulator set serializeable
+    template<class Archive>
+    void serialize(Archive & ar, const unsigned int file_version)
+    {
+        detail::serialize_accumulator<Archive> serializer(ar, file_version);
+        fusion::for_each(this->accumulators, serializer);
+    }
+
 private:
 
     accumulators_type accumulators;

include/boost/accumulators/statistics/count.hpp

@@ -43,6 +43,13 @@ namespace impl
             return this->cnt;
         }
 
+        // make this accumulator serializeable
+        template<class Archive>
+        void serialize(Archive & ar, const unsigned int file_version)
+        { 
+            ar & cnt;
+        }
+
     private:
         std::size_t cnt;
     };

include/boost/accumulators/statistics/covariance.hpp

@@ -152,6 +152,13 @@ namespace impl
             return this->cov_;
         }
 
+        // make this accumulator serializeable
+        template<class Archive>
+        void serialize(Archive & ar, const unsigned int file_version)
+        { 
+            ar & cov_;
+        }
+
     private:
         result_type cov_;
     };

include/boost/accumulators/statistics/density.hpp

@@ -25,6 +25,8 @@
 #include <boost/accumulators/statistics/count.hpp>
 #include <boost/accumulators/statistics/max.hpp>
 #include <boost/accumulators/statistics/min.hpp>
+#include <boost/serialization/vector.hpp>
+#include <boost/serialization/utility.hpp>
 
 namespace boost { namespace accumulators
 {
@@ -184,6 +186,20 @@ namespace impl
             return make_iterator_range(this->histogram);
         }
 
+        // make this accumulator serializeable
+        // TODO split to save/load and check on parameters provided in ctor
+        template<class Archive>
+        void serialize(Archive & ar, const unsigned int file_version)
+        {
+            ar & cache_size;
+            ar & cache;
+            ar & num_bins;
+            ar & samples_in_bin;
+            ar & bin_positions;
+            ar & histogram;
+            ar & is_dirty; 
+        }
+
     private:
         std::size_t            cache_size;      // number of cached samples
         array_type             cache;           // cache to store the first cache_size samples

include/boost/accumulators/statistics/extended_p_square.hpp

@@ -26,6 +26,7 @@
 #include <boost/accumulators/statistics_fwd.hpp>
 #include <boost/accumulators/statistics/count.hpp>
 #include <boost/accumulators/statistics/times2_iterator.hpp>
+#include <boost/serialization/vector.hpp>
 
 namespace boost { namespace accumulators
 {
@@ -236,6 +237,19 @@ namespace impl
             );
         }
 
+    public:
+        // make this accumulator serializeable
+        // TODO: do we need to split to load/save and verify that the parameters did not change?
+        template<class Archive>
+        void serialize(Archive & ar, const unsigned int file_version)
+        { 
+            ar & probabilities;
+            ar & heights;
+            ar & actual_positions;
+            ar & desired_positions;
+            ar & positions_increments;
+        }
+
     private:
         array_type probabilities;         // the quantile probabilities
         array_type heights;               // q_i

include/boost/accumulators/statistics/extended_p_square_quantile.hpp

@@ -185,6 +185,17 @@ namespace impl
             }
 
         }
+
+    public:
+        // make this accumulator serializeable
+        // TODO: do we need to split to load/save and verify that the parameters did not change?
+        template<class Archive>
+        void serialize(Archive & ar, const unsigned int file_version)
+        { 
+            ar & probabilities;
+            ar & probability;
+        }
+
     private:
 
         array_type probabilities;

include/boost/accumulators/statistics/kurtosis.hpp

@@ -63,6 +63,10 @@ namespace impl
                         * ( accumulators::moment<2>(args) - mean(args) * mean(args) )
                     ) - 3.;
         }
+        
+        // serialization is done by accumulators it depends on
+        template<class Archive>
+        void serialize(Archive & ar, const unsigned int file_version) {}
     };
 
 } // namespace impl

include/boost/accumulators/statistics/max.hpp

@@ -48,6 +48,13 @@ namespace impl
             return this->max_;
         }
 
+        // make this accumulator serializeable
+        template<class Archive>
+        void serialize(Archive & ar, const unsigned int file_version)
+        { 
+            ar & max_;
+        }
+
     private:
         Sample max_;
     };