Line data    Source code

       1           0 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : #include <deque>
       7             : #include <vector>
       8             : 
       9             : #include "DataStructures/DataVector.hpp"
      10             : 
      11             : namespace intrp {
      12             : 
      13             : /*!
      14             :  * \brief Predicts the zero crossing of a function.
      15             :  *
      16             :  * Fits a linear function to a set of y_values at different x_values
      17             :  * and uses the fit to predict what x_value the y_value zero will be crossed.
      18             :  *
      19             :  * predicted_zero_crossing treats x=0 in a special way: All of the
      20             :  * x_values must be non-positive; one of the x_values is typically (but
      21             :  * is not required to be) zero.  In typical usage, x is time, and x=0
      22             :  * is the current time, and we are interested in whether the function
      23             :  * crosses zero in the past or in the future. If it cannot be
      24             :  * determined (within the error bars of the fit) whether the zero
      25             :  * crossing occurs for x < 0 versus x > 0, then we return zero.
      26             :  * Otherwise we return the best-fit x for when the function crosses
      27             :  * zero.
      28             :  *
      29             :  * \details We fit to a straight line: y = intercept + slope*x.
      30             :  * So our best guess is that the function will cross zero at
      31             :  * x_best_fit = -intercept/slope.
      32             :  *
      33             :  * However, the data are assumed to be noisy.  The fit gives us error
      34             :  * bars for the slope and the intercept.  Given the error bars, we can
      35             :  * compute four limiting crossing values x0, x1, x2, and x3 by using
      36             :  * the maximum and minimum possible values of slope and intercept.
      37             :  * For example, if we assume slope<0 and intercept>0, then the
      38             :  * earliest possible crossing consistent with the error bars is
      39             :  * x3=(-intercept+delta_intercept)/(slope-delta_slope) and the latest
      40             :  * possible crossing consistent with the error bars is
      41             :  * x0=(-intercept-delta_intercept)/(slope+delta_slope).
      42             :  *
      43             :  * We compute all four crossing values and demand that all of them
      44             :  * are either at x>0 (i.e. in the future if x is time) or at x<0
      45             :  * (i.e. in the past if x is time).  Otherwise we conclude that we
      46             :  * cannot determine even the sign of the crossing value, so we return
      47             :  * zero.
      48             :  */
      49           1 : double predicted_zero_crossing_value(const std::vector<double>& x_values,
      50             :                                      const std::vector<double>& y_values);
      51             : 
      52             : /*!
      53             :  * \brief Predicts the zero crossing of multiple functions.
      54             :  *
      55             :  * For the ith element of the DataVector inside y_values, calls
      56             :  * predicted_zero_crossing_value(x_values,y_values[:][i]), where we
      57             :  * have used python-like notation.
      58             :  */
      59           1 : DataVector predicted_zero_crossing_value(
      60             :     const std::deque<double>& x_values, const std::deque<DataVector>& y_values);
      61             : 
      62             : }  // namespace intrp