@d3plus/data

JavaScript data loading, manipulation, and analysis functions.

Installing

If using npm, npm install @d3plus/data. Otherwise, you can download the latest release from GitHub or load from a CDN.

import {*} from "@d3plus/data";

In a vanilla environment, a d3plus global is exported from the pre-bundled version:

<script src="https://cdn.jsdelivr.net/npm/@d3plus/data"></script>
<script>
  console.log(d3plus);
</script>

Examples

Live examples can be found on d3plus.org, which includes a collection of example visualizations using @d3plus/react.

API Reference

| Functions | Description | | --- | --- | | addToQueue | Adds the provided value to the internal queue to be loaded, if necessary. This is used internally in new d3plus visualiz | | concat | Reduce and concat all the elements included in arrayOfArrays if they are arrays. If it is a JSON object try to concat th | | fold | Given a JSON object where the data values and headers have been split into separate key lookups, this function will comb | | isData | Returns true/false whether the argument provided to the function should be loaded using an internal XHR request. Valid d | | load | Loads data from a filepath or URL, converts it to a valid JSON object, and returns it to a callback function. | | merge | Combines an Array of Objects together and returns a new Object. | | nestGroups | Recursively groups data by each key function, producing {key, values} objects compatible with d3-hierarchy. | | unique | ES5 implementation to reduce an Array of values to unique instances. |

| Interfaces | Description | | --- | --- | | DataPoint | DataPoint | | MergedDataPoint | |

Functions

addToQueue()

addToQueue(this: VizContext, _: string | DataPoint[] | Record<string, unknown>, f: DataFormatter | undefined, key: string): void

Defined in: addToQueue.ts:26

Adds the provided value to the internal queue to be loaded, if necessary. This is used internally in new d3plus visualizations that fold in additional data sources, like the nodes and links of Network or the topojson of Geomap.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | this | VizContext | - | | _ | string | DataPoint[] | Record<string, unknown> | - | | f | DataFormatter | required | Optional formatter function applied to the loaded data. | | key | string | The property name on the instance to store the loaded data. |

Returns

void

concat()

concat(arrayOfArrays: (DataPoint[] | Record<string, DataPoint[]>)[], data?: string): DataPoint[]

Defined in: concat.ts:8

Reduce and concat all the elements included in arrayOfArrays if they are arrays. If it is a JSON object try to concat the array under given key data. If the key doesn't exists in object item, a warning message is lauched to the console. You need to implement DataFormat callback to concat the arrays manually.

Parameters

| Parameter | Type | Default | Description | | ------ | ------ | ------ | ------ | | arrayOfArrays | (DataPoint[] | Record<string, DataPoint[]>)[] | required | Array of elements | | data | string | "data" | The key in each element that contains the sub-array to concatenate. |

Returns

DataPoint[]

fold()

fold(json: FoldableJSON, data?: string, headers?: string): DataPoint[]

Defined in: fold.ts:13

Given a JSON object where the data values and headers have been split into separate key lookups, this function will combine the data values with the headers and returns one large array of objects.

Parameters

| Parameter | Type | Default | Description | | ------ | ------ | ------ | ------ | | json | FoldableJSON | required | A JSON data Object with data and headers keys. | | data | string | "data" | The key in the JSON object that contains the data array. | | headers | string | "headers" | The key used for the flat headers array inside of the JSON object. |

Returns

DataPoint[]

isData()

isData(dataItem: unknown): boolean

Defined in: isData.ts:5

Returns true/false whether the argument provided to the function should be loaded using an internal XHR request. Valid data can either be a string URL or an Object with "url" and "headers" keys.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | dataItem | unknown | The value to be tested |

Returns

boolean

load()

load(this: VizContext, path: string | DataPoint[] | (string | DataPoint[] | LoadRequestConfig)[], formatter?: DataFormatter, key?: string, callback?: (error: Error | null | undefined, data: DataPoint[] | DataPoint[][] | undefined) => void): void

Defined in: load.ts:33

Loads data from a filepath or URL, converts it to a valid JSON object, and returns it to a callback function.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | this | VizContext | - | | path | string | DataPoint[] | (string | DataPoint[] | LoadRequestConfig)[] | The path to the file or url to be loaded. Also support array of paths strings. If an Array of objects is passed, the xhr request logic is skipped. | | formatter? | DataFormatter | Optional function to transform the loaded data. | | key? | string | The key in the this context to save the resulting data to. | | callback? | (error: Error | null | undefined, data: DataPoint[] | DataPoint[][] | undefined) => void | Optional function called with the error and loaded data. |

Returns

void

merge()

merge(objects: DataPoint[], aggs?: Record<string, AggregationFunction>): MergedDataPoint

Defined in: merge.ts:30

Combines an Array of Objects together and returns a new Object.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | objects | DataPoint[] | The Array of objects to be merged together. | | aggs | Record<string, AggregationFunction> | An object containing specific aggregation methods (functions) for each key type. By default, numbers are summed and strings are returned as an array of unique values. |

Returns

MergedDataPoint

Examples

merge([
{id: "foo", group: "A", value: 10, links: [1, 2]},
{id: "bar", group: "A", value: 20, links: [1, 3]}
]);

{id: ["bar", "foo"], group: "A", value: 30, links: [1, 2, 3]}

nestGroups()

nestGroups(data: DataPoint[], fns: KeyAccessor[]): NestEntry[]

Defined in: nest.ts:33

Recursively groups data by each key function, producing {key, values} objects compatible with d3-hierarchy.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | data | DataPoint[] | The flat data array to nest. | | fns | KeyAccessor[] | An array of key accessor functions, one per nesting level. |

Returns

NestEntry[]

unique()

unique<T>(arr: T[], accessor?: (d: T) => unknown): T[]

Defined in: unique.ts:10

ES5 implementation to reduce an Array of values to unique instances.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | arr | T[] | The Array of objects to be filtered. | | accessor | (d: T) => unknown | An optional accessor function used to extract data points from an Array of Objects. |

Returns

T[]

Examples

unique(["apple", "banana", "apple"]);

["apple", "banana"]

Interfaces

DataPoint

Defined in: DataPoint.ts:5

DataPoint Represents a single data point object used throughout d3plus visualizations.

Indexable

[key: string]: string | number | boolean | DataPoint

MergedDataPoint

Defined in: merge.ts:9

Indexable

[key: string]: MergedValue