Added count_steps_without_decrease() and count_steps_without_increase().

dlib/statistics/running_gradient.h

@@ -194,6 +194,80 @@ namespace dlib
         return g.probability_gradient_greater_than(thresh);
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T
+        > 
+    size_t count_steps_without_decrease (
+        const T& container,
+        double probability_of_decrease = 0.51
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(0.5 < probability_of_decrease && probability_of_decrease < 1,
+            "\t size_t count_steps_without_decrease()"
+            << "\n\t probability_of_decrease: "<< probability_of_decrease 
+        );
+
+        running_gradient g;
+        size_t count = 0;
+        size_t j = 0;
+        for (auto i = container.rbegin(); i != container.rend(); ++i)
+        {
+            ++j;
+            g.add(*i);
+            if (g.current_n() > 2)
+            {
+                // Note that this only looks backwards because we are looping over the
+                // container backwards.  So here we are really checking if the gradient isn't
+                // decreasing.
+                double prob_decreasing = g.probability_gradient_greater_than(0);
+                // If we aren't confident things are decreasing.
+                if (prob_decreasing < probability_of_decrease)
+                    count = j;
+            }
+        }
+        return count;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T
+        > 
+    size_t count_steps_without_increase (
+        const T& container,
+        double probability_of_increase = 0.51
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(0.5 < probability_of_increase && probability_of_increase < 1,
+            "\t size_t count_steps_without_increase()"
+            << "\n\t probability_of_increase: "<< probability_of_increase 
+        );
+
+        running_gradient g;
+        size_t count = 0;
+        size_t j = 0;
+        for (auto i = container.rbegin(); i != container.rend(); ++i)
+        {
+            ++j;
+            g.add(*i);
+            if (g.current_n() > 2)
+            {
+                // Note that this only looks backwards because we are looping over the
+                // container backwards.  So here we are really checking if the gradient isn't
+                // increasing.
+                double prob_increasing = g.probability_gradient_less_than(0);
+                // If we aren't confident things are increasing.
+                if (prob_increasing < probability_of_increase)
+                    count = j;
+            }
+        }
+        return count;
+    }
+
 // ----------------------------------------------------------------------------------------
 
 }

dlib/statistics/running_gradient_abstract.h

@@ -153,6 +153,61 @@ namespace dlib
               then returns R.probability_gradient_greater_than(thresh).
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T
+        > 
+    size_t count_steps_without_decrease (
+        const T& container,
+        double probability_of_decrease = 0.51
+    );
+    /*!
+        requires
+            - container muse be a container of double values that can be enumerated with
+              .rbegin() and .rend().
+            - 0.5 < probability_of_decrease < 1
+        ensures
+            - If you think of the contents of container as a potentially noisy time series,
+              then this function returns a count of how long the time series has gone
+              without noticeably decreasing in value.  It does this by adding the
+              elements into a running_gradient object and counting how many elements,
+              starting with container.back(), that you need to examine before you are
+              confident that the series has been decreasing in value.  Here, "confident of
+              decrease" means that the probability of decrease is >= probability_of_decrease.  
+            - Setting probability_of_decrease to 0.51 means we count until we see even a
+              small hint of decrease, whereas a larger value of 0.99 would return a larger
+              count since it keeps going until it is nearly certain the time series is
+              decreasing.
+            - The max possible output from this function is container.size().
+    !*/
+
+    template <
+        typename T
+        > 
+    size_t count_steps_without_increase (
+        const T& container,
+        double probability_of_increase = 0.51
+    );
+    /*!
+        requires
+            - container muse be a container of double values that can be enumerated with
+              .rbegin() and .rend().
+            - 0.5 < probability_of_increase < 1
+        ensures
+            - If you think of the contents of container as a potentially noisy time series,
+              then this function returns a count of how long the time series has gone
+              without noticeably increasing in value.  It does this by adding the
+              elements into a running_gradient object and counting how many elements,
+              starting with container.back(), that you need to examine before you are
+              confident that the series has been increasing in value.  Here, "confident of
+              increase" means that the probability of increase is >= probability_of_increase.  
+            - Setting probability_of_increase to 0.51 means we count until we see even a
+              small hint of increase, whereas a larger value of 0.99 would return a larger
+              count since it keeps going until it is nearly certain the time series is
+              increasing.
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
 }