Skip to content

Arrays

Jump to bottom Edit New page
mbostock edited this page May 30, 2011 · 51 revisions

API Reference

When using D3—and doing data visualization in general—you tend to do a lot of array manipulation. That's because D3's canonical representation of data is an array. Some common forms of array manipulation include taking a contiguous slice (subset) of an array, filtering an array using a predicate function, and mapping an array to a parallel set of values using a transform function. Before looking at the set of utilities that D3 provides for arrays, you should familiarize yourself with the powerful array methods built-in to JavaScript.

This includes mutator methods that modify the array:

There are also accessor methods that return some representation of 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 a function of 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).

Ordering

# d3.ascending(a, b)

Returns -1 if a is less than b, or 1 if a is greater than b, or 0. This is the comparator function for natural order, and can be used in conjunction with the built-in array sort method to arrange elements in ascending order:

function(a, b) {
  return a < b ? -1 : a > b ? 1 : 0;
}

Note that if no comparator function is specified to the built-in sort method, the default order is lexicographic (alphabetical), not natural! This can lead to bugs when sorting an array of numbers.

# d3.descending(a, b)

Returns -1 if a is greater than b, or 1 if a is less than b, or 0. This is the comparator function for reverse natural order, and can be used in conjunction with the built-in array sort method to arrange elements in descending order:

function(a, b) {
  return b < a ? -1 : b > a ? 1 : 0;
}

Note that if no comparator function is specified to the built-in sort method, the default order is lexicographic (alphabetical), not natural! This can lead to bugs when sorting an array of numbers.

# d3.min(array[, accessor])

Returns the minimum value in the given array. If the array is empty, returns undefined. An optional accessor function may be specified, which is equivalent to calling array.map(function) before computing the minimum value. Unlike the built-in Math.min, this method ignores any values that cannot be coerced to a number, such as NaN or undefined. Thus, when computing the domain of a scale from data, only the defined region of the data is considered, rather than applying a degenerate domain.

# d3.max(array[, accessor])

Returns the maximum value in the given array. If the array is empty, returns undefined. An optional accessor function may be specified, which is equivalent to calling array.map(function) before computing the maximum value. Unlike the built-in Math.max, this method ignores any values that cannot be coerced to a number, such as NaN or undefined. Thus, when computing the domain of a scale from data, only the defined region of the data is considered, rather than applying a degenerate domain.

Associative Arrays

Another common data type in JavaScript is the associative array, or more simply the object, which has a set of named properties. In Java this is referred to as a map, and in Python, a dictionary. JavaScript provides a standard mechanism for iterating over the keys (or property names) in an associative array: the for…in loop. However, note that the iteration order is undefined. D3 provides several operators for converting associative arrays to standard indexed arrays.

# d3.keys(object)

Returns an array containing the property names of the specified object (an associative array). The order of the returned array is undefined.

# d3.values(object)

Returns an array containing the property values of the specified object (an associative array). The order of the returned array is undefined.

# d3.entries(object)

Returns an array containing the property keys and values of the specified object (an associative array). Each entry is an object with a key and value attribute, such as {key: "foo", value: 42}. The order of the returned array is undefined.

Array Operators

# d3.split(array[, function])

Splits the specified array into multiple arrays at breakpoints identified by the specified function. If no breakpoint function is specified, the array will be split at any null or undefined values. Elements that are identified as breakpoints will not be included in the returned arrays. This method is often used in conjunction with the line shape, such that missing data points are elided; each contiguous slice of the array where the data is defined is rendered as a line segment.

# d3.merge(arrays)

Merges the specified arrays into a single array. This method is similar to the built-in array concat method; the only difference is that it is more convenient when you have an array of arrays.

# d3.range([start, ]stop[, step])

Generates an array containing an arithmetic progression, similar to the Python built-in range. This method is often used to iterate over a sequence of numeric or integer values, such as the indexes into an array. Unlike the Python version, the arguments are not required to be integers, though the results are more predictable if they are due to floating point precision. If step is omitted, it defaults to 1. If start is omitted, it defaults to 0. The full form returns an array of numbers [start, start + step, start + 2 * step, …]. 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. If the returned array would contain an infinite number of values, an error is thrown rather than causing an infinite loop.

Nest

# d3.nest()

# nest.key(function)

# nest.sortKeys(comparator)

# nest.sortValues(comparator)

# nest.rollup(function)

# nest.map(array)

# nest.entries(array)

Add a custom footer
Add a custom sidebar

Clone this wiki locally