InternMap example with Date keys
const valueByDate = new d3.InternMap([[new Date('2021-01-01'), 42], [new Date('2022-01-01'), 12], [new Date('2023-01-01'), 45]]); valueByDate.get(new Date('2022-01-01')) returns 12. This demonstrates using Date objects as keys in an InternMap.
InternSet example with Date values
const dates = new d3.InternSet([new Date('2021-01-01'), new Date('2022-01-01'), new Date('2023-01-01')]); dates.has(new Date('2022-01-01')) returns true. This demonstrates using Date objects as values in an InternSet.
quickselect function signature and behavior
quickselect(array, k, lo, hi, compare) rearranges 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, defaults to zero. If hi is not specified, defaults to array.length - 1. If compare is not specified, defaults to ascending. Example: given numbers = [65, 28, 59, 33, 21, 56, 22, 95, 50, 12, 90, 53, 28, 77, 39], calling d3.quickselect(numbers, 8) rearranges to [39, 28, 28, 33, 21, 12, 22, 50, 53, 56, 59, 65, 90, 77, 95] where numbers[8] is 53.
reverse function signature and behavior
reverse(iterable) returns an array containing the values in the given iterable in reverse order. Does not mutate the input and works with any iterable, unlike Array.reverse. Example: d3.reverse(new Set([0, 2, 3, 1])) returns [1, 3, 2, 0].
shuffle function signature and behavior
shuffle(array, start, stop) randomizes the order of the specified array in-place using the Fisher–Yates shuffle and returns the array. If start is specified, it is the starting index (inclusive) of the array to shuffle; defaults to zero if not specified. If stop is specified, it is the ending index (exclusive) of the array to shuffle; defaults to array.length if not specified. Example: d3.shuffle([...'abcdefg']) returns a shuffled array like ['e', 'c', 'a', 'd', 'b', 'g', 'f']. To shuffle the first ten elements: shuffle(array, 0, 10).
shuffler function signature and behavior
shuffler(random) returns a shuffle function given the specified random source. Example: d3.shuffler(d3.randomLcg(42))([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) returns [5, 3, 7, 6, 8, 9, 1, 4, 0, 2]. Often used with d3.randomLcg for a deterministic shuffle.
sort function signature and behavior
sort(iterable, comparator) 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, defaults to d3.ascending. Unlike Array.sort, d3.sort does not mutate the input, defaults to natural order instead of lexicographic order, and the input can be any iterable. Example with default: d3.sort(new Set([0, 2, 3, 1])) returns [0, 1, 2, 3]. With accessor: d3.sort(data, (d) => d.value) is equivalent to d3.sort(data, (a, b) => d3.ascending(a.value, b.value)). Multiple accessors can be specified to break ties: d3.sort(points, ({x}) => x, ({y}) => y) is equivalent to d3.sort(data, (a, b) => d3.ascending(a.x, b.x) || d3.ascending(a.y, b.y)). The accessor is only invoked once per element.
permute function signature and behavior
permute(source, keys) 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. Example with array: d3.permute(['a', 'b', 'c'], [1, 2, 0]) returns ['b', 'c', 'a']. Example with object: d3.permute({yield: 27, variety: 'Manchuria', year: 1931, site: 'University Farm'}, ['site', 'variety', 'yield']) returns ['University Farm', 'Manchuria', 27].
descending comparator function
descending(a, b) 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. Use with Array.sort() to arrange elements in descending order. Example: [39, 21, 1, 104, 22].sort(d3.descending) returns [104, 39, 22, 21, 1].
d3.leastIndex signature and behavior
d3.leastIndex(iterable, comparator) returns the index of the least element of the specified iterable according to the specified comparator or accessor. If comparator is not specified, it defaults to ascending. Returns -1 if the iterable contains no comparable elements.
d3.greatestIndex signature and behavior
d3.greatestIndex(iterable, comparator) returns the index of the greatest element of the specified iterable according to the specified comparator or accessor. If comparator is not specified, it defaults to ascending. Returns -1 if the iterable contains no comparable elements.
d3.mode signature and behavior
d3.mode(iterable, accessor) returns the mode of the given iterable, i.e. the value which appears the most often. Ignores undefined, null, and NaN values. In case of equality, returns the first of the relevant values. If the iterable contains no comparable values, returns undefined.
d3.sum signature and behavior
d3.sum(iterable, accessor) returns the sum of the given iterable of numbers. Ignores undefined, null, and NaN values. An optional accessor function may be specified. If the iterable contains no numbers, returns 0.
d3.mean signature and behavior
d3.mean(iterable, accessor) returns the mean of the given iterable of numbers. Ignores undefined, null, and NaN values. An optional accessor function may be specified. If the iterable contains no numbers, returns undefined.
d3.median signature and behavior
d3.median(iterable, accessor) returns the median of the given iterable of numbers using the R-7 method. Ignores undefined, null, and NaN values. An optional accessor function may be specified. If the iterable contains no numbers, returns undefined.
d3.medianIndex signature and behavior
d3.medianIndex(array, accessor) returns the index of the element to the left of the median, similar to median but returning an index instead of the value.
d3.cumsum signature and behavior
d3.cumsum(iterable, accessor) returns the cumulative sum of the given iterable of numbers as a Float64Array of the same length. An optional accessor function may be specified. This method ignores undefined and NaN values. If the iterable contains no numbers, returns zeros.
d3.quantileIndex signature and behavior
d3.quantileIndex(array, p, accessor) returns the index to the left of p, similar to quantile but returning an index instead of the value.
d3.quantileSorted signature and behavior
d3.quantileSorted(array, p, accessor) is 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 signature and behavior
d3.rank(iterable, comparator) returns an array with the rank of each value in the iterable, i.e. the zero-based index of the value when the iterable is sorted. Nullish values are sorted to the end and ranked NaN. An optional comparator or accessor function may be specified; if comparator is not specified, it defaults to ascending. Ties get the same rank, defined as the first time the value is found.
d3.variance signature and behavior
d3.variance(iterable, accessor) returns an unbiased estimator of the population variance of the given iterable of numbers using Welford's algorithm. If the iterable has fewer than two numbers, returns undefined. An optional accessor function may be specified. This method ignores undefined and NaN values.
d3.deviation signature and behavior
d3.deviation(iterable, accessor) returns the standard deviation, defined as the square root of the bias-corrected variance, of the given iterable of numbers. If the iterable has fewer than two numbers, returns undefined. An optional accessor function may be specified. This method ignores undefined and NaN values.
d3.every signature and behavior
d3.every(iterable, test) returns true if the given test function returns true for every value in the given iterable. This method returns as soon as test returns a non-truthy value or all values are iterated over. Equivalent to Array.prototype.every.
d3.some signature and behavior
d3.some(iterable, test) returns true if the given test function returns true for any value in the given iterable. This method returns as soon as test returns a truthy value or all values are iterated over. Equivalent to Array.prototype.some.
d3.quantile signature and behavior
d3.quantile(iterable, p, accessor) returns the p-quantile of the given iterable of numbers, where p is a number in the range [0, 1]. Uses the R-7 method. An optional accessor function may be specified.
d3.extent signature and behavior
d3.extent(iterable, accessor) returns the minimum and maximum value in the given iterable as an array [min, max] using natural order. An optional accessor function may be specified. If the iterable contains no comparable values, returns [undefined, undefined].
d3.count signature and behavior
d3.count(iterable, accessor) returns the number of valid number values (not null, NaN, or undefined) in the specified iterable; accepts an optional accessor function.
d3.min signature and behavior
d3.min(iterable, accessor) returns the minimum value in the given iterable using natural order. Unlike Math.min, it does not coerce inputs to numbers and ignores undefined, null, and NaN values. An optional accessor function may be specified, which is passed an element and its zero-based index. If the iterable contains no comparable values, returns undefined.
d3.minIndex signature and behavior
d3.minIndex(iterable, accessor) returns the index of the minimum value rather than the value itself, similar to min but working with comparators and accessors.
d3.max signature and behavior
d3.max(iterable, accessor) returns the maximum value in the given iterable using natural order. Unlike Math.max, it does not coerce inputs to numbers and ignores undefined, null, and NaN values. An optional accessor function may be specified, which is passed an element and its zero-based index. If the iterable contains no comparable values, returns undefined.
d3.maxIndex signature and behavior
d3.maxIndex(iterable, accessor) returns the index of the maximum value rather than the value itself, similar to max but working with comparators and accessors.
d3.ticks signature and behavior
d3.ticks(start, stop, count) returns an array of approximately count + 1 uniformly-spaced, nicely-rounded values between start and stop (inclusive). Each value is a power of ten multiplied by 1, 2 or 5. Ticks satisfy start ≤ t and t ≤ stop. Example: d3.ticks(1, 9, 5) returns [2, 4, 6, 8].
d3.ticks returns nicely-rounded values
The ticks returned by d3.ticks are nicely-rounded values that are powers of ten multiplied by 1, 2 or 5. This allows for human-readable axis labels.
d3.ticks example with high count
d3.ticks(1, 9, 20) returns [1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5, 5.5, 6, 6.5, 7, 7.5, 8, 8.5, 9].
d3.tickIncrement signature and behavior
d3.tickIncrement(start, stop, count) is like d3.tickStep except it requires that start is always less than or equal to stop. If the tick step for the given start, stop and count would be less than one, it returns the negative inverse tick step instead. This method always returns an integer and is used by d3.ticks to guarantee that returned tick values are represented as precisely as possible in IEEE 754 floating point.
d3.tickIncrement example
d3.tickIncrement(1, 9, 5) returns 2. d3.tickIncrement(1, 9, 20) returns -2, meaning a tick step of 0.5.
d3.tickStep signature and behavior
d3.tickStep(start, stop, count) returns the difference between adjacent tick values if the same arguments were passed to d3.ticks: a nicely-rounded value that is a power of ten multiplied by 1, 2 or 5. If stop is less than start, it may return a negative tick step to indicate descending ticks.
d3.tickStep example
d3.tickStep(1, 9, 5) returns 2. d3.tickStep(9, 1, 5) returns -2.
d3.tickStep floating point precision
Due to the limited precision of IEEE 754 floating point, the value returned by d3.tickStep may not be exact decimals. Use d3-format to format numbers for human consumption.
d3.nice signature and behavior
d3.nice(start, stop, count) returns a new interval [niceStart, niceStop] covering the given interval [start, stop] where niceStart and niceStop are guaranteed to align with the corresponding tick step. It requires that start is less than or equal to stop. Example: d3.nice(1, 9, 5) returns [0, 10].
d3.range signature and behavior
d3.range(start, stop, step) returns an array containing an arithmetic progression. If step is omitted, it defaults to 1. If start is omitted, it defaults to 0. The stop value is exclusive. If step is positive, the last element is the largest start + i * step less than stop; if step is negative, the last element is the smallest start + i * step greater than stop.
d3.range with one argument
d3.range(6) returns [0, 1, 2, 3, 4, 5].
d3.range with negative step
d3.range(5, -1, -1) returns [5, 4, 3, 2, 1, 0].
d3.range with infinity
If the returned array would contain an infinite number of values, d3.range returns an empty array. d3.range(Infinity) returns [].
d3.range with floating point step
d3.range(0, 1, 0.2) returns [0, 0.2, 0.4, 0.6000000000000001, 0.8]. This behavior is due to IEEE 754 double-precision floating point. Use d3-format to format numbers for human consumption with appropriate rounding.
d3.range floating point precision workaround
To generate a range with a specific length avoiding floating point errors, use d3.range with an integer range and map to the desired values. For example, use d3.range(49).map((d) => d / 49) instead of d3.range(0, 1, 1 / 49) to reliably return 49 elements.
d3.range values calculation
The values in the array returned by d3.range are defined as start + i * step, where i is an integer from zero to one minus the total number of elements in the returned array.
d3.cross signature and behavior
d3.cross(...iterables, reducer) returns the Cartesian product of the specified iterables. If a reducer function is specified, it is invoked for each combination of elements from each iterable and returns the corresponding reduced value. Example: d3.cross([1, 2], ["x", "y"]) returns [[1, "x"], [1, "y"], [2, "x"], [2, "y"]]. With a reducer: d3.cross([1, 2], ["x", "y"], (a, b) => a + b) returns ["1x", "1y", "2x", "2y"].
d3.merge signature and behavior
d3.merge(iterables) merges the specified iterable of iterables into a new flat array. It is similar to Array.concat but more convenient when working with an array of arrays or an iterable of iterables. Example: d3.merge([[1], [2, 3]]) returns [1, 2, 3]. Works with any iterable type: d3.merge(new Set([new Set([1]), new Set([2, 3])])) returns [1, 2, 3].
d3.pairs signature and behavior
d3.pairs(iterable, reducer) returns an array of adjacent pairs of elements from the specified iterable in order. If the iterable has fewer than two elements, returns the empty array. Example: d3.pairs([1, 2, 3, 4]) returns [[1, 2], [2, 3], [3, 4]]. With a reducer function, it is successively passed elements i-1 and i: d3.pairs([1, 1, 2, 3, 5], (a, b) => b - a) returns [0, 1, 1, 2].
d3.transpose signature and behavior
d3.transpose(matrix) transposes a two-dimensional matrix using the zip operator. Example: d3.transpose([["Alice", "Bob", "Carol"], [32, 13, 14]]) returns [["Alice", 32], ["Bob", 13], ["Carol", 14]]. The operation is reversible: d3.transpose([["Alice", 32], ["Bob", 13], ["Carol", 14]]) returns [["Alice", "Bob", "Carol"], [32, 13, 14]].
d3.zip signature and behavior
d3.zip(...arrays) returns an array of arrays, where the ith array contains the ith element from each of the argument arrays. The returned array is truncated in length to the shortest array in the input. If arrays contains only a single array, the returned array contains one-element arrays. With no arguments, the returned array is empty. Example: d3.zip(["Alice", "Bob", "Carol"], [32, 13, 14]) returns [["Alice", 32], ["Bob", 13], ["Carol", 14]].
d3.filter signature and behavior
d3.filter(iterable, test) returns a new array containing the values from iterable in order for which the test function returns true. Unlike Array.filter, it works with any iterable type. Example: d3.filter(new Set([0, 2, 3, 4]), (d) => d & 1) returns [3].
d3.map signature and behavior
d3.map(iterable, mapper) returns a new array containing the mapped values from iterable in order as defined by the mapper function. Unlike Array.map, it works with any iterable type. Example: d3.map(new Set([0, 2, 3, 4]), (d) => d & 1) returns [0, 0, 1, 0].
d3.reduce signature and behavior
d3.reduce(iterable, reducer, initialValue) returns the reduced value defined by the reducer function, which is repeatedly invoked for each value in iterable, being passed the current reduced value and the next value. Unlike Array.reduce, it works with any iterable type. Example: d3.reduce(new Set([0, 2, 3, 4]), (p, v) => p + v, 0) returns 9.
d3-array module overview
d3-array provides functions for array manipulation, ordering, searching, and summarizing data. It includes submodules for: Add (full precision addition and summation), Bin (discrete binning), Bisect (binary search), Blur (quantitative blurring), Group (discrete grouping), Intern (maps and sets with non-primitive values), Sets (logical set operations), Sort (sorting and reordering), Summarize (summary statistics), Ticks (representative values from intervals), and Transform (deriving new arrays).