d3-array

Data in JavaScript is often represented by an iterable (such as an array, set or generator), and so iterable manipulation is a common task when analyzing or visualizing data. For example, you might take a contiguous slice (subset) of an array, filter an array using a predicate function, or map an array to a parallel set of values using a transform function. Before looking at the methods that d3-array provides, familiarize yourself with the powerful array methods built-in to JavaScript.

JavaScript includes mutation methods that modify the array:

• array.pop - Remove the last element from the array.
• array.push - Add one or more elements to the end of the array.
• array.reverse - Reverse the order of the elements of the array.
• array.shift - Remove the first element from the array.
• array.sort - Sort the elements of the array.
• array.splice - Add or remove elements from the array.
• array.unshift - Add one or more elements to the front of the array.

There are also access methods that return some representation of the array:

• array.concat - Join the array with other array(s) or value(s).
• array.join - Join all elements of the array into a string.
• array.slice - Extract a section of the array.
• array.indexOf - Find the first occurrence of a value within the array.
• array.lastIndexOf - Find the last occurrence of a value within the array.

And finally iteration methods that apply functions to elements in the array:

• array.filter - Create a new array with only the elements for which a predicate is true.
• array.forEach - Call a function for each element in the array.
• array.every - See if every element in the array satisfies a predicate.
• array.map - Create a new array with the result of calling a function on every element in the array.
• array.some - See if at least one element in the array satisfies a predicate.
• array.reduce - Apply a function to reduce the array to a single value (from left-to-right).
• array.reduceRight - Apply a function to reduce the array to a single value (from right-to-left).

Installing

If you use npm, npm install d3-array. You can also download the latest release on GitHub. For vanilla HTML in modern browsers, import d3-array from jsDelivr:

<script type="module">

import {min} from "https://cdn.jsdelivr.net/npm/d3-array@3/+esm";

const m = min(array);

</script>

For legacy environments, you can load d3-array’s UMD bundle; a d3 global is exported:

<script src="https://cdn.jsdelivr.net/npm/d3-array@3"></script>
<script>

const m = d3.min(array);

</script>

API Reference

• Statistics
• Search
• Transformations
• Iterables
• Sets
• Bins
• Interning

Statistics

Methods for computing basic summary statistics.

# d3.min(iterable[, accessor]) · Source, Examples

Returns the minimum value in the given iterable using natural order. If the iterable contains no comparable values, returns undefined. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the minimum value.

Unlike the built-in Math.min, this method ignores undefined, null and NaN values; this is useful for ignoring missing data. In addition, elements are compared using natural order rather than numeric order. For example, the minimum of the strings [“20”, “3”] is “20”, while the minimum of the numbers [20, 3] is 3.

See also extent.

# d3.minIndex(iterable[, accessor]) · Source, Examples

Returns the index of the minimum value in the given iterable using natural order. If the iterable contains no comparable values, returns -1. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the minimum value.

Unlike the built-in Math.min, this method ignores undefined, null and NaN values; this is useful for ignoring missing data. In addition, elements are compared using natural order rather than numeric order. For example, the minimum of the strings [“20”, “3”] is “20”, while the minimum of the numbers [20, 3] is 3.

# d3.max(iterable[, accessor]) · Source, Examples

Returns the maximum value in the given iterable using natural order. If the iterable contains no comparable values, returns undefined. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the maximum value.

Unlike the built-in Math.max, this method ignores undefined values; this is useful for ignoring missing data. In addition, elements are compared using natural order rather than numeric order. For example, the maximum of the strings [“20”, “3”] is “3”, while the maximum of the numbers [20, 3] is 20.

See also extent.

# d3.maxIndex(iterable[, accessor]) · Source, Examples

Returns the index of the maximum value in the given iterable using natural order. If the iterable contains no comparable values, returns -1. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the maximum value.

Unlike the built-in Math.max, this method ignores undefined values; this is useful for ignoring missing data. In addition, elements are compared using natural order rather than numeric order. For example, the maximum of the strings [“20”, “3”] is “3”, while the maximum of the numbers [20, 3] is 20.

# d3.extent(iterable[, accessor]) · Source, Examples

Returns the minimum and maximum value in the given iterable using natural order. If the iterable contains no comparable values, returns [undefined, undefined]. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the extent.

# d3.mode(iterable[, accessor]) · Source, Examples

Returns the mode of the given iterable, i.e. the value which appears the most often. In case of equality, returns the first of the relevant values. If the iterable contains no comparable values, returns undefined. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the mode. This method ignores undefined, null and NaN values; this is useful for ignoring missing data.

# d3.sum(iterable[, accessor]) · Source, Examples

Returns the sum of the given iterable of numbers. If the iterable contains no numbers, returns 0. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the sum. This method ignores undefined and NaN values; this is useful for ignoring missing data.

# d3.mean(iterable[, accessor]) · Source, Examples

Returns the mean of the given iterable of numbers. If the iterable contains no numbers, returns undefined. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the mean. This method ignores undefined and NaN values; this is useful for ignoring missing data.

# d3.median(iterable[, accessor]) · Source, Examples

Returns the median of the given iterable of numbers using the R-7 method. If the iterable contains no numbers, returns undefined. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the median. This method ignores undefined and NaN values; this is useful for ignoring missing data.

# d3.medianIndex(array[, accessor]) · Source

Similar to median, but returns the index of the element to the left of the median.

# d3.cumsum(iterable[, accessor]) · Source, Examples

Returns the cumulative sum of the given iterable of numbers, as a Float64Array of the same length. If the iterable contains no numbers, returns zeros. An optional accessor function may be specified, which is equivalent to calling Array.from before computing the cumulative sum. This method ignores undefined and NaN values; this is useful for ignoring missing data.

# d3.quantile(iterable, p[, accessor]) · Source, Examples

Returns the p-quantile of the given iterable of numbers, where p is a number in the range [0, 1]. For example, the median can be computed using p = 0.5, the first quartile at p = 0.25, and the third quartile at p = 0.75. This particular implementation uses the R-7 method, which is the default for the R programming language and Excel. For example:

var a = [0, 10, 30];
d3.quantile(a, 0); // 0
d3.quantile(a, 0.5); // 10
d3.quantile(a, 1); // 30
d3.quantile(a, 0.25); // 5
d3.quantile(a, 0.75); // 20
d3.quantile(a, 0.1); // 2

An optional accessor function may be specified, which is equivalent to calling array.map(accessor) before computing the quantile.

# d3.quantileIndex(array, p[, accessor]) Source

Similar to quantile, but returns the index to the left of p.

# d3.quantileSorted(array, p[, accessor]) · Source, Examples

Similar to quantile, but expects the input to be a sorted array of values. In contrast with quantile, the accessor is only called on the elements needed to compute the quantile.

# d3.rank(