class TimeSeriesMath::TimeSeries

TimeSeries

TimeSeries class provides an efficient data structure for storing timestamped data values.

TimeSeries maintains order of its elements and provides efficient search methods for near-constant time access (depends strongly on timestamps distribution – the more even, the better).

Examples:

require 'time_series_math'
include TimeSeriesMath

# one by one element insertion
ts = TimeSeries.new
ts.push 1.0, { x: 2.0, y: 3.0 }
ts.push 1.2, { x: 2.0, y: 3.0 }
ts.push 1.6, { x: 2.0, y: 3.0 }
ts.push 1.9, { x: 2.0, y: 3.0 }
ts.push 2.1, { x: 2.0, y: 3.0 }

# more time-efficient batch insertion using arrays:
ts = TimeSeries.new
tt = [ 1.0, 1.2, 1.6, 1.9, 2.1 ]
dd = [ {x: 2.0}, {x: 2.1}, {x: 2.5}, {x: 2.7}, {x: 2.85} ]
ts.push_array(tt, dd)

# retrieve closest element before given time
ts[1.2] # => { x: 2.1 }
ts[2.095] # => { x: 2.7 }

Attributes

data[R]
processor[R]

Public Class Methods

new(arr_t = nil, arr_v = nil) click to toggle source

Creates a TimeSeries object.

@param arr_t [Array<Float>] Array of timestamps @param arr_v [Array] Array of corresponding values, should be of the same size as arr_t

Examples:

ts = TimeSeries.new # creates empty TimeSeries object

ts = TimeSeries.new([0.1, 0.5, 1.0], [120.0, 130.0, 140.0])
# File lib/time_series_math/time_series.rb, line 47
def initialize(arr_t = nil, arr_v = nil)
  @data = []
  @processor = nil
  push_array(arr_t, arr_v) if arr_t && arr_v
end

Public Instance Methods

[](t) click to toggle source

Returns value calculated at t.

The actual value returned depends on the processor used by TimeSeries object. When no processor is used, the returned value is the value of the last element preceding, or exactly at t.

# File lib/time_series_math/time_series.rb, line 149
def [](t)
  i = left_index_at(t)
  i && @data[i][1]
end
[]=(t, v) click to toggle source

Alias for push(t, v)

Example:

ts = TimeSeries.new
ts[1.0] = { x: 123.0 }
ts[2.0] = { x: 125.0 }

ts[1.0] # => { x: 123.0 }

@param (see push)

# File lib/time_series_math/time_series.rb, line 121
def []=(t, v)
  push(t, v)
end
first() click to toggle source

@return [Array, nil] First element of the time series

# File lib/time_series_math/time_series.rb, line 73
def first
  @data.first
end
indices_at(t) click to toggle source

@return [Array] indices of the elements surrounding t.

# File lib/time_series_math/time_series.rb, line 156
def indices_at(t)
  bsearch_indices_at(t)
end
keys() click to toggle source

@return [Array] Array of timestamps

# File lib/time_series_math/time_series.rb, line 61
def keys
  @data.map { |d| d[0] }
end
last() click to toggle source

@return [Array, nil] Last element of the time series

# File lib/time_series_math/time_series.rb, line 85
def last
  @data.last
end
left_index_at(t) click to toggle source

@return index of the element preceding t

# File lib/time_series_math/time_series.rb, line 139
def left_index_at(t)
  indices_at(t).first
end
push(t, v) click to toggle source

Inserts new element into time series. @param t [Float] Timestamp of the new value @param v [Fixnum, Float, Array, Hash] New value

# File lib/time_series_math/time_series.rb, line 99
def push(t, v)
  t = t.to_f
  i = left_index_at(t)
  if i.nil?
    @data.unshift([t, v])
  else
    @data.insert(i + 1, [t, v])
  end
end
push_array(arr_t, arr_v) click to toggle source

Inserts batch of new values into time series. This method is more time efficient than using push to insert elements one by one.

@param arr_t [Array] Array of timestamps @param arr_v [Array] Array of corresponding values, should be of the same size as arr_t

# File lib/time_series_math/time_series.rb, line 131
def push_array(arr_t, arr_v)
  arr_data = arr_t.zip(arr_v)
  @data.concat(arr_data)
  @data.sort_by! { |d| d[0] }
end
size() click to toggle source

@return number of values in the series

# File lib/time_series_math/time_series.rb, line 55
def size
  @data.size
end
t_first() click to toggle source

@return [Float, nil] Timestamp of the first element

# File lib/time_series_math/time_series.rb, line 79
def t_first
  first && first[0]
end
t_last() click to toggle source

@return [Float, nil] Timestamp of the last element

# File lib/time_series_math/time_series.rb, line 91
def t_last
  last && last[0]
end
use(processor_module) click to toggle source

Use processor

# File lib/time_series_math/time_series.rb, line 162
def use(processor_module)
  @processor = processor_module
  extend processor_module
end
values() click to toggle source

@return [Array] Array of values

# File lib/time_series_math/time_series.rb, line 67
def values
  @data.map { |d| d[1] }
end