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 },

]

---