Tidy JS

https://pbeshai.github.io/tidy/
Admin
Tidy.js is a JavaScript library for data wrangling and transformation, providing readable,...
Tokens:57,805
Snippets:303
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install @tidyjs/tidy Package

Source: https://pbeshai.github.io/tidy/genai-docs/index.md

Install the @tidyjs/tidy package using npm. This is the first step to using the library in your project.

```bash
npm install @tidyjs/tidy
```

--------------------------------

### Selectors API - startsWith

Source: https://pbeshai.github.io/tidy/docs/api/selectors

Returns all keys that start with the specified substring. Case-insensitive by default.

```APIDOC
## startsWith

### Description
Returns all keys that start with the specified substring.

### Parameters
#### `prefix` (string) - Required - The prefix that must exist in the keys.
#### `ignoreCase` (boolean) - Optional - If true, matches without considering whether letters are upper or lower case (default: true).

### Usage
```javascript
const data = [
  { foo: 1, bar: 20, foobar: 300, FoObAR: 90 },
];

tidy(data, select([startsWith('bAR')]))
// output:
[{ foobar: 300, FoObAR: 90 }]

tidy(data, select([startsWith('bAR', false)]))
// output:
[{ FoObAR: 90 }]
```
```

--------------------------------

### Install Tidy.js with npm or yarn

Source: https://pbeshai.github.io/tidy/docs/getting_started

Use npm or yarn to add the Tidy.js library to your project.

```bash
npm install @tidyjs/tidy
```

```bash
yarn add @tidyjs/tidy
```

--------------------------------

### Inner Join Example with TidyJS

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Demonstrates an inner join operation using TidyJS with different 'by' configurations. Requires 'tidy' and 'innerJoin' functions.

```javascript
const data = [  
  { a: 1, J: 'j', b: 10, c: 100 },  
  { a: 1, J: 'k', b: 60, c: 600 },  
  { a: 1, J: 'J', b: 30, c: 300 },  
  { a: 2, J: 'j', b: 20, c: 200 },  
  { a: 3, J: 'x', b: 50, c: 500 },  
];  

const joinData = [  
  { a: 1, J: 'j', altJ: 'j', x: 'x1', y: 'y1' },  
  { a: 1, J: 'J', altJ: 'J', x: 'x9', y: 'y9' },  
  { a: 2, J: 'j', altJ: 'j', x: 'x2', y: 'y2' },  
];  

tidy(data, innerJoin(joinData, { by: ['a', 'J'] }));  
// output:  
[  
  { a: 1, J: 'j', altJ: 'j', b: 10, c: 100, x: 'x1', y: 'y1' },  
  { a: 1, J: 'J', altJ: 'J', b: 30, c: 300, x: 'x9', y: 'y9' },  
  { a: 2, J: 'j', altJ: 'j', b: 20, c: 200, x: 'x2', y: 'y2' },  
]   
```

```javascript
tidy(data, innerJoin(joinData, { by: { a: 'a', altJ: 'J' } }))  
// output:  
[  
  { a: 1, J: 'j', altJ: 'j', b: 10, c: 100, x: 'x1', y: 'y1' },  
  { a: 1, J: 'J', altJ: 'J', b: 30, c: 300, x: 'x9', y: 'y9' },  
  { a: 2, J: 'j', altJ: 'j', b: 20, c: 200, x: 'x2', y: 'y2' },  
]   
```

--------------------------------

### Full Join Example with TidyJS

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Demonstrates a full join operation using TidyJS with different 'by' configurations. Ensure the 'tidy' and 'fullJoin' functions are imported.

```javascript
tidy([{ a: 1, b: 2 }, { a: 2, b: 5 }],  
  fullJoin(  
    [{ a: 1, c: 3 }, { a: 4, c: 4 }],  
    { by: 'a' }  
  )  
)
// output:  
[  
  { a: 1, b: 2, c: 3 },  
  { a: 2, b: 5 },  
  { a: 4, c: 4 },  
];  
```

```javascript
const data = [  
  { a: 1, J: 'j', b: 10, c: 100 },  
  { a: 1, J: 'k', b: 60, c: 600 },  
  { a: 1, J: 'J', b: 30, c: 300 },  
  { a: 2, J: 'j', b: 20, c: 200 },  
  { a: 3, J: 'x', b: 50, c: 500 },  
];  

const joinData = [  
  { a: 1, J: 'j', altJ: 'j', x: 'x1', y: 'y1' },  
  { a: 1, J: 'J', altJ: 'J', x: 'x9', y: 'y9' },  
  { a: 2, J: 'j', altJ: 'j', x: 'x2', y: 'y2' },  
  { a: 2, J: 'X', altJ: 'x', x: 'x5', y: 'y5' },  
];  

tidy(data, fullJoin(joinData, { by: ['a', 'J'] }));
// output:  
[  
  { a: 1, J: 'j', altJ: 'j', b: 10, c: 100, x: 'x1', y: 'y1' },  
  { a: 1, J: 'k', b: 60, c: 600 },  
  { a: 1, J: 'J', altJ: 'J', b: 30, c: 300, x: 'x9', y: 'y9' },  
  { a: 2, J: 'j', altJ: 'j', b: 20, c: 200, x: 'x2', y: 'y2' },  
  { a: 3, J: 'x', b: 50, c: 500 },  
  { a: 2, J: 'X', altJ: 'x', x: 'x5', y: 'y5' },  
]   
```

```javascript
tidy(data, fullJoin(joinData, { by: { a: 'a', altJ: 'J' } }))  
// output:  
[  
  { a: 1, J: 'j', altJ: 'j', b: 10, c: 100, x: 'x1', y: 'y1' },  
  { a: 1, J: 'k', b: 60, c: 600 },  
  { a: 1, J: 'J', altJ: 'J', b: 30, c: 300, x: 'x9', y: 'y9' },  
  { a: 2, J: 'j', altJ: 'j', b: 20, c: 200, x: 'x2', y: 'y2' },  
  { a: 3, J: 'x', b: 50, c: 500 },  
  { a: 2, J: 'X', altJ: 'x', x: 'x5', y: 'y5' },  
]   
```

--------------------------------

### Advanced Pivoting with Multiple Columns and Value Filling

Source: https://pbeshai.github.io/tidy/docs/api/pivot

This example demonstrates pivoting wider using multiple columns for names and values, and also specifies how to fill missing values using `valuesFillMap`. This is useful when dealing with complex data structures or when you need to ensure all potential columns are present with default values.

```javascript
const data = [
  { type: 'one', other: 5, place: 'canada', val: 1, secval: 91 },
  { type: 'one', other: 5, place: 'usa', val: 10, secval: 910 },
  { type: 'one', other: 6, place: 'campbell', val: 4, secval: 94 },
  { type: 'one', other: 6, place: 'brampton', val: 8, secval: 98 },
  { type: 'two', other: 5, place: 'brampton', val: 7, secval: 97 },
  { type: 'two', other: 5, place: 'boston', val: 3, secval: 93 },
  { type: 'two', other: 6, place: 'usa', val: 11, secval: 911 },
  { type: 'three', other: 5, place: 'canada', val: 20, secval: 920 },
];

const results = tidy(
  data,
  pivotWider({
    namesFrom: ['place', 'other'],
    valuesFrom: ['val', 'secval'],
    valuesFillMap: { val: 0, secval: -1 },
  })
);
// output:
[{ 
  secval_boston_5: -1,
  secval_boston_6: -1,
  secval_brampton_5: -1,
  secval_brampton_6: 98,
  secval_campbell_5: -1,
  secval_campbell_6: 94,
  secval_canada_5: 91,
  secval_canada_6: -1,
  secval_usa_5: 910,
  secval_usa_6: -1,
  type: 'one',
  val_boston_5: 0,
  val_boston_6: 0,
  val_brampton_5: 0,
  val_brampton_6: 8,
  val_campbell_5: 0,
  val_campbell_6: 4,
  val_canada_5: 1,
  val_canada_6: 0,
  val_usa_5: 10,
  val_usa_6: 0,
},
{
  secval_boston_5: 93,
  secval_boston_6: -1,
  secval_brampton_5: 97,
  secval_brampton_6: -1,
  secval_campbell_5: -1,
  secval_campbell_6: -1,
  secval_canada_5: -1,
  secval_canada_6: -1,
  secval_usa_5: -1,
  secval_usa_6: 911,
  type: 'two',
  val_boston_5: 3,
  val_boston_6: 0,
  val_brampton_5: 7,
  val_brampton_6: 0,
  val_campbell_5: 0,
  val_campbell_6: 0,
  val_canada_5: 0,
  val_canada_6: 0,
  val_usa_5: 0,
  val_usa_6: 11,
},
{
  secval_boston_5: -1,
  secval_boston_6: -1,
  secval_brampton_5: -1,
  secval_brampton_6: -1,
  secval_campbell_5: -1,
  secval_campbell_6: -1,
  secval_canada_5: 920,
  secval_canada_6: -1,
  secval_usa_5: -1,
  secval_usa_6: -1,
  type: 'three',
  val_boston_5: 0,
  val_boston_6: 0,
  val_brampton_5: 0,
  val_brampton_6: 0,
  val_campbell_5: 0,
  val_campbell_6: 0,
  val_canada_5: 20,
  val_canada_6: 0,
  val_usa_5: 0,
  val_usa_6: 0,
}]

```

--------------------------------

### Start a Tidy Flow with tidy()

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Use tidy() to initiate a data wrangling pipeline. It accepts a flat array of items and chains multiple tidy functions sequentially. The last function can be groupBy with export options.

```javascript
const data = [
  { str: 'foo', value: 3 },
  { str: 'foo', value: 3 },
  { str: 'foo', value: 1 },
  { str: 'bar', value: 3 },
  { str: 'bar', value: 1 },
  { str: 'bar', value: 1 },
  { str: 'foo', value: 3 },
  { str: 'bar', value: 7 },
];

tidy(
  data,
  distinct(['str', 'value']),
  filter((d) => d.value <= 3),
  summarize({ summedValue: sum('value') })
);
// output:
[{ summedValue: 8 }]
```

--------------------------------

### Example of using rate function with mutate

Source: https://pbeshai.github.io/tidy/docs/api/item

Demonstrates how to use the 'rate' function within 'mutate' to calculate two different rates based on item properties. Handles cases where denominators are zero or null.

```javascript
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 },
]
```

--------------------------------

### Group data by a single key

Source: https://pbeshai.github.io/tidy/docs/api/groupby

Use groupBy with a single string key to group data. This example groups by 'str' and summarizes the 'value' for each group.

```javascript
const data = [
  { str: 'a', ing: 'x', foo: 'G', value: 1 },
  { str: 'b', ing: 'x', foo: 'H', value: 100 },
  { str: 'b', ing: 'x', foo: 'K', value: 200 },
  { str: 'a', ing: 'y', foo: 'G', value: 2 },
  { str: 'a', ing: 'y', foo: 'H', value: 3 },
  { str: 'a', ing: 'y', foo: 'K', value: 4 },
  { str: 'b', ing: 'y', foo: 'G', value: 300 },
  { str: 'b', ing: 'z', foo: 'H', value: 400 },
  { str: 'a', ing: 'z', foo: 'K', value: 5 },
  { str: 'a', ing: 'z', foo: 'G', value: 6 },
]

tidy(
  data,
  groupBy('str', [
    summarize({ total: sum('value') })
  ])
)
// output:
[{ str: 'a', total: 21 },
 { str: 'b', total: 1000 }]
```

--------------------------------

### Selectors API - numRange

Source: https://pbeshai.github.io/tidy/docs/api/selectors

Returns all keys that start with a specified prefix and have a numerical suffix within a given range.

```APIDOC
## numRange

### Description
Returns all keys that start with the specified substring combined with a numerical suffix within a specified range.

### Parameters
#### `prefix` (string) - Required - The prefix for the keys that will have the numbers appended to.
#### `range` ([number, number]) - Required - The `[min, max]` numbers to generate the keys over.
#### `width?` (number | undefined) - Optional - How many leading zeroes the numbers should have, defaults to none.

### Usage
```javascript
const data = [
  { foo07: 1, foo08: 20, foo10: 300, foo11: 90, foo12: 12, bar08: 8, foo: 1 },
];

tidy(data, select([numRange('foo', [8, 11], 2)]))
// output:
[{ foo08: 20, foo10: 300, foo11: 90 }]
```
```

--------------------------------

### Group data by multiple keys

Source: https://pbeshai.github.io/tidy/docs/api/groupby

Use groupBy with an array of keys to group data by multiple criteria. This example groups by 'str' and 'ing', then summarizes the 'value'.

```javascript
const data = [
  { str: 'a', ing: 'x', foo: 'G', value: 1 },
  { str: 'b', ing: 'x', foo: 'H', value: 100 },
  { str: 'b', ing: 'x', foo: 'K', value: 200 },
  { str: 'a', ing: 'y', foo: 'G', value: 2 },
  { str: 'a', ing: 'y', foo: 'H', value: 3 },
  { str: 'a', ing: 'y', foo: 'K', value: 4 },
  { str: 'b', ing: 'y', foo: 'G', value: 300 },
  { str: 'b', ing: 'z', foo: 'H', value: 400 },
  { str: 'a', ing: 'z', foo: 'K', value: 5 },
  { str: 'a', ing: 'z', foo: 'G', value: 6 },
]

tidy(
  data,
  groupBy(['str', 'ing'], [
    summarize({ total: sum('value') })
  ])
)
// output:
[
  { str: 'a', ing: 'x', total: 1 },
  { str: 'a', ing: 'y', total: 9 },
  { str: 'a', ing: 'z', total: 11 },
  { str: 'b', ing: 'x', total: 300 },
  { str: 'b', ing: 'y', total: 300 },
  { str: 'b', ing: 'z', total: 400 },
]
```

--------------------------------

### Filter keys starting with a substring (case-insensitive)

Source: https://pbeshai.github.io/tidy/docs/api/selectors

Use `startsWith` to find keys beginning with a specified prefix. The match is case-insensitive by default; pass `false` as the second argument for a case-sensitive comparison.

```javascript
const data = [
  { foo: 1, bar: 20, foobar: 300, FoObAR: 90 },
];

tidy(data, select([startsWith('bAR')]))
// output:
// [{ foobar: 300, FoObAR: 90 }]

tidy(data, select([startsWith('bAR', false)]))
// output:
// [{ FoObAR: 90 }]
```

--------------------------------

### Get First Item Value with first()

Source: https://pbeshai.github.io/tidy/docs/api/summary

Use first() to retrieve the value for a specified key from the first item in a collection. It can take a key string or an accessor function.

```javascript
const data = [
  { str: 'foo', value: 3 },
  { str: 'foo', value: 1 },
  { str: 'bar', value: 3 },
  { str: 'bar', value: 1 },
  { str: 'bar', value: 7 },
];

tidy(data, summarize({
  str: first('str'),
  value: sum('value'),
}))
// output:
[{ str: 'foo', value: 15 }]
```

--------------------------------

### Generate Row Numbers with Custom Start

Source: https://pbeshai.github.io/tidy/docs/api/vector

The `rowNumber` function generates sequential row numbers for each item. Use the `startAt` option to specify a different starting number for the sequence.

```javascript
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 },
]
```

--------------------------------

### Row Number Function

Source: https://pbeshai.github.io/tidy/docs/api/vector

Explains how to use the `rowNumber` function to add a row index to each item in the dataset, with an option to specify the starting number.

```APIDOC
## Row Number Function

### Description
Computes the row number for each item in the array. This can also be achieved using a simple `mutate` operation.

### Method
`rowNumber(options)`

### Parameters
#### `options`
```
{
  startAt?: number
}
```

- `startAt` (number) - Optional - The number to start counting from. Defaults to 0.

### Usage Example
```javascript
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 Example
```json
[
  { "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 }
]
```
```

--------------------------------

### Group By and Summarize with TidyJS

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Illustrates grouping data by one or more keys and then summarizing the grouped data using TidyJS. Requires 'tidy', 'groupBy', 'summarize', and 'sum' functions.

```javascript
const data = [  
  { str: 'a', ing: 'x', foo: 'G', value: 1 },  
  { str: 'b', ing: 'x', foo: 'H', value: 100 },  
  { str: 'b', ing: 'x', foo: 'K', value: 200 },  
  { str: 'a', ing: 'y', foo: 'G', value: 2 },  
  { str: 'a', ing: 'y', foo: 'H', value: 3 },  
  { str: 'a', ing: 'y', foo: 'K', value: 4 },  
  { str: 'b', ing: 'y', foo: 'G', value: 300 },  
  { str: 'b', ing: 'z', foo: 'H', value: 400 },  
  { str: 'a', ing: 'z', foo: 'K', value: 5 },  
  { str: 'a', ing: 'z', foo: 'G', value: 6 },  
]

tidy(  
  data,  
  groupBy('str', [  
    summarize({ total: sum('value') })  
  ])  
)
// output:  
[  
  { str: 'a', total: 21 },  
  { str: 'b', total: 1000 },  
]
```

```javascript
tidy(  
  data,  
  groupBy(['str', 'ing'], [  
    summarize({ total: sum('value') })  
  ])  
)
// output:  
[  
  { str: 'a', ing: 'x', total: 1 },  
  { str: 'a', ing: 'y', total: 9 },  
  { str: 'a', ing: 'z', total: 11 },  
  { str: 'b', ing: 'x', total: 300 },  
  { str: 'b', ing: 'y', total: 300 },  
  { str: 'b', ing: 'z', total: 400 },  
]
```

--------------------------------

### Slice Data with Range

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Use `slice` to extract a subset of data within a specified range. The range is inclusive of the start index and exclusive of the end index.

```javascript
const data = [
  { value: 1 },
  { value: 2 },
  { value: 3 },
  { value: 4 },
  { value: 5 },
];

tidy(data, slice(1, 3))
// output:
// [{ value: 2 }, { value: 3 }]
```

--------------------------------

### Selectors API - everything

Source: https://pbeshai.github.io/tidy/docs/api/selectors

Returns all keys for items in the collection. It looks only at the first element in the collection.

```APIDOC
## everything

### Description
Returns all keys for items in the collection. It is naive and looks only at the first element in the collection.

### Usage
```javascript
const data = [
  { foo: 1, bar: 20, foobar: 300, FoObAR: 90 },
];

tidy(data, select(['foobar', everything(), '-FoObAR']))
// output:
[{ foobar: 300, foo: 1, bar: 20 }]
```
```

--------------------------------

### Slice data array

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Use `slice` to extract a subset of data from an array, similar to `Array.prototype.slice`. Specify a start index (inclusive) and an end index (exclusive).

--------------------------------

### Group, Summarize, Select, and Arrange Data with Tidy.js

Source: https://pbeshai.github.io/tidy/playground

This snippet demonstrates a common data wrangling pattern in Tidy.js. It groups data by specified columns, calculates summary statistics, selects relevant columns, and then arranges the results. Ensure the 'input' variable is pre-defined with your dataset.

```javascript
output = tidy(input,
groupBy(['cyl', 'gear'], [
summarize({
n: n(),
mpg: mean('mpg'),
hp: mean('hp'),
wt: mean('wt'),
}),
]),
select(['cyl', 'gear', everything()]),
arrange([desc('n'), desc('mpg')])
);
```

--------------------------------

### Calculate Moving Average with Zerofill (Summarize)

Source: https://pbeshai.github.io/tidy/docs/examples/moving_average_example

An alternative method to handle missing dates by first summarizing to daily granularity, then filling missing dates with zero, and finally computing a 7-day moving average.

```javascript
tidy(  
  data,  
  summarizeMomentGranularity('day', { value: sum('value') }),  
  complete(  
    { timestamp: fullSeqDateISOString('timestamp', 'day') },  
    { value: 0 }  
  ),  
  mutateWithSummary({  
    movingAvg: roll(7, mean('value'), { partial: true })  
  })  
);
```

--------------------------------

### Get Last Item Value with last()

Source: https://pbeshai.github.io/tidy/docs/api/summary

Use last() to retrieve the value for a specified key from the last item in a collection. It accepts a key or an accessor function.

```javascript
const data = [
  { str: 'foo', value: 3 },
  { str: 'foo', value: 1 },
  { str: 'bar', value: 3 },
  { str: 'bar', value: 1 },
  { str: 'bar', value: 7 },
];

tidy(data, summarize({
  str: last('str'),
  value: sum('value'),
}))
// output:
[{ str: 'bar', value: 15 }]
```

--------------------------------

### Compute Mean Rate with meanRate()

Source: https://pbeshai.github.io/tidy/docs/api/summary

Use meanRate() for fractional values by summing numerators and denominators separately before division. Requires numerator and denominator keys or accessor functions.

```javascript
const data = [
  { str: 'foo', value: 3, value2: 4 },
  { str: 'foo', value: 0, value2: 0 },
  { str: 'bar', value: 0, value2: 3 },
  { str: 'bar', value: 1, value2: 2 },
  { str: 'bar', value: 7, value2: 10 },
];

tidy(data, summarize({
  meanValue: meanRate('value', 'value2'),
}))
// output:
[{ meanValue: 11 / 19 }]
```

--------------------------------

### expandKeys

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Expands a collection to include all combinations of specified keys. Supports various input formats for keys, including strings, arrays of strings, and mapping objects.

```APIDOC
## expandKeys

### Description
The keys to expand the collection to have all combinations of. This can be specified as a single key string, an array of key strings or a key mapping object. The key mapping object maps from keys in the items to either:
  * `{ a: 'a' }`: the key name itself. In this case, the values to use for the combinations will be derived from what is in the data currently.
  * `{ a: [1, 2, 3, 4] }`: an array of values denoting all possible values for this key, even if they do not occur in the data.
  * `{ a: fullSeq('a') }`: a function mapping from the items in the collection to an array of all possible values. This is typically used in combination with sequence helper functions like **fullSeq**.

### Parameters
#### `expandKeys`
```
| string /* key of item */  
| string[]  
| { [key]: string | any[] | (items: object[]) => any[] }  
```

### Usage
```javascript
const data = [
  { a: 1, b: 'b1', c: 100 },
  { a: 2, b: 'b1', c: 200 },
  { a: 3, b: 'b1', c: 300 },
  { a: 1, b: 'b2', c: 101 },
  { a: 2, b: 'b2', c: 201 },
];

tidy(data, complete(['a', 'b'], { c: 0 }))
// output:
[
  { a: 1, b: 'b1', c: 100 },
  { a: 1, b: 'b2', c: 101 },
  { a: 2, b: 'b1', c: 200 },
  { a: 2, b: 'b2', c: 201 },
  { a: 3, b: 'b1', c: 300 },
  { a: 3, b: 'b2', c: 0 },
]
```
```

--------------------------------

### Select all keys from the first object

Source: https://pbeshai.github.io/tidy/docs/api/selectors

The `everything` selector returns all keys from the first object in the collection. It's a naive selector that only inspects the initial element.

```javascript
const data = [
  { foo: 1, bar: 20, foobar: 300, FoObAR: 90 },
];

tidy(data, select(['foobar', everything(), '-FoObAR']))
// output:
// [{ foobar: 300, foo: 1, bar: 20 }]
```

--------------------------------

### complete

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Completes a collection with missing combinations of data, useful for zero-filling.

```APIDOC
## complete

### Description
Complete a collection with missing combinations of data, can be useful for zero filling data. This is a convenience function that combines **expand**, **leftJoin**, and **replaceNully**.

### Parameters

```

--------------------------------

### Summarize All Data with Tidy

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Use summarizeAll to apply a summary function to all keys in the data. This is useful for aggregating all numerical columns.

```javascript
const data = [
  { value2: 3, value: 3 },
  { value2: 4, value: 1 },
  { value2: 5, value: 3 },
  { value2: 1, value: 1 },
  { value2: 10, value: 7 },
];

tidy(data, summarizeAll(sum))
// output:
// [{ value: 15, value2: 23 }]
```

--------------------------------

### Using rate with a predicate

Source: https://pbeshai.github.io/tidy/docs/api/item

Illustrates how to use the 'rate' function with a predicate to conditionally compute rates only when the denominator is greater than 1000.

```javascript
rate('numerator', 'denominator', { predicate: d => d.denominator > 1000 })
```

--------------------------------

### Filter keys with a numerical suffix within a range

Source: https://pbeshai.github.io/tidy/docs/api/selectors

Use `numRange` to select keys that start with a specific prefix followed by a number within a defined range. The `width` parameter controls leading zeros for the numerical suffix.

```javascript
const data = [
  { foo07: 1, foo08: 20, foo10: 300, foo11: 90, foo12: 12, bar08: 8, foo: 1 },
];

tidy(data, select([numRange('foo', [8, 11], 2)]))
// output:
// [{ foo08: 20, foo10: 300, foo11: 90 }]
```

--------------------------------

### Select Minimum N Items by Key with sliceMin

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Use `sliceMin` to select the N items with the smallest values based on a specified key or comparator. Requires data to be ordered.

```javascript
const data = [
  { value: 3 },
  { value: 1 },
  { value: 4 },
  { value: 5 },
  { value: 2 },
];

tidy(data, sliceMin(2, 'value'))
// output:
// [{ value: 1 }, { value: 2 }]
```

--------------------------------

### Summarize Data by Moment Date Granularity

Source: https://pbeshai.github.io/tidy/docs/tidy-moment

Use summarizeMomentGranularity to group and aggregate data by specified date intervals (day, week, month, year) using UTC moment dates. It's useful for preparing time-series data for further analysis like moving averages. Ensure moment.js is installed and imported.

```javascript
const data = [
  { str: 'foo', date: moment.utc('2020-01-01'), value: 3 },
  { str: 'foo', date: moment.utc('2020-01-03'), value: 1 },
  { str: 'bar', date: moment.utc('2020-01-10'), value: 3 },
  { str: 'bar', date: moment.utc('2020-01-21'), value: 1 },
  { str: 'bar', date: moment.utc('2020-01-29'), value: 2 },
  { str: 'bar', date: moment.utc('2020-02-01'), value: 5 },
];

tidy(
  data,
  summarizeMomentGranularity('weeks', { value: sum('value') })
);
// output:
[
  {
    value: 4,
    str: 'foo',
    date: moment.utc('2019-12-30'),
    timestamp: '2019-12-30T00:00:00.000Z',
  },
  {
    value: 3,
    str: 'bar',
    date: moment.utc('2020-01-06'),
    timestamp: '2020-01-06T00:00:00.000Z',
  },
  {
    value: 1,
    str: 'bar',
    date: moment.utc('2020-01-20'),
    timestamp: '2020-01-20T00:00:00.000Z',
  },
  {
    value: 7,
    str: 'bar',
    date: moment.utc('2020-01-27'),
    timestamp: '2020-01-27T00:00:00.000Z',
  },
]
```

--------------------------------

### Selectors API - matches

Source: https://pbeshai.github.io/tidy/docs/api/selectors

Returns all keys that match a given regular expression. The 'i' flag must be provided for case-insensitivity.

```APIDOC
## matches

### Description
Returns all keys that start with the specified substring.

### Parameters
#### `regex` (RegExp) - Required - The regular expression used to match keys against. You must provide the `i` flag to have case ignored.

### Usage
```javascript
const data = [
  { foo: 1, bar: 20, foobar: 300, FoObAR: 90 },
];

tidy(data, select([matches(/oba/i)]))
// output:
[{ foobar: 300, FoObAR: 90 }]

tidy(data, select([matches(/oba/)]))
// output:
[{ foobar: 300 }]
```
```

--------------------------------

### Left Join with Array of Keys

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Performs a left join on two datasets using an array of keys for matching. Ensure that the column names are the same in both datasets.

```javascript
const data = [
  { a: 1, J: 'j', b: 10, c: 100 },
  { a: 1, J: 'k', b: 60, c: 600 },
  { a: 1, J: 'J', b: 30, c: 300 },
  { a: 2, J: 'j', b: 20, c: 200 },
  { a: 3, J: 'x', b: 50, c: 500 },
];

const joinData = [
  { a: 1, J: 'j', altJ: 'j', x: 'x1', y: 'y1' },
  { a: 1, J: 'J', altJ: 'J', x: 'x9', y: 'y9' },
  { a: 2, J: 'j', altJ: 'j', x: 'x2', y: 'y2' },
];

tidy(data, leftJoin(joinData, { by: ['a', 'J'] }));
// output:
[
  { a: 1, J: 'j', altJ: 'j', b: 10, c: 100, x: 'x1', y: 'y1' },
  { a: 1, J: 'k', b: 60, c: 600 },
  { a: 1, J: 'J', altJ: 'J', b: 30, c: 300, x: 'x9', y: 'y9' },
  { a: 2, J: 'j', altJ: 'j', b: 20, c: 200, x: 'x2', y: 'y2' },
  { a: 3, J: 'x', b: 50, c: 500 },
]
```

--------------------------------

### Select First N Items with sliceHead

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Use `sliceHead` to select the first N items from a collection. This is useful for taking a prefix of your data.

```javascript
const data = [
  { value: 1 },
  { value: 2 },
  { value: 3 },
  { value: 4 },
  { value: 5 },
];

tidy(data, sliceHead(2))
// output:
// [{ value: 1 }, { value: 2 }]
```

--------------------------------

### sliceHead

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Selects the first N items in the collection.

```APIDOC
## sliceHead

### Description
Selects the first N items in the collection.

### Parameters
#### `n`
```
number
```

The number of items to select.

### Usage
```javascript
const data = [
  { value: 1 },
  { value: 2 },
  { value: 3 },
  { value: 4 },
  { value: 5 },
];

tidy(data, sliceHead(2))
// output:
// [{ value: 1 }, { value: 2 }]
```
```

--------------------------------

### Expand Keys for Data Combinations

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Specifies how to expand a collection to include all combinations of specified keys. Supports key strings, arrays of strings, or a mapping object for custom value derivation or function-based value generation.

```javascript
string /* key of item */  
string[]  
{ [key]: string | any[] | (items: object[]) => any[] }
```

--------------------------------

### Complete Data with Default Values

Source: https://pbeshai.github.io/tidy/docs/api/tidy

Completes a dataset by ensuring all combinations of specified keys exist, filling missing values with a default. This is useful for ensuring a full matrix of data before further processing.

```javascript
const data = [
  { a: 1, b: 'b1', c: 100 },
  { a: 2, b: 'b1', c: 200 },
  { a: 3, b: 'b1', c: 300 },
  { a: 1, b: 'b2', c: 101 },
  { a: 2, b: 'b2', c: 201 },
];

tidy(data, complete(['a', 'b'], { c: 0 }))
```

```javascript
[
  { a: 1, b: 'b1', c: 100 },
  { a: 1, b: 'b2', c: 101 },
  { a: 2, b: 'b1', c: 200 },
  { a: 2, b: 'b2', c: 201 },
  { a: 3, b: 'b1', c: 300 },
  { a: 3, b: 'b2', c: 0 },
]
```
Tokens:
Raw