Sorting data

Sort values; see also bisect.

ascending(a, b)

Examples · Source · Returns -1 if a is less than b, 1 if a is greater than b, 0 if a and b are equivalent, and otherwise NaN.

[39, 21, 1, 104, 22].sort(d3.ascending) // [1, 21, 22, 39, 104]

This is the comparator function for natural order, and can be used with array.sort to arrange elements in ascending order.

descending(a, b)

Examples · Source · Returns -1 if a is greater than b, 1 if a is less than b, 0 if a and b are equivalent, and otherwise NaN.

[39, 21, 1, 104, 22].sort(d3.descending) // [104, 39, 22, 21, 1]

This is the comparator function for natural order, and can be used with array.sort to arrange elements in descending order.

permute(source, keys)

Examples · Source · Returns a permutation of the specified source array or object using the specified iterable of keys. The returned array contains the corresponding property of the source object for each key in keys, in order.

d3.permute(["a", "b", "c"], [1, 2, 0]) // returns ["b", "c", "a"]

The given source need not be an array; for example, given an object

const object = {yield: 27, variety: "Manchuria", year: 1931, site: "University Farm"};

three fields could be extract like so

d3.permute(object, ["site", "variety", "yield"]) // ["University Farm", "Manchuria", 27]

quickselect(array, k, lo, hi, compare)

Examples · Source · Rearranges the elements of array between lo and hi (inclusive) in-place such that array[k] is the (k - lo + 1)-th smallest value and array.slice(lo, k) are the k smallest elements, according to the given compare function, and returns the given array. If lo is not specified, it defaults to zero; if hi is not specified, it defaults to array.length - 1; if compare is not specified, it defaults to ascending.

For example, given an array of numbers:

const numbers = [65, 28, 59, 33, 21, 56, 22, 95, 50, 12, 90, 53, 28, 77, 39];

To select the smallest 8 elements:

d3.quickselect(numbers, 8)

The rearranged numbers is

[39, 28, 28, 33, 21, 12, 22, 50, 53, 56, 59, 65, 90, 77, 95]
//                               ^^ numbers[k]

where numbers[8] is 53: greater than the preceding k elements and less than the following elements. Implemented by Volodymyr Agafonkin’s quickselect.

reverse(iterable)

Source · Returns an array containing the values in the given iterable in reverse order.

d3.reverse(new Set([0, 2, 3, 1])) // [1, 3, 2, 0]

Equivalent to array.reverse, except that it does not mutate the given input and works with any iterable.

shuffle(array, start, stop)

Examples · Source · Randomizes the order of the specified array in-place using the Fisher–Yates shuffle and returns the array.

d3.shuffle([..."abcdefg"]) // ["e", "c", "a", "d", "b", "g", "f"], perhaps

If start is specified, it is the starting index (inclusive) of the array to shuffle; if start is not specified, it defaults to zero. If stop is specified, it is the ending index (exclusive) of the array to shuffle; if stop is not specified, it defaults to array.length. For example, to shuffle the first ten elements of the array: shuffle(array, 0, 10).

shuffler(random)

Source · Returns a shuffle function given the specified random source.

d3.shuffler(d3.randomLcg(42))([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) // [5, 3, 7, 6, 8, 9, 1, 4, 0, 2]

Often used with d3.randomLcg for a deterministic shuffle.

sort(iterable, comparator)

Source · Returns an array containing the values in the given iterable in the sorted order defined by the given comparator or accessor function. If comparator is not specified, it defaults to d3.ascending.

d3.sort(new Set([0, 2, 3, 1])) // [0, 1, 2, 3]

If an accessor (a function that does not take exactly two arguments) is specified,

d3.sort(data, (d) => d.value)

it is equivalent to a comparator using natural order:

d3.sort(data, (a, b) => d3.ascending(a.value, b.value))

The accessor is only invoked once per element, and thus the returned sorted order is consistent even if the accessor is nondeterministic. Multiple accessors may be specified to break ties.

d3.sort(points, ({x}) => x, ({y}) => y)

The above is equivalent to:

d3.sort(data, (a, b) => d3.ascending(a.x, b.x) || d3.ascending(a.y, b.y))

Unlike array.sort, d3.sort does not mutate the given input, the comparator defaults to natural order instead of lexicographic order, and the input can be any iterable.