# Item Function API

Mapping functions that map from a single item (or row) to a value. Typically used with mutate.

## rate#

Returns a function that computes a rate (numerator / denominator), setting the value to 0 if denominator = 0 and numerator = 0. If denominator or numerator are nully, the result is undefined.

### Parameters#

#### `numerator`#

| string /* key of object */
| (item: object) => number

Either a key of the object or an accessor function that returns a number given the object. This will be used as the numerator when computing the rate.

#### `denominator`#

| string /* key of object */
| (item: object) => number

Either a key of the object or an accessor function that returns a number given the object. This will be used as the denominator when computing the rate.

#### `options?`#

{
predicate?: (item: object) => boolean
allowDivideByZero?: boolean
}
• `allowDivideByZero = false`: If true, evaluates division when denominator is 0 (typically resulting in Infinity), otherwise rates with 0 denominators are `undefined`.
• `predicate`: Optional parameter that when provided will return undefined as the value of the rate when the predicate function returns false. This is typically used for only computing rates when there is sufficient sample size (i.e., checking if the denominator is large enough). For example:
rate('numerator', 'denominator', { predicate: d => d.denominator > 1000 })

### Usage#

const data = [
{ str: 'foo', value: 3, value2: 0 },
{ str: 'foo', value: 1, value2: 1 },
{ str: 'bar', value: 3, value2: null },
{ str: 'bar', value: null, value2: 4 },
{ str: 'bar', value: 0, value2: 0 },
{ str: 'bar', value: 7, value2: 35 },
];
tidy(
data,
mutate({
rate1: rate(
(d) => d.value * 100,
(d) => d.value2
),
rate2: rate('value', 'value2'),
})
)
// output:
[
{ str: 'foo', value: 3, value2: 0, rate1: Infinity, rate2: Infinity },
{ str: 'foo', value: 1, value2: 1, rate1: 100, rate2: 1 },
{ str: 'bar', value: 3, value2: null, rate1: undefined, rate2: undefined, },
{ str: 'bar', value: null, value2: 4, rate1: 0, rate2: undefined },
{ str: 'bar', value: 0, value2: 0, rate1: 0, rate2: 0 },
{ str: 'bar', value: 7, value2: 35, rate1: 20, rate2: 0.2 },
]

Last updated on by Peter Beshai