Symbolic time series representations

Means of representing your time series data in a convenient way for your task.

Overview

The codebase under this repository is supposed to be operated in one of three ways:

• As a standalone C library (builds automatically)
• As a standalone Lua library (builds automatically provided Lua is found on your system)
• As a plugin lib for mozilla-services/lua_sandbox (is built upon fetch from main repo, linked against luasb headers)

Installation

Prerequisites

• C compiler (GCC 4.7+)
• Lua 5.1 (optional, needed to build Lua part)
• CMake (2.8.7+)

CMake Build Instructions

git clone https://github.com/Quadrocube/symtseries.git
cd symtseries
mkdir release
cd release
cmake .. -DCMAKE_BUILD_TYPE=Release && make
ctest

SAX (Symbolic Aggregate approXimation)

Latest SAX paper

iSAX 2.0

Overview

SAX is the method of time series data representation which provides a user with several interesting capabilities:

• Shape-based pattern matching (even for HUGE pattern collections -- which is yet TBD though)
• Shape-based time series clustering
• Numerosity and dimensionality reduction of your time series data

Example Usage

API functions

window.new(n, w, c)

require "sax"
local window = sax.window.new(150, 10, 8)

Import sax module via the Lua 'require' function. The module is globally registered and returned by the require function.

Arguments

• n (unsigned) The number of values to keep track of (must be > 1 and <= 4096)
• w (unsigned) The number of frames to split the window into (must be > 1 and a divisor of n)
• c (unsigned) The cardinality of the word (must be between 2 and STS_MAX_CARDINALITY)

Return

• mozsvc.sax.window userdata object

word.new[(v, w, c), (s, c)]

local a = sax.word.new({10.3, 7, 1, -5, -5, 7.2}, 2, 8)
local b = sax.word.new("FC", 8)
print(a == b)
-- prints true

Arguments

• v (table-array) Series to be represented in SAX notation (must be of length > 1 and <= 4096)
• w (unsigned) The number of frames to split the series into (must be > 1 and a divisor of #v)
• c (unsigned) The cardinality of the word (must be between 2 and STS_MAX_CARDINALITY)

OR

• s (string) SAX-notation string denoting a word (must be of length > 1)
• c (unsigned) The cardinality of the word (must be between 2 and STS_MAX_CARDINALITY)

Return

• mozsvc.sax.word userdata object

mindist(a, b)

local a = sax.word.new({10.3, 7, 1, -5, -5, 7.2}, 2, 8)
local values = {-9, -8, -7, -5, -5, 7.2}
local b = sax.window.new(#values, 2, 8)
for i=1,#values do b:add(values[i]) end
local distance, above, below = sax.mindist(a, b)
-- distance == 1.560325
-- above == 1.103316
-- below == 1.103316

Arguments

• a, b (mozsvc.sax.word or mozsvc.sax.window) SAX words or windows to compute mindist.
• Note that currently mindist between different-[nwc] words is not supported

Return

• distance Lowerbounding approximation of the Euclidian distance between series represented in a and b
• above Lowerbounding approximation of the Euclidian distance where a is above b
• below Lowerbounding approximation of the Euclidian distance where a is below b

version()

print(sax.version())

Return

• Version number as a string

Window methods

add(val)

local window = sax.window.new(4, 2, 4)
local values = {1, 2, 3, 10.1}
local a = sax.word.new(values, 2, 4)

for i=1,4 do window:add(values[i]) end

print(a == window)
window:add({-10, 1, 2, 3, 10.1}) -- it only copies n last values if given more than n
print(a == window)

-- prints true true

Arguments

• val (number or array) value(s) to be appended to a window

Return

• none - throws an error on invalid input

get_word()

Return

• returns a copy of current word

clear()

local window = sax.window.new(4, 2, 4)
local values = {1, 2, 3, 10.1}

for i=1,4 do window:add(values[i]) end

print(window)
window:clear()
print(window)

-- prints AD##

Return

• none - just resets the window

__tostring

local win = sax.window.new(4, 2, 4)
for i=1,4 do win:add(1.5) end
print(win)
-- prints CC

Return

• string representing the current word in window in SAX notation

__eq

local window = sax.window.new(4, 2, 4)
local values = {1, 2, 3, 10.1}
local a, b

for i=1,4 do window:add(values[i]) end

b = sax.word.new(values, 2, 4)

print(window:get_word() == b)
print(window == b)
-- prints true true

Return

• Whether or not two words are considered equal (per-symbol, w, and c comparison)

Word methods

__tostring

local a = sax.word.new({10.3, 7, 1, -5, -5, 7.2}, 2, 8)
print(a)
-- prints FC

Return

• string representing this word in SAX notation

__eq

See window.__eq