Vector Function API

Mapping functions that given a collection of items produce an array of values (a "vector") equal in length to the collection. Typically used with mutateWithSummary.

cumsum#

Returns a function that computes a cumulative sum as per d3-array::cumsum, using d3-array::fsum to reduce floating point errors.

Parameters#

key#

| string /* key of object */
| (item: object, index: number, array: object[]) => number | null | undefined

Either the key to compute the value over or an accessor function that maps a given item to the value to compute over.

Usage#

const data = [
{ str: 'foo', value: 3, value2: 1 },
{ str: 'bar', value: 1, value2: 3 },
{ str: 'bar', value: null, value2: undefined },
{ str: 'bar', value: 5, value2: 4 },
];
tidy(
data,
mutateWithSummary({
cumsum1: cumsum('value'),
cumsum2: cumsum((d) => (d.value == null ? d.value : d.value2 * 2)),
})
);
// output:
[
{ str: 'foo', value: 3, value2: 1, cumsum1: 3, cumsum2: 2 },
{ str: 'bar', value: 1, value2: 3, cumsum1: 4, cumsum2: 8 },
{ str: 'bar', value: null, value2: undefined, cumsum1: 4, cumsum2: 8 },
{ str: 'bar', value: 5, value2: 4, cumsum1: 9, cumsum2: 16 },
]

lag#

Lags a vector by a specified offset (options.n, default 1). Useful for finding previous values to compute deltas with later. It can be convenient to use TMath::subtract andTMath::add with these values to handle nulls.

Parameters#

key#

| string /* key of object */
| (item: object, index: number, array: object[]) => any

Either the key to compute the value over or an accessor function that maps a given item to the value to compute over.

options#

{
n?: number = 1
default?: any
}
  • n = 1 The number of positions to lag by. e.g. given [1,2,3,4] a lag n of 1 would produce [undefined,1,2,3]
  • default = undefined The default value for non-existent rows (e.g. we've lagged before the first element).

Usage#

const data = [
{ str: 'foo', value: 1 },
{ str: 'foo', value: 2 },
{ str: 'bar', value: 4 },
]
tidy(
data,
mutateWithSummary({
prev1: lag('value'),
prev1_0: lag('value', { default: 0 }),
prev2: lag('value', { n: 2 }),
prev3: lag('value', { n: 3 }),
other: lag('other'),
}),
mutate({
delta1_0: (d) => d.value - d.prev1_0,
})
)
// output:
[
{ str: 'foo', value: 1, prev1: undefined, prev1_0: 0, delta1_0: 1 },
{ str: 'foo', value: 2, prev1: 1, prev1_0: 1, delta1_0: 1 },
{ str: 'bar', value: 4, prev1: 2, prev1_0: 2, prev2: 1 , delta1_0: 2 },
]

lead#

Leads a vector by a specified offset (options.n, default 1). Useful for finding next values to compute deltas with later. It can be convenient to use TMath::subtract andTMath::add with these values to handle nulls.

Parameters#

key#

| string /* key of object */
| (item: object, index: number, array: object[]) => any

Either the key to compute the value over or an accessor function that maps a given item to the value to compute over.

options#

{
n?: number = 1
default?: any
}
  • n = 1 The number of positions to lead by. e.g. given [1,2,3,4] a lead n of 1 would produce [2,3,4,undefined]
  • default = undefined The default value for non-existent rows (e.g. we've lagged before the first element).

Usage#

const data = [
{ str: 'foo', value: 1 },
{ str: 'foo', value: 2 },
{ str: 'bar', value: 4 },
]
tidy(
data,
mutateWithSummary({
next1: lead('value'),
next1_0: lead('value', { default: 0 }),
next2: lead('value', { n: 2 }),
next3: lead('value', { n: 3 }),
other: lead('other'),
}),
mutate({
delta1: (d) => TMath.subtract(d.value, d.next1),
})
)
// output:
[
{ str: 'foo', value: 1, next1: 2, next1_0: 2, next2: 4, delta1: -1 },
{ str: 'foo', value: 2, next1: 4, next1_0: 4, delta1: -2 },
{ str: 'bar', value: 4, next1: undefined, next1_0: 0, delta1: undefined },
]

roll#

Computes values over a rolling window. Typically used for calculating moving averages or running sums.

Parameters#

width#

number

The size of the window.

rollFn#

(itemsInWindow: object[], endIndex: number) => any

The function used to apply to the window, reduces to a single value for the window. Given the subset of items that are within the window as well as the ending index in the original array.

options#

{
partial?: boolean
align?: 'right' | 'center' | 'left'
}
  • partial = false If true, will compute the value even if the size of the window is less than the specified width. Otherwise, the rolled up value will be undefined.
  • align = 'right' which direction the window is aligned to (default: right, looking back)
    • right: current row is the last item [ 1, 2, 3 ]
    • left: current row is the first item [ 1, 2, 3 ]
    • center: current row is the center item [ 1, 2, 3 ]

Usage#

const data = [
{ str: 'foo', value: 3 },
{ str: 'foo', value: 1 },
{ str: 'bar', value: 3 },
{ str: 'bar', value: 1 },
{ str: 'bar', value: 7 },
];
tidy(data, mutateWithSummary({
movingAvg: roll(3, mean('value'), { partial: true }),
}))
// output:
[
{ str: 'foo', value: 3, movingAvg: 3 / 1 }, // partial
{ str: 'foo', value: 1, movingAvg: 4 / 2 }, // partial
{ str: 'bar', value: 3, movingAvg: 7 / 3 },
{ str: 'bar', value: 1, movingAvg: 5 / 3 },
{ str: 'bar', value: 7, movingAvg: 11 / 3 },
]

rowNumber#

Computes the row number for each item in the array. Note this can also be accomplished with a simple mutate, if you prefer:

mutate({ row: (_, i) => i })

Parameters#

options#

{
startAt?: number
}
  • startAt = 0 what to start counting at, default is 0 โ€“ so the first row is row 0, then row 1 for the second row.

Usage#

const data = [
{ str: 'foo', value: 3 },
{ str: 'foo', value: 1 },
{ str: 'bar', value: 3 },
{ str: 'bar', value: 1 },
{ str: 'bar', value: 7 },
];
tidy(data, mutateWithSummary({
row: rowNumber(),
rowFrom1: rowNumber({ startAt: 1})
}))
// output:
[
{ str: 'foo', value: 3, row: 0, rowFrom1: 1 },
{ str: 'foo', value: 1, row: 1, rowFrom1: 2 },
{ str: 'bar', value: 3, row: 2, rowFrom1: 3 },
{ str: 'bar', value: 1, row: 3, rowFrom1: 4 },
{ str: 'bar', value: 7, row: 4, rowFrom1: 5 },
]

Last updated on by Peter Beshai