time-series-library

A TypeScript/JavaScript library for arithmetic on Statistics Canada time series vector data.

Installation

// es6 module
import {Vector, VectorLib} from 'time-series-library';

Usage

Vector:
get(index)
refper(index), refperStr(index)
value(index)
values()
length
push(datapoint)
equals(other)
copy()
map(fn)
find(predicate)
filter(predicate)
range(startDate, endDate)
latestN(n)
interoperable(other)
intersection(others)
sum()
average()
reduce()
operate(operation)
periodDeltaTransformation(transformation)
samePeriodPreviousYearTransformation(transformation)
periodTransformation(transformation)
periodToPeriodPercentageChange(transformation)
periodToPeriodDifference()
samePeriodPreviousYearPercentageChange()
samePeriodPreviousYearDifference()
convertToFrequency(mode, converter)
weekly(mode)
monthly(mode)
biMonthly(mode)
quarterly(mode)
semiAnnual(mode)
annual(mode)
biAnnual(mode)
triAnnnual(mode)
quadrennial(mode)
quinquennial(mode)
round(decimals)
roundBankers(decimals)
json()

VectorLib:
evaluate(expression, vectors)
generateDaily(values, startDate)
generateWeekly(values, startDate)
generateMonthly(values, startDate)
generateBiMonthly(values, startDate)
generateQuarterly(values, startDate)
generateSemiAnnual(values, startDate)
generateAnnual(values, startDate)
generateBiAnnual(values, startDate)
generateTriAnnual(values, startDate)
generateQuadrennial(values, startDate)
generateQuinquennial(values, startDate)

Vector

To create a new vector:

let vector = new Vector();

Vectors can also be initialized with data:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2},
    {'refper': "2018-03-01", 'value': 3}
]);

The value of refper may be a yyyy-mm-dd formatted date string or a Date object.

Datapoints may also hold addional information in the metadata property:

let vector = let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1, 'metadata': {'key': 'value'}}
]); 

get(index)

Returns the datapoint of a vector at a specific index.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2},
    {'refper': "2018-03-01", 'value': 3}
]);

let result = vector.get(1);

Result:

{'refper': "2018-02-01", 'value': 2}

refper(index), refperStr(index)

Gets the refeperence period of a datapoint at a specific index.

The function refper returns a data object and the function refperStr returns a yyyy-mm-dd formatted date string.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2},
    {'refper': "2018-03-01", 'value': 3}
]);

let result = vector.refperStr(1);

Result:

"2018-02-01"

value(index)

Return the value of a datapoint at a specific index.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2},
    {'refper': "2018-03-01", 'value': 3}
]);

let result = vector.value(1);

Result:

2

values()

Return the list of values in a vector.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2},
    {'refper': "2018-03-01", 'value': 3}
]);

let result = vector.values();

Result:

[1, 2, 3]

length

Gets the length of a vector.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2}
]);

let result = vector.length;

Result:

2

push(datapoint)

Appends a datapoint to a vector.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1}
]);

vector.push({'refper': "2018-02-01", 'value': 2});

Result:

[
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2}
]

equals(other)

Checks if two vectors are equal.

Two vectors a and b are equal if the number of datapoints in a is equal to the number of datapoints in b, and for each datapoint with reference period Ra and value Va in a, there exists a datapoint in b whose reference period is equal to Ra and value is equal to Va.

Example:

let v1 = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2}
]);
let v2 = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2}
]);

let result = v1.equals(v2);

Result:

true

copy()

Returns a new Vector object that is a copy of the calling Vector.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2}
]);

let result = vector.copy();

Result:

[
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2}
]

map(fn)

Applies a map function, fn on each point in a vector.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 0},
    {'refper': "2018-01-02", 'value': 1},
    {'refper': "2018-01-03", 'value': 2},
]);

let result = vector.map(p => p.value);

Result:

[0, 1, 2]

find(predicate)

Returns the first datapoint in a vector matching a predicate function. Returns undefined if no match is found.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 0},
    {'refper': "2018-01-02", 'value': 1},
    {'refper': "2018-01-03", 'value': 2},
]);

let result = vector.find(p => p == 1);

Result:

{'refper': "2018-01-02", 'value': 1}

filter(predicate)

Returns a filtered vector based on a predicate function. The function predicate should be a function that operates on a datapoint and returns a boolean.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 0},
    {'refper': "2018-01-02", 'value': 1},
    {'refper': "2018-01-03", 'value': 2},
]);

let result = vector.filter(p => p.value % 2 == 0);

Result:

[
    {'refper': "2018-01-01", 'value': 0},
    {'refper': "2018-01-03", 'value': 2}
]

range(startDate, endDate)

Returns the vector constrained within a specified range. The parameters startDate and endDate may be either date strings or date objects.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 0},
    {'refper': "2018-02-01", 'value': 1},
    {'refper': "2018-03-01", 'value': 2},
    {'refper': "2018-04-01", 'value': 3}
]);

let result = vlib.range("2018-02-01", "2018-03-01");

Result:

[
    {'refper': "2018-02-01", 'value': 1},
    {'refper': "2018-03-01", 'value': 2}
]

latestN

Returns a new vector containing only the last n reference periods of the calling vector.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 0},
    {'refper': "2018-02-01", 'value': 1},
    {'refper': "2018-03-01", 'value': 2},
    {'refper': "2018-04-01", 'value': 3}
]);

let result = vlib.latestN(2);

Result:

[
    {'refper': "2018-03-01", 'value': 2},
    {'refper': "2018-04-01", 'value': 3}
]

interoperable(other)

Checks if two vectors are interoperable.

Two vectors a and b are interoperable if the number of datapoints in a is equal to the number of datapoints in b, and for each datapoint with reference period Ra in a, there exists a datapoint in b whose reference period is equal to Ra.

Example:

let v1 = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2}
]);
let v2 = new Vector([
    {'refper': "2018-01-01", 'value': 3},
    {'refper': "2018-02-01", 'value': 4}
]);

let result = v1.interoperable(v2);

Result:

true

intersection(others)

Returns the result of the intersection of the calling vector with other vectors.

The parameter others can either be a single vector or an array of vectors.

The result of vectors a intersected with b is defined as the vector a' and such that a' is composed only of datapoints with reference periods defined in both a and b.

Example:

let v1 = [
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2},
    {'refper': "2018-03-01", 'value': 3},
    {'refper': "2018-04-01", 'value': 4}
];
let v2 = [
    {'refper': "2018-01-01", 'value': 5},
    {'refper': "2018-03-01", 'value': 6}
];

let result = v1.intersection(v2);

Result:

[
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-03-01", 'value': 3}
]

sum()

Returns the sum of all values in a vector.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", value: 1},
    {'refper': "2018-02-01", value: 2},
    {'refper': "2018-03-01", value: 3},
]);

let result = vector.sum();

Result:

6

average()

Returns the average of the values in a vector.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", value: 1},
    {'refper': "2018-02-01", value: 2},
    {'refper': "2018-03-01", value: 3},
]);

let result = vector.average();

Result:

2

reduce(reducer)

Reduces the values in a vector based on the function reducer.

The function reducer has Number parameters accumulator and current and should return a Number.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 2},
    {'refper': "2018-02-01", 'value': 3},
    {'refper': "2018-02-01", 'value': 4}
]);  
let result = vector.reduce(function(accumulator, current) {
    return accumulator * current;
});

Result:

24

operate(operation)

Performs an operation with another vector. The parameter operation is a function with two Number inputs a and b that returns the result of an operation on both inputs. The input a should represent the value in the calling vector and the input b should represent the value in the other vector.

The intersection of the two vectors are taken before performing the operation.

Example:

let vectorA = new Vector([
    {'refper': "2018-01-01", 'value': 1},
    {'refper': "2018-02-01", 'value': 2}
]);

let vectorB = new Vector([
    {'refper': "2018-01-01", 'value': 3},
    {'refper': "2018-02-01", 'value': 4}
]);

let result = vectorA.operate(vectorB, (a, b) => a + b);

Result:

[
    {'refper': "2018-01-01", 'value': 4},
    {'refper': "2018-02-01", 'value': 6}  
]

periodDeltaTransformation(transformation)

Returns a new vector that is the result of a period to period transformation on the calling vector. The parameter transformation should be a function with two Number inputs representing the value of the current period and previous period and should return the transformed value.

The first datapoint of the transformed vector will have a value of null since there is no previous period to compare to.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", value: 1},
    {'refper': "2018-02-01", value: 2},
    {'refper': "2018-03-01", value: 3},
]);

let result = vector.periodDeltaTransformation(function(curr, last)  {
    return curr + last;
});  

Result:

[
    {'refper': "2018-01-01", value: null},
    {'refper': "2018-02-01", value: 3},
    {'refper': "2018-03-01", value: 5}
]

samePeriodPreviousYearTransformation(transformation)

Returns a new vector that is the result of a same period previous year transformation on the calling vector. The parameter transformation should be a function with two Number inputs representing the value of the current period and previous period and should return the transformed value.

The first few datapoints of the transformed vector will have a value of null since there is no previous year to compare to.

Example:

let vector = new Vector([
    {'refper': '2018-03-31', 'value': 1},
    {'refper': '2018-06-30', 'value': 2},
    {'refper': '2018-09-30', 'value': 3},
    {'refper': '2018-12-31', 'value': 4},
    {'refper': '2019-03-31', 'value': 5},
    {'refper': '2019-06-30', 'value': 6},
    {'refper': '2019-09-30', 'value': 7},
    {'refper': '2019-12-31', 'value': 8}
]);

let result = vector.samePeriodPreviousYearTransformation(function(curr, last)  {
    return curr - last;
});  

Result:

[
    {'refper': '2018-03-31', 'value': null},
    {'refper': '2018-06-30', 'value': null},
    {'refper': '2018-09-30', 'value': null},
    {'refper': '2018-12-31', 'value': null},
    {'refper': '2019-03-31', 'value': 4},
    {'refper': '2019-06-30', 'value': 4},
    {'refper': '2019-09-30', 'value': 4},
    {'refper': '2019-12-31', 'value': 4}
]

periodTransformation(transformation)

Returns a new vector that is the result of period transformation on the calling vector. The parameter transformation should be a function with a Number input representing the value of the current period and should return the transformed value.

The first datapoint of the transformed vector will have a value of null since there is no previous period to compare to.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", value: 1},
    {'refper': "2018-02-01", value: 2},
    {'refper': "2018-03-01", value: 3}
]);

let result = vector.periodTransformation(function(value)  {
    return value * 2;
});  

Result:

[
    {'refper': "2018-01-01", value: 2},
    {'refper': "2018-02-01", value: 4},
    {'refper': "2018-03-01", value: 6}
]

periodToPeriodPercentageChange()

Returns a period-to-period percentage change vector of the calling vector.

Example:

let vector = new Vector([
    {'refper': '2018-01-01', 'value': 2},
    {'refper': '2018-02-01', 'value': 6},
    {'refper': '2018-03-01', 'value': 3}
]);

let result = vector.periodToPeriodPercentageChange();

Result:

[
    {'refper': "2018-01-01", 'value': null},
    {'refper': "2018-02-01", 'value': 200.0},
    {'refper': "2018-03-01", 'value': -50.0}
]

periodToPeriodDifference()

Returns a period-to-period difference vector of the calling vector.

Example:

let vector = new Vector([
    {'refper': '2018-01-01', 'value': 2},
    {'refper': '2018-02-01', 'value': 6},
    {'refper': '2018-03-01', 'value': 3}
]);

let result = vector.periodToPeriodDifference();

Result:

[
    {'refper': "2018-01-01", 'value': null},
    {'refper': "2018-02-01", 'value': 4},
    {'refper': "2018-03-01", 'value': -3}
]

samePeriodPreviousYearPercentageChange()

Returns the same period previous year percentage change vector of the calling vector.

Note: Only works for vectors with frequencies of monthly of lower.

Example:

let vector = new Vector([
    {'refper': '2018-06-01', 'value': 1},
    {'refper': '2018-12-01', 'value': 2},
    {'refper': '2019-06-01', 'value': 4},
    {'refper': '2019-12-01', 'value': 8},
    {'refper': '2020-06-01', 'value': 4},
    {'refper': '2020-12-01', 'value': 4}
]);

let result = vector.samePeriodPreviousYearPercentageChange();

Result:

[
    {'refper': '2018-06-01', 'value': null},
    {'refper': '2018-12-01', 'value': null},
    {'refper': '2019-06-01', 'value': 300.0},
    {'refper': '2019-12-01', 'value': 300.0},
    {'refper': '2020-06-01', 'value': 0},
    {'refper': '2020-12-01', 'value': -50.0}
]

samePeriodPreviousYearDifference()

Returns the same period previous year difference vector of the calling vector.

Note: Only works for vectors with frequencies of monthly of lower.

Example:

let vector = new Vector([
    {'refper': '2018-06-01', 'value': 0},
    {'refper': '2018-12-01', 'value': 2},
    {'refper': '2019-06-01', 'value': 0},
    {'refper': '2019-12-01', 'value': 6},
    {'refper': '2020-06-01', 'value': 0},
    {'refper': '2020-12-01', 'value': 4}
]);

let result = vector.samePeriodPreviousYearPercentageChange();

Result:

[
    {'refper': '2018-06-01', 'value': null},
    {'refper': '2018-12-01', 'value': null},
    {'refper': '2019-06-01', 'value': 0},
    {'refper': '2019-12-01', 'value': 4},
    {'refper': '2020-06-01', 'value': 0},
    {'refper': '2020-12-01', 'value': -2}
]

convertToFrequency(mode, converter)

Converts the frequency of a vector to a user defined frequency.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each user defined frequency (Default).
• "sum": Takes the sum of each user defined frequency.
• "average": Takes the average of each user defined frequency.
• "max": Takes the maximum value of each user defined frequency.
• "min": Takes the minimum value of each user defined frequency.

The parameter conveter is a function with date parameters curr and last and a Boolean return value. This function should return true when curr and last are the defined frequency apart.

Note: For the mode of operation, the vector is split into chunks where each chunk starts when the converter returns true. This operation starts from the last reference period of the vector and proceeds in descending order by time. Any chunk that does not have the same size as the latest chunk will be removed.

Example:

let vector = new Vector([
    {'refper': '2018-12-01', value: 1},
    {'refper': '2018-12-12', value: 2},
    {'refper': '2019-01-01', value: 3},
    {'refper': '2019-01-12', value: 4},
    {'refper': '2019-02-01', value: 5},
    {'refper': '2019-02-12', value: 6}
]);

let result = vector.convertToFrequency('last', function(curr, last) {
    // Define frequency as monthly.
    return curr.getMonth() === (last.getMonth() + 1) % 12;
});

Result:

[
    {'refper': '2018-12-12', value: 2},
    {'refper': '2019-01-12', value: 4},
    {'refper': '2019-02-12', value: 6}
]

weekly(mode)

Converts the frequency of a vector to weekly.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each week (Default).
• "sum": Takes the sum of each week.
• "average": Takes the average of each week.
• "max": Takes the maximum value of each week.
• "min": Takes the minimum value of each week.

Example:

let vector = new Vector([
    {'refper': '2019-02-11', value: 1},
    {'refper': '2018-02-12', value: 2},
    {'refper': '2019-02-13', value: 3},
    {'refper': '2019-02-14', value: 4},
    {'refper': '2019-02-15', value: 5},
    {'refper': '2019-02-18', value: 6},
    {'refper': '2019-02-19', value: 7},
    {'refper': '2019-02-20', value: 8},
    {'refper': '2019-02-21', value: 9},
    {'refper': '2019-02-22', value: 10},
    {'refper': '2019-02-25', value: 11}
]);

let result = vector.weekly();

Result:

[
    {'refper': '2019-02-15', value: 5},
    {'refper': '2019-02-22', value: 10}
]

monthly(mode)

Converts the frequency of a vector to monthly.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each month (Default).
• "sum": Takes the sum of each month.
• "average": Takes the average of each month.
• "max": Takes the maximum value of each month.
• "min": Takes the minimum value of each month.

Example:

    let vector = new Vector([
        {'refper': '2018-12-01', value: 1},
        {'refper': '2018-12-12', value: 2},
        {'refper': '2019-01-01', value: 3},
        {'refper': '2019-01-12', value: 4},
        {'refper': '2019-02-01', value: 5},
        {'refper': '2019-02-12', value: 6}
    ]);

    let result = vector.monthly();

Result:

[
    {'refper': '2018-12-12', value: 2},
    {'refper': '2019-01-12', value: 4},
    {'refper': '2019-02-12', value: 6}
]

biMonthly(mode)

Converts the frequency of a vector to bi-monthly.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each two month period (Default).
• "sum": Takes the sum of each two month period.
• "average": Takes the average of each two month period.
• "max": Takes the maximum value of each two month period.
• "min": Takes the minimum value of each two month period.

Example:

    let vector = new Vector([
        {'refper': '2018-01-01', value: 1},
        {'refper': '2018-02-01', value: 2},
        {'refper': '2019-03-01', value: 3},
        {'refper': '2019-04-01', value: 4},
        {'refper': '2019-05-01', value: 5},
        {'refper': '2019-06-01', value: 6}
    ]);

    let result = vector.biMonthly();

Result:

[
    {'refper': '2018-02-01', value: 2},
    {'refper': '2019-04-01', value: 4},
    {'refper': '2019-06-01', value: 6}
]

quarterly(mode)

Converts the frequency of a vector to quarterly.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each quarter (Default).
• "sum": Takes the sum of each quarter.
• "average": Takes the average of each quarter.
• "max": Takes the maximum value of each quarter.
• "min": Takes the minimum value of each quarter.

Example:

let vector = new Vector([
    {'refper': '2018-01-01', value: 1},
    {'refper': '2018-02-01', value: 2},
    {'refper': '2019-03-01', value: 3},
    {'refper': '2019-04-01', value: 4},
    {'refper': '2019-05-01', value: 5},
    {'refper': '2019-06-01', value: 6},
    {'refper': '2019-07-01', value: 7},
    {'refper': '2019-08-01', value: 8},
    {'refper': '2019-09-01', value: 9},
    {'refper': '2019-10-01', value: 10},
    {'refper': '2019-11-01', value: 11},
    {'refper': '2019-12-01', value: 12}
]);

let result = vector.quarterly();

Result:

[
    {'refper': '2019-03-01', value: 3},
    {'refper': '2019-06-01', value: 6},
    {'refper': '2019-09-01', value: 9},
    {'refper': '2019-12-01', value: 12}
]

semiAnnual(mode)

Converts the frequency of a vector to semi-annual.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each semi-annum (Default).
• "sum": Takes the sum of each semi-annum.
• "average": Takes the average of each semi-annum.
• "max": Takes the maximum value of each semi-annum.
• "min": Takes the minimum value of each seni-annum.

Example:

let vector = new Vector([
    {'refper': '2018-01-01', value: 1},
    {'refper': '2018-02-01', value: 2},
    {'refper': '2019-03-01', value: 3},
    {'refper': '2019-04-01', value: 4},
    {'refper': '2019-05-01', value: 5},
    {'refper': '2019-06-01', value: 6},
    {'refper': '2019-07-01', value: 7},
    {'refper': '2019-08-01', value: 8},
    {'refper': '2019-09-01', value: 9},
    {'refper': '2019-10-01', value: 10},
    {'refper': '2019-11-01', value: 11},
    {'refper': '2019-12-01', value: 12}
]);

let result = vector.semiAnnual();

Result:

[
    {'refper': '2019-06-01', value: 6},
    {'refper': '2019-12-01', value: 12}
]

annual(mode)

Converts the frequency of a vector to annual.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each year (Default).
• "sum": Takes the sum of each year.
• "average": Takes the average of each year.
• "max": Takes the maximum value of each year.
• "min": Takes the minimum value of each year.

Example:

let vector = new Vector([
    {'refper': "2018-06-01", 'value': 0},
    {'refper': "2018-12-01", 'value': 1},
    {'refper': "2019-06-01", 'value': 2},
    {'refper': "2019-12-01", 'value': 3},
    {'refper': "2020-06-01", 'value': 4},
    {'refper': "2020-12-01", 'value': 5}
]);

let result = vector.annual();

Result:

[
    {'refper': "2018-12-01", 'value': 1},
    {'refper': "2019-12-01", 'value': 3},
    {'refper': "2020-12-01", 'value': 5}
]

biAnnual(mode)

Converts the frequency of a vector to bi-annual.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each bi-annum (Default).
• "sum": Takes the sum of each bi-annum.
• "average": Takes the average of each bi-annum.
• "max": Takes the maximum value of each bi-annum.
• "min": Takes the minimum value of each bi-annum.

Example:

let vector = new Vector([
    {'refper': "2018-12-01", 'value': 0},
    {'refper': "2019-12-01", 'value': 1},
    {'refper': "2020-12-01", 'value': 2},
    {'refper': "2021-12-01", 'value': 3},
    {'refper': "2022-12-01", 'value': 4},
    {'refper': "2023-12-01", 'value': 5}
]);

let result = vector.biAnnual();

Result:

[
    {'refper': "2019-12-01", 'value': 1},
    {'refper': "2021-12-01", 'value': 3},
    {'refper': "2023-12-01", 'value': 5}
]

triAnnual(mode)

Converts the frequency of a vector to tri-annual.

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each tri-annum (Default).
• "sum": Takes the sum of each tri-annum.
• "average": Takes the average of each tri-annum.
• "max": Takes the maximum value of each tri-annum.
• "min": Takes the minimum value of each tri-annum.

Example:

let vector = new Vector([
    {'refper': "2018-12-01", 'value': 0},
    {'refper': "2019-12-01", 'value': 1},
    {'refper': "2020-12-01", 'value': 2},
    {'refper': "2021-12-01", 'value': 3},
    {'refper': "2022-12-01", 'value': 4},
    {'refper': "2023-12-01", 'value': 5}
]);

let result = vector.triAnnual();

Result:

[
    {'refper': "2020-12-01", 'value': 2},
    {'refper': "2023-12-01", 'value': 5}
]

quadrennial(mode)

Converts the frequency of a vector to quadrennial (every 4 years).

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each quadrennium (Default).
• "sum": Takes the sum of each quadrennium.
• "average": Takes the average of each quadrennium.
• "max": Takes the maximum value of each quadrennium.
• "min": Takes the minimum value of each quadrennium.

Example:

let vector = new Vector([
    {'refper': "2018-12-01", 'value': 0},
    {'refper': "2019-12-01", 'value': 1},
    {'refper': "2020-12-01", 'value': 2},
    {'refper': "2021-12-01", 'value': 3},
    {'refper': "2022-12-01", 'value': 4},
    {'refper': "2023-12-01", 'value': 5},
    {'refper': "2024-12-01", 'value': 6},
    {'refper': "2025-12-01", 'value': 7},
    {'refper': "2026-12-01", 'value': 8},
    {'refper': "2027-12-01", 'value': 9}
]);

let result = vector.quadrennial();

Result:

[
    {'refper': '2022-01-31', 'value': 5},
    {'refper': '2026-01-31', 'value': 9},
    {'refper': '2030-01-31', 'value': 13}
]

quinquennial(mode)

Converts the frequency of a vector to quinquennial (every 5 years).

The parameter mode is optional and can be one of the following strings:

• "last": Takes the last reference period of each quinquennium (Default).
• "sum": Takes the sum of each quinquennium.
• "average": Takes the average of each quinquennium.
• "max": Takes the maximum value of each quinquennium.
• "min": Takes the minimum value of each quinquennium.

Example:

let vector = new Vector([
    {'refper': "2018-12-01", 'value': 0},
    {'refper': "2019-12-01", 'value': 1},
    {'refper': "2020-12-01", 'value': 2},
    {'refper': "2021-12-01", 'value': 3},
    {'refper': "2022-12-01", 'value': 4},
    {'refper': "2023-12-01", 'value': 5},
    {'refper': "2024-12-01", 'value': 6},
    {'refper': "2025-12-01", 'value': 7},
    {'refper': "2026-12-01", 'value': 8},
    {'refper': "2027-12-01", 'value': 9}
]);

let result = vector.quinquennial();

Result:

[
    {'refper': "2022-12-01", 'value': 4},
    {'refper': "2027-12-01", 'value': 9}
]

round(decimals)

Returns a new vector with all values in the calling vector roudned to a specified number of decimal places.

If decimals is not specified then the default value of 0 will be used.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1.555},
    {'refper': "2018-02-01", 'value': 1.554}
]);

let result = vector.round(2);

Result:

[
    {'refper': "2018-01-01", 'value': 1.56},
    {'refper': "2018-02-01", 'value': 1.55}
]

roundBankers(decimals)

Returns a new vector with all values in the calling vector rounded to a specified number of decimal places using the Banker's rounding algorithm.

If decimals is not specified then the default value of 0 will be used.

Example:

let vector = new Vector([
    {'refper': "2018-01-01", 'value': 1.5},
    {'refper': "2018-02-01", 'value': 2.5}
]);

let result = vector.roundBankers(0);

Result:

[
    {'refper': "2018-01-01", 'value': 2},
    {'refper': "2018-02-01", 'value': 2}
]

json()

Converts a vector to a JSON formatted array.

Example:

let vector = new Vector([
    {'refper': '2018-01-01', 'value': 1},
    {'refper': '2018-02-01', 'value': 2}
]);
let result = vector.json();

Result:

[
    {"refper": "2018-01-01", "value": 1},
    {"refper": "2018-02-01", "value": 2}
]

VectorLib

evaluate(expression, vectors)

Performs arithmetic on a set of vectors. This function returns a Vector object.

All input vectors will be intersected with each other before performing an operation using the intersection function.

Example:

let vectors = {
    '1': new Vector([
        {'refper': "2018-01-01", 'value': 1},
        {'refper': "2018-02-01", 'value': 2}
    ]),
    '2': new Vector([
        {'refper': "2018-01-01", 'value': 3},
        {'refper': "2018-02-01", 'value': 4}
    ]),
    '3': new Vector([
        {'refper': "2018-01-01", 'value': 2},
        {'refper': "2018-02-01", 'value': 2}
    ])
};

let result = vlib.evaluate("(v1 + 2*v2) * v3", vectors);

Result:

[
    {'refper': "2018-01-01", 'value': 16},
    {'refper': "2018-02-01", 'value': 24}
]

generateDaily(values, startDate)

Generates a daily vector from a list of values starting from a specific reference period.

Example:

let result = generateDaily([1, 2, 3], '2019-01-01');

Result:

[
    {'refper': "2019-01-01", 'value': 1},
    {'refper': "2019-01-02", 'value': 2},
    {'refper': "2019-01-03", 'value': 3}
]

generateWeekly(values, startDate)

Generates a weekly vector from a list of values starting from a specific reference period.

Example:

let result = generateWeekly([1, 2, 3], '2019-01-01');

Result:

[
    {'refper': "2019-01-01", 'value': 1},
    {'refper': "2019-01-08", 'value': 2},
    {'refper': "2019-01-15", 'value': 3}
]

generateMonthly(values, startDate)

Generates a monthly vector from a list of values starting from a specific reference period. The last day of each month will be used as the reference periods.

Example:

let result = generateMonthly([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2019-01-31", 'value': 1},
    {'refper': "2019-02-28", 'value': 2},
    {'refper': "2019-03-31", 'value': 3}
]

generateMonthly(values, startDate)

Generates a bi-monthly vector from a list of values starting from a specific reference period. The last day of each month will be used as the reference periods.

Example:

let result = generateBiMonthly([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2019-01-31", 'value': 1},
    {'refper': "2019-03-31", 'value': 2},
    {'refper': "2019-05-31", 'value': 3}
]

generateQuarterly(values, startDate)

Generates a quarterly vector from a list of values starting from a specific reference period. The last day of each month will be used as the reference periods.

Example:

let result = generateQuarterly([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2019-01-31", 'value': 1},
    {'refper': "2019-04-30", 'value': 2},
    {'refper': "2019-07-31", 'value': 3}
]

generateSemiAnnual(values, startDate)

Generates a semi annual vector from a list of values starting from a specific reference period. The last day of each month will be used as the reference periods.

Example:

let result = generateSemiAnnual([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2019-01-31", 'value': 1},
    {'refper': "2019-07-31", 'value': 2},
    {'refper': "2020-01-31", 'value': 3}
]

generateAnnual(values, startDate)

Generates an annual vector from a list of values starting from a specific reference period. The last day of each year will be used as the reference periods.

Example:

let result = generateAnnual([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2019-01-31", 'value': 1},
    {'refper': "2020-01-31", 'value': 2},
    {'refper': "2021-01-31", 'value': 3}
]

generateBiAnnual(values, startDate)

Generates a bi-annual vector from a list of values starting from a specific reference period. The last day of each year will be used as the reference periods.

Example:

let result = generateBiAnnual([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2019-01-31", 'value': 1},
    {'refper': "2021-01-31", 'value': 2},
    {'refper': "2023-01-31", 'value': 3}
]

generateTriAnnual(values, startDate)

Generates a tri-annual vector from a list of values starting from a specific reference period. The last day of each year will be used as the reference periods.

Example:

let result = generateTriAnnual([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2020-01-31", 'value': 1},
    {'refper': "2023-01-31", 'value': 2},
    {'refper': "2026-01-31", 'value': 3}
]

generateQuadrennial(values, startDate)

Generates a quadrennial vector from a list of values starting from a specific reference period. The last day of each year will be used as the reference periods.

Example:

let result = generateQuadrennial([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2019-01-31", 'value': 1},
    {'refper': "2023-01-31", 'value': 2},
    {'refper': "2027-01-31", 'value': 3}
]

generateQuinquennial(values, startDate)

Generates a quinquennial vector from a list of values starting from a specific reference period. The last day of each year will be used as the reference periods.

Example:

let result = generateQuinquennial([1, 2, 3], '2019-01-31');

Result:

[
    {'refper': "2019-01-31", 'value': 1},
    {'refper': "2024-01-31", 'value': 2},
    {'refper': "2029-01-31", 'value': 3}
]