// Copyright (C) 2016 Davis E. King (davis@dlib.net) // License: Boost Software License See LICENSE.txt for the full license. #undef DLIB_RuNNING_GRADIENT_ABSTRACT_Hh_ #ifdef DLIB_RuNNING_GRADIENT_ABSTRACT_Hh_ namespace dlib{classrunning_gradient{/*! WHAT THIS OBJECT REPRESENTS This object is a tool for estimating if a noisy sequence of numbers is trending up or down and by how much. It does this by finding the least squares fit of a line to the data and then allows you to perform a statistical test on the slope of that line. !*/ public:running_gradient( ); /*! ensures - #current_n() == 0 !*/voidclear( ); /*! ensures - #current_n() == 0 - this object has its initial value - clears all memory of any previous data points !*/doublecurrent_n( ) const; /*! ensures - returns the number of values given to this object by add(). !*/voidadd(doubley ); /*! ensures - Updates the gradient() and standard_error() estimates in this object based on the new y value. - #current_n() == current_n() + 1 !*/doublegradient( ) const; /*! requires - current_n() > 1 ensures - If we consider the values given to add() as time series data, we can estimate the rate-of-change of those values. That is, how much, typically, do those values change from sample to sample? The gradient() function returns the current estimate. It does this by finding the least squares fit of a line to the data given to add() and returning the slope of this line. !*/doubleintercept( ) const; /*! requires - current_n() > 0 ensures - This class fits a line to the time series data given to add(). This function returns the intercept of that line while gradient() returns the slope of that line. This means that, for example, the next point that add() will see, as predicted by this best fit line, is the value intercept() + current_n()*gradient(). !*/doublestandard_error( ) const; /*! requires - current_n() > 2 ensures - returns the standard deviation of the estimate of gradient(). !*/doubleprobability_gradient_less_than(doublethresh ) const; /*! requires - current_n() > 2 ensures - If we can assume the values given to add() are linearly related to each other and corrupted by Gaussian additive noise then our estimate of gradient() is a random variable with a mean value of gradient() and a standard deviation of standard_error(). This lets us compute the probability that the true gradient of the data is less than thresh, which is what this function returns. !*/doubleprobability_gradient_greater_than(doublethresh ) const; /*! requires - current_n() > 2 ensures - returns 1-probability_gradient_less_than(thresh) !*/};voidserialize( const running_gradient& item, std::ostream& out ); /*! provides serialization support !*/voiddeserialize( running_gradient& item, std::istream& in ); /*! provides serialization support !*/ // ---------------------------------------------------------------------------------------- template < typename T >doubleprobability_gradient_less_than( const T& container,doublethresh ); /*! requires - container must be a container of double values that can be enumerated with a range based for loop. - The container must contain more than 2 elements. ensures - Puts all the elements of container into a running_gradient object, R, and then returns R.probability_gradient_less_than(thresh). !*/ template < typename T >doubleprobability_gradient_greater_than( const T& container,doublethresh ); /*! requires - container must be a container of double values that can be enumerated with a range based for loop. - The container must contain more than 2 elements. ensures - Puts all the elements of container into a running_gradient object, R, and then returns R.probability_gradient_greater_than(thresh). !*/ // ---------------------------------------------------------------------------------------- template < typename T >doubleprobability_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 >doubleprobability_values_are_increasing_robust( const T& container,doublequantile_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 < typename T >size_tcount_steps_without_decrease( const T& container,doubleprobability_of_decrease = 0.51 ); /*! requires - container must 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_tcount_steps_without_decrease_robust( const T& container,doubleprobability_of_decrease = 0.51,doublequantile_discard = 0.10 ); /*! requires - container must be a container of double values that can be enumerated with .begin() and .end() as well as .rbegin() and .rend(). - 0.5 < probability_of_decrease < 1 - 0 <= quantile_discard <= 1 ensures - This function behaves just like count_steps_without_decrease(container,probability_of_decrease) 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. !*/ // ---------------------------------------------------------------------------------------- template < typename T >size_tcount_steps_without_increase( const T& container,doubleprobability_of_increase = 0.51 ); /*! requires - container must 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. !*/ // ---------------------------------------------------------------------------------------- template < typename T >doublefind_upper_quantile( const T& container,doublequantile ); /*! requires - container must be a container of double values that can be enumerated with .begin() and .end(). - 0 <= quantile <= 1 - container.size() > 0 ensures - Finds and returns the value such that quantile percent of the values in container are greater than it. For example, 0.5 would find the median value in container while 0.1 would find the value that lower bounded the 10% largest values in container. !*/ // ----------------------------------------------------------------------------------------}#endif // DLIB_RuNNING_GRADIENT_ABSTRACT_Hh_