Package com.amalgamasimulation.utils

Interface ITimeStatistics

All Known Implementing Classes:
AdaptiveTimeStatistics, SparseTimeStatistics, TimeStatistics
public interface ITimeStatistics
Represents a time series data with fixed granularity. Granularity is the size of time buckets at which the values are accumulated and aggregated.

Typical uses of this class include:

  • Collecting daily inventory statistics in supply chain or manufacturing models
  • Collecting truck runs count statistics by months
  • Collecting amount of material transported by hours

This class makes difference between empty time buckets and time buckets with zero values. So, explicitly adding zero value to a time bucket may result in changes of the overall statistics output, such as a different result of totalStatistics() method.

Author:
Andrey Malykhanov

  • Method Details

    • replace

      void replace(double time, double value)
      Replaces the value in the time bucket corresponding to the specified time with the specified value. Makes the bucket containing the specified time non-empty.
      Parameters:
      time - specified time, used to determine the time bucket
      value - specified value, can be both positive and negative. This value is set to the corresponding time bucket

      The figure below illustrates the result of calling this method:

    • add

      void add(double time, double value)
      Adds the specified value to the time bucket corresponding to the specified time. Makes the bucket containing the specified time non-empty.
      Parameters:
      time - specified time, used to determine the time bucket
      value - specified value, can be both positive and negative

      The figure below illustrates the result of calling this method:

    • lastTime

      double lastTime()
      Returns the last time that was set by calling add(double, double) or replace(double, double) method, or Double.NEGATIVE_INFINITY if none of these methods have yet been called.
      Returns:
      last time that was set by calling add(double, double) or replace(double, double) method, or Double.NEGATIVE_INFINITY

    • lastValue

      double lastValue()
      Returns the value in the time bucket that corresponds to lastTime(), or 0 if lastTime() is equal to Double.NEGATIVE_INFINITY, i.e. if none of these methods have yet been called.
      Returns:
      value in the time bucket that corresponds to lastTime(), or 0

    • totalStatistics

      DoubleSummaryStatistics totalStatistics()
      Returns a DoubleSummaryStatistics instance that contains the statistics across all existing time buckets.
      Returns:
      DoubleSummaryStatistics instance that contains the statistics across all values in the existing time buckets

      The figure below illustrates the result of calling this method:

    • interpolatedStatistics

      DoubleSummaryStatistics interpolatedStatistics(double beginTime, double endTime, boolean includeZeros)
      Returns a DoubleSummaryStatistics instance that contains the statistics across all time buckets between the buckets containing the specified begin and end times. Interpolates the data for empty time buckets: assumes the value in an empty time bucket is equal to the value in the previous non-empty time bucket, or 0 if there is no such bucket.

      Specifies whether to include zero values into the statistics or not.

      Parameters:
      beginTime - begin time, points to the first time bucket of collecting the statistics
      endTime - end time, points to the last time bucket of collecting the statistics
      includeZeros - whether or not to include zeroes while calculating statistics
      Returns:
      DoubleSummaryStatistics instance that contains the statistics across all time buckets between the specified begin and end times

      The figure below illustrates the result of calling this method:

    • interpolatedStatistics

      DoubleSummaryStatistics interpolatedStatistics(double beginTime, double endTime)
      Returns a DoubleSummaryStatistics instance that contains the statistics across all time buckets between the buckets containing the specified begin and end times. Interpolates the data for empty time buckets: assumes the value in an empty time bucket is equal to the value in the previous non-empty time bucket, or 0 if there is no such bucket.

      Includes zero values into the statistics.

      Parameters:
      beginTime - begin time, points to the first time bucket of collecting the statistics
      endTime - end time, points to the last time bucket of collecting the statistics
      Returns:
      DoubleSummaryStatistics instance that contains the statistics across all time buckets between the specified begin and end times

      The figure below illustrates the result of calling this method:

    • valueAt

      double valueAt(double time)
      Returns the value in the bucket containing the specified time. If the specified time is associated with an empty bucket, zero is returned.
      Parameters:
      time - specified time
      Returns:
      value in the bucket containing the specified time, or zero

    • interpolatedValueAt

      double interpolatedValueAt(double time)
      Returns the value in the bucket containing the specified time. If no values were added to the bucket containing the specified time, then returns the value in the last non-empty preceding the current bucket.

      In other words, returns a linearly interpolated value at the specified time.

      If there are no non-empty buckets at of before the specified time, returns zero.

      Parameters:
      time - specified time
      Returns:
      linearly interpolated value at the specified time

      The figure below illustrates the result of interpolation:

    • sumBetween

      double sumBetween(double beginTime, double endTime)
      Returns the sum of values in all non-empty buckets the buckets containing the specified begin and end times. Does not do interpolation, i.e. does not consider empty buckets.

      If the sum is needed with interpolated values, use interpolatedStatistics(double, double) method.

      Parameters:
      beginTime - begin time, points to the first time bucket of summation
      endTime - end time, points to the last time bucket of summation
      Returns:
      sum of values in all non-empty buckets between the specified begin and end times

    • minTime

      double minTime()
      Returns zero, which is the minimum argument for a typical time series statistics.
      Returns:
      always returns zero

    • maxTime

      double maxTime()
      Returns the time corresponding to the right border of a non-empty bucket with the biggest argument.
      Returns:
      time of a non-empty bucket with the biggest argument

    • granularity

      double granularity()
      Returns the granularity of this time statistics. Granularity is the size of time buckets at which the values are accumulated and aggregated.
      Returns:
      granularity of this time statistics

    • plotData

      List<Pair<Double,Double>> plotData()
      Returns the data for plotting the content of this ITimeStatistics instance on a line chart. The data is returned in the form of List of argument-value Pairs. The returned list is sorted by arguments in ascending order.
      Returns:
      List of argument-value Pairs

    • cumulativePlotData

      List<Pair<Double,Double>> cumulativePlotData()
      Returns the data for plotting the cumulative sum of the content of this TimeStatistics instance on a line chart. The data is returned in the form of List of argument-value Pairs. The returned list is sorted by arguments in ascending order.
      Returns:
      List of argument-value Pairs

    • copy

      ITimeStatistics copy()
      Returns a copy of this ITimeStatistics instance.
      Returns:
      copy of this ITimeStatistics instance

    • dataSize

      int dataSize()
      Returns the number of data points stored inside this ITimeStatistics instance.
      Returns:
      number of data points stored inside this ITimeStatistics instance

    • getSum

      default ITimeStatistics getSum(ITimeStatistics otherTimeStatistics)
      Returns a new instance of ITimeStatistics which is the sum of this instance and the other specified instance.

      Sum of two ITimeStatistics instances is an bucket-wise sum of them without considering any interpolation.

      Parameters:
      otherTimeStatistics - ITimeStatistics which is summed with this one
      Returns:
      new instance of ITimeStatistics

    • getInterpolatedSum

      default ITimeStatistics getInterpolatedSum(ITimeStatistics otherTimeStatistics)
      Returns a new instance of ITimeStatistics which is the interpolated sum of this instance and the other specified instance.
      Parameters:
      otherTimeStatistics - ITimeStatistics which is summed with this one
      Returns:
      new instance of ITimeStatistics

    • getSum

      static ITimeStatistics getSum(Stream<ITimeStatistics> elements, double granularity)

    • getSum

      static ITimeStatistics getSum(List<ITimeStatistics> elements, double granularity)

    • nonEmptyBucketsStream

      Stream<Pair<Double,Double>> nonEmptyBucketsStream()
      Returns a Stream of argument-value Pairs. Each pair represents a non-empty (but potentially zero) bucket. Stream is ordered by time (the first element of a pair) in ascending order.
      Returns:
      Stream of argument-value Pairs

    • toCodeString

      default String toCodeString()