conditions-over-interval v0.0.1

Conditions Over Interval

Overview

This package is a collection of functions for dealing with varaible logs which are data structures of the form:

{
    varA: [{t: 123, value: 99}, {t: 123, value: 88}, ...],
    varB: [{t: 156, value: 'A'}, ...],
    ...
}

That is, a collection of variables that change values at different instants in time. There can be any number of variables in the object and they can take any kind of value.

Given a data structure like this it is possible to query things such as:

• What the value of the variables are at a given moment in time
• How many unique combinations of variables there are
• For what duration of time is a given condition true

Interface

LogCollection

The main interface to the module is the LogCollection constructor. This takes an object defining the variable logs and exposes functions to query.

IMPORTANT!: It is assumed that the variable logs are sorted ascending by t. This will not work otherwise

examples:

const logCollection = LogCollection({}) // empty collection

// a collection with some varaibles defined at certain times.
// It is implied that the variables remain the same between measurements
const logCollection = LogCollection({
    internalTemp: [{ t: 23000123, value: 23}, ...],
    airconSetpoint: [{ t: 23000100, value: 20}, { t: 23000500, value: 22}]
})

LogCollection.contextAt(t)

Compute the context (which is an assignment of variables) at a particular point in time. Returns a context object which contains a field for each of the variables in the log. Variables that have not been assigned a value at that time will be undefined.

const logCollection = LogCollection({
    x: [{ t: 10, value: 'a'}],
    y: [{ t: 20, value: 3}]
})
logCollection.contextAt(9) // { x: undefined, y: undefined }
logCollection.contextAt(15) // { x: 'a', y: undefined }
logCollection.contextAt(21) // { x: 'a', y: 3 }

Condition

A Condition defines a set of required variables and optinally a function of them that returns a boolean. The function accepts a context object (see above), which is an object containg a value for each variable aggregated from the log at some point in time.

This module also exposes a constructor for conditions

examples:

const cond = Condition([]) // requries no variables, always true

const cond = Condition(['x']) // requries x be defined, always true

const cond = Condition(['x', 'y'], ({ x, y }) => x === 3*y)
// requries x and y be defined and x equal triple y

LogCollection.canEvaluate(condition, interval)

Computes if a particular condition can be evaluated over a given interval. A condition can be defined if all its varaibles are defined for the entire duration of the interval i0

const logCollection = LogCollection({
    x: [{ t: 10, value: 'a'}],
    y: [{ t: 20, value: 3}]
})
const cond = Condition(['x', 'y'])
logCollection.canEvaluate(cond, {start: 0, end: 10}) // false
logCollection.canEvaluate(cond, {start: 22, end: 30}) // true

LogCollection.rangesWhereTrue(condition, options)

Computes the time intervals for which a condition evaluates to true. By default this will merge adjacent intervals so a condition that is always true will return a single range ({start: null, end: null} === ALL_TIME). Setting options.mergeAdjacent to false will preserve the boundaries defined by the log.

const logCollection = LogCollection({
    x: [{ t: 10, value: 'a'}],
    y: [{ t: 20, value: 'a'}]
})
const cond = Condition(['x', 'y'], ({ x, y }) => x === y)
logCollection.rangesWhereTrue(cond) // [Interval{start: 20, end: null}] // unbounded interval

LogCollection.matchingBlocksOfDuration(condition, size, end)

Search for blocks of size size for which the condition is true. As often the resulting intervals are right unbounded there is an optional end param (in the example it is 30) which limits the search at that value.

A possible use case for this is searching historical logs for durations of time when a condition was met. For example a customer might receive a reward if they statisfy some conditions for a duration of time.

  const logCollection = LogCollection({
    x: [{ t: 10, value: 'a' }],
    y: [{ t: 20, value: 'a' }]
  })
  const cond = Condition(['x', 'y'], ({ x, y }) => x === 'a' && y === 'a')
  const result = logCollection.matchingBlocksOfDuration(cond, 5, 30) 
  // [
  //   Interval(20, 25),
  //   Interval(25, 30)
  // ]