[ML] Change point detection and prediction (#92)

Closes #6.

Author: tveasey

docs/CHANGELOG.asciidoc

@@ -29,6 +29,7 @@
 
 Improve and use periodic boundary condition for seasonal component modeling ({pull}84[#84])
 Improve robustness w.r.t. outliers of detection and initialisation of seasonal components ({pull}90[#90])
+Explicit change point detection and modelling ({pull}92[#92])
 
 === Bug Fixes
 

include/core/CContainerPrinter.h

@@ -274,7 +274,7 @@ class CORE_EXPORT CContainerPrinter : private CNonInstantiatable {
         return *value;
     }
 
-    //! Print a boost::shared_pointer.
+    //! Print a std::shared_pointer.
     template<typename T>
     static std::string printElement(const std::shared_ptr<T>& value) {
         if (value == std::shared_ptr<T>()) {

include/core/CRapidJsonWriterBase.h

@@ -74,7 +74,6 @@ class CRapidJsonWriterBase
     using TValue = rapidjson::Value;
     using TDocumentWeakPtr = std::weak_ptr<TDocument>;
     using TValuePtr = std::shared_ptr<TValue>;
-
     using TPoolAllocatorPtr = std::shared_ptr<CRapidJsonPoolAllocator>;
     using TPoolAllocatorPtrStack = std::stack<TPoolAllocatorPtr>;
     using TStrPoolAllocatorPtrMap = boost::unordered_map<std::string, TPoolAllocatorPtr>;

include/core/Constants.h

@@ -16,38 +16,41 @@ namespace ml {
 namespace core {
 namespace constants {
 
+//! A minute in seconds.
+const core_t::TTime MINUTE{60};
+
 //! An hour in seconds.
-const core_t::TTime HOUR = 3600;
+const core_t::TTime HOUR{3600};
 
 //! A day in seconds.
-const core_t::TTime DAY = 86400;
+const core_t::TTime DAY{86400};
 
 //! A (two day) weekend in seconds.
-const core_t::TTime WEEKEND = 172800;
+const core_t::TTime WEEKEND{172800};
 
 //! Five weekdays in seconds.
-const core_t::TTime WEEKDAYS = 432000;
+const core_t::TTime WEEKDAYS{432000};
 
 //! A week in seconds.
-const core_t::TTime WEEK = 604800;
+const core_t::TTime WEEK{604800};
 
 //! A (364 day) year in seconds.
-const core_t::TTime YEAR = 31449600;
+const core_t::TTime YEAR{31449600};
 
 //! Log of min double.
-const double LOG_MIN_DOUBLE = std::log(std::numeric_limits<double>::min());
+const double LOG_MIN_DOUBLE{std::log(std::numeric_limits<double>::min())};
 
 //! Log of max double.
-const double LOG_MAX_DOUBLE = std::log(std::numeric_limits<double>::max());
+const double LOG_MAX_DOUBLE{std::log(std::numeric_limits<double>::max())};
 
 //! Log of double epsilon.
-const double LOG_DOUBLE_EPSILON = std::log(std::numeric_limits<double>::epsilon());
+const double LOG_DOUBLE_EPSILON{std::log(std::numeric_limits<double>::epsilon())};
 
 //! Log of two.
-const double LOG_TWO = 0.693147180559945;
+const double LOG_TWO{0.693147180559945};
 
 //! Log of two pi.
-const double LOG_TWO_PI = 1.83787706640935;
+const double LOG_TWO_PI{1.83787706640935};
 
 #ifdef Windows
 const char PATH_SEPARATOR = '\\';

include/maths/CBasicStatistics.h

@@ -201,6 +201,14 @@ class MATHS_EXPORT CBasicStatistics {
             }
         }
 
+        //! Update the moments with the collection \p x.
+        template<typename U, std::size_t N>
+        void add(const core::CSmallVector<U, N>& x) {
+            for (const auto& xi : x) {
+                this->add(xi);
+            }
+        }
+
         //! Update the moments with the collection \p x.
         template<typename U>
         void add(const std::vector<SSampleCentralMoments<U, ORDER>>& x) {

include/maths/CCalendarComponent.h

@@ -82,6 +82,9 @@ class MATHS_EXPORT CCalendarComponent : private CDecompositionComponent {
     //! Clear all data.
     void clear();
 
+    //! Linearly scale the component's by \p scale.
+    void linearScale(core_t::TTime time, double scale);
+
     //! Adds a value \f$(t, f(t))\f$ to this component.
     //!
     //! \param[in] time The time of the point.

include/maths/CCalendarComponentAdaptiveBucketing.h

@@ -67,6 +67,9 @@ class MATHS_EXPORT CCalendarComponentAdaptiveBucketing : private CAdaptiveBucket
     //! allocated memory.
     void clear();
 
+    //! Linearly scale the bucket values by \p scale.
+    void linearScale(double scale);
+
     //! Add the function value at \p time.
     //!
     //! \param[in] time The time of \p value.

include/maths/CModel.h

@@ -44,9 +44,11 @@ using TForecastPushDatapointFunc = std::function<void(SErrorBar)>;
 class MATHS_EXPORT CModelParams {
 public:
     CModelParams(core_t::TTime bucketLength,
-                 const double& learnRate,
-                 const double& decayRate,
-                 double minimumSeasonalVarianceScale);
+                 double learnRate,
+                 double decayRate,
+                 double minimumSeasonalVarianceScale,
+                 core_t::TTime minimumTimeToDetectChange,
+                 core_t::TTime maximumTimeToTestForChange);
 
     //! Get the bucket length.
     core_t::TTime bucketLength() const;
@@ -63,6 +65,15 @@ class MATHS_EXPORT CModelParams {
     //! Get the minimum seasonal variance scale.
     double minimumSeasonalVarianceScale() const;
 
+    //! Check if we should start testing for a change point in the model.
+    bool testForChange(core_t::TTime changeInterval) const;
+
+    //! Get the minimum time to detect a change point in the model.
+    core_t::TTime minimumTimeToDetectChange(void) const;
+
+    //! Get the maximum time to test for a change point in the model.
+    core_t::TTime maximumTimeToTestForChange(void) const;
+
     //! Set the probability that the bucket will be empty for the model.
     void probabilityBucketEmpty(double probability);
 
@@ -78,6 +89,10 @@ class MATHS_EXPORT CModelParams {
     double m_DecayRate;
     //! The minimum seasonal variance scale.
     double m_MinimumSeasonalVarianceScale;
+    //! The minimum time permitted to detect a change in the model.
+    core_t::TTime m_MinimumTimeToDetectChange;
+    //! The maximum time permitted to test for a change in the model.
+    core_t::TTime m_MaximumTimeToTestForChange;
     //! The probability that a bucket will be empty for the model.
     double m_ProbabilityBucketEmpty;
 };
@@ -90,8 +105,6 @@ class MATHS_EXPORT CModelAddSamplesParams {
 
 public:
     CModelAddSamplesParams();
-    CModelAddSamplesParams(const CModelAddSamplesParams&) = delete;
-    const CModelAddSamplesParams& operator=(const CModelAddSamplesParams&) = delete;
 
     //! Set whether or not the data are integer valued.
     CModelAddSamplesParams& integer(bool integer);
@@ -145,8 +158,6 @@ class MATHS_EXPORT CModelProbabilityParams {
 
 public:
     CModelProbabilityParams();
-    CModelProbabilityParams(const CModelAddSamplesParams&) = delete;
-    const CModelProbabilityParams& operator=(const CModelAddSamplesParams&) = delete;
 
     //! Set the tag for the entity for which to compute the probability.
     CModelProbabilityParams& tag(std::size_t tag);
@@ -254,6 +265,9 @@ class MATHS_EXPORT CModel {
         E_Reset    //!< Model reset.
     };
 
+    //! Combine the results \p lhs and \p rhs.
+    static EUpdateResult combine(EUpdateResult lhs, EUpdateResult rhs);
+
 public:
     CModel(const CModelParams& params);
     virtual ~CModel() = default;