bortexz.tacos.timeseries — io.github.bortexz/tacos 0.0.1

-IntoTimeseries clj protocol

Protocol that constructs a timeseries from a given object

-into-timeseries clj

(-into-timeseries _)

create clj

(create)

(create obj)

Creates a new timeseries. Timeseries are currently implemented as data.avl sorted maps with timestamp as keys. Note that anything that can be compared can be used as a timestamp (epoch millis integer, java.time.Instant, etc...)

0-arity creates an empty timeseries. 1-arity creates a timeseries from object implementing IntoTimeseries. Objects implementing IntoTimeseries:

• Clojure collections, each item being a tuple [timestamp value].
• Views created with view or tail.
• AVL Sorted map, returning the map unchanged.

delta-timeline clj

(delta-timeline new-timestamps max-size)

Returns implementation of Timeline that updates given new-timestamps (ordered collection of new timestamps) on a timeseries, and keeps a maximum of max-size items.

earliest clj

(earliest coll)

Returns the earliest item of timeseries coll as tuple [timestamp value], or nil if coll is empty.

keep-latest clj

(keep-latest coll n)

Keeps only n latest values of timeseries coll. Same as (create (tail coll n)), but faster when number of items to be removed is small (currently < 10), as it dissoc's the earliest items instead of creating a new timeseries. When number of items to remove is >= 10, falls back to (create (tail coll n)).

latest clj

(latest coll)

Returns the latest item of timeseries coll as tuple [timestamp value], or nil if coll is empty.

moving-average clj

(moving-average coll k period)

Calculates the moving average of given coll at timestamp k for period items, or nil if there aren't enough values.

nearest clj

(nearest coll test k)

Returns the nearest item [timestamp value] to timestamp k on timeseries coll using test, that can be either >, >=, <, <=.

select clj

(select view testf)

Selects a value from view by testing each value against the previously selected value with testf, a 2-arity fn that accepts new value and previosly selected value. If testf returns true, then the new value becomes the selected value. Iteration starts with first value as previosly selected, and second value as next value. Returns [view-idx val] where view-idx is the index in view of the selected value, and val is selected value.

E.g

• latest [idx val] of previous 10 vals from endk (select (tail coll 10 {:endk endk :vf val}) >=)

shift clj

(shift coll k n)

(shift coll k n {:keys [vf] :or {vf identity}})

Returns item at distance n from timestamp k. If timestamp k does not exist, or new position does not exist, returns nil. If item exists, returns tuple [timestamp value].

Optionally accepts opts:

• vf fn to get on map-entry [timestamp val] if existing, defaults to identity.

e.g. (shift coll k -1) takes the previous item to timestamp k e.g. (shift coll k 1) takes the next item to timestamp k.

tail clj

(tail coll n)

(tail coll n {:keys [endk vf full?] :or {vf val full? true}})

Returns a view of the tail of timeseries coll, up to n items.

opts:

• endk last timestamp of the tail, defaults to the latest of the timeseries if not specified. If endk is specified, but does not exist on coll, returns nil.
• vf fn that accepts an item [timestamp value] and returns a val (e.g key, val, ...). Defaults to val.
• full? If false, returns tails that contain < n items, otherwise returns nil instead of an incomplete tail view. Defaults to true.

Timeline clj protocol

Protocol enabling incremental timeseries.

A timeline is responsible for keeping the timeseries updated with new timestamps, as well as prune earliest items when are no longer needed.

-apply-timeline clj

(-apply-timeline this value get-ts)

Given:

• timeseries current timeseries value
• get-ts 2-arity fn accepting accumulated timeseries and timestamp, returns the value of this timeseries at timestamp.

Returns updated timeseries value.

view clj

(view coll)

(view coll {:keys [startk endk vf] :or {vf identity}})

Returns a view object for traversing timeseries coll with given opts.

A view is reducedible, seqable, countable, indexed and can be converted into a new timeseries.

Values of this view will be retrieved from each mapentry [timestamp value] using vf (defaults to val).

A new timeseries can be created from this view calling (create <view>)

nth can be used on the view to get the nth value inside the view.

When reduced using reduce-kv, the k will be the index inside the view (starting at 0, ending at (dec (count view))) as if reducing-kv a vector of items.

If startk or endk are specified but do not exist on coll, returns nil.

opts:

• startk First timestamp of the view. Defaults to earliest timestamp of timeseries.
• endk Last timestamp of the view. Defaults to latest timestamp of timeseries.
• vf fn to apply to tuple [timestamp value] to get a value. Defaults to identity.