Add probability_values_are_increasing() and probability_values_are_increasing_robust()

dlib/statistics/running_gradient.h

@@ -240,6 +240,50 @@ namespace dlib
         return upper_q;
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T
+        > 
+    double probability_values_are_increasing (
+        const T& container
+    )
+    {
+        running_gradient g;
+        for (auto x : container)
+        {
+            g.add(x);
+        }
+        if (g.current_n() > 2)
+            return g.probability_gradient_greater_than(0);
+        else
+            return 0.5;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T
+        > 
+    double probability_values_are_increasing_robust (
+        const T& container,
+        double quantile_discard = 0.10
+    )
+    {
+        const auto quantile_thresh = find_upper_quantile(container, quantile_discard); 
+        running_gradient g;
+        for (auto x : container)
+        {
+            // Ignore values that are too large.
+            if (x <= quantile_thresh)
+                g.add(x);
+        }
+        if (g.current_n() > 2)
+            return g.probability_gradient_greater_than(0);
+        else
+            return 0.5;
+    }
+
 // ----------------------------------------------------------------------------------------
 
     template <

dlib/statistics/running_gradient_abstract.h

@@ -166,6 +166,45 @@ namespace dlib
               then returns R.probability_gradient_greater_than(thresh).
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T
+        > 
+    double probability_values_are_increasing (
+        const T& container
+    );
+    /*!
+        requires
+            - container must be a container of double values that can be enumerated with a
+              range based for loop.
+        ensures
+            - Returns the probability that the values in container are increasing.  This is
+              probability_gradient_greater_than(container,0) if container.size() > 2 and 0.5
+              otherwise.
+    !*/
+
+    template <
+        typename T
+        > 
+    double probability_values_are_increasing_robust (
+        const T& container,
+        double quantile_discard = 0.10
+    );
+    /*!
+        requires
+            - container must be a container of double values that can be enumerated with a
+              range based for loop.
+        ensures
+            - This function behaves just like probability_values_are_increasing(container) except
+              that it ignores values in container that are in the upper quantile_discard quantile.
+              So for example, if the quantile discard is 0.1 then the 10% largest values in
+              container are ignored.  This makes the estimate robust to large spurious values that
+              otherwise might confuse the results.  For instance, the sequence of values 
+              {1,2,1e10,3,4,5,6,7,8,9} looks decreasing to probability_values_are_increasing() 
+              but looks increasing to probability_values_are_increasing_robust().
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     template <

dlib/test/statistics.cpp

@@ -7,6 +7,7 @@
 #include <cstdlib>
 #include <ctime>
 #include <dlib/statistics.h>
+#include <dlib/statistics/running_gradient.h>
 #include <dlib/rand.h>
 #include <dlib/svm.h>
 #include <algorithm>
@@ -900,6 +901,14 @@ namespace
             }
         }
 
+        void test_probability_values_are_increasing() {
+            DLIB_TEST(probability_values_are_increasing(std::vector<double>{1,2,3,4,5,6,7,8}) > 0.99);
+            DLIB_TEST(probability_values_are_increasing(std::vector<double>{8,7,6,5,4,4,3,2}) < 0.01);
+            DLIB_TEST(probability_values_are_increasing_robust(std::vector<double>{1,2,3,4,5,6,7,8}) > 0.99);
+            DLIB_TEST(probability_values_are_increasing_robust(std::vector<double>{8,7,6,5,4,4,3,2}) < 0.01);
+            DLIB_TEST(probability_values_are_increasing(std::vector<double>{1,2,1e10,3,4,5,6,7,8}) < 0.3);
+            DLIB_TEST(probability_values_are_increasing_robust(std::vector<double>{1,2,1e100,3,4,5,6,7,8}) > 0.99);
+        }
 
         void test_event_corr()
         {
@@ -942,6 +951,7 @@ namespace
             test_running_stats_decayed();
             test_running_scalar_covariance_decayed();
             test_equal_error_rate();
+            test_probability_values_are_increasing();
         }
     } a;