Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 44 ยท Selections and Data Joins

Data Utilities with d3-array

Summarize and reshape data with d3-array: extent, min, max, sum, mean, median, quantile, group, rollup, bin, sort, range, cumsum, bisect and ticks.

Charts rarely draw raw data. You first need the highest value for an axis, the average per category, or a histogram of counts. The d3-array module is a toolbox for exactly this kind of work. Its functions take arrays (or any iterable) and an optional accessor function, so they work directly on arrays of objects. You will use them in nearly every chart in this track.

Summaries: min, max, extent, sum, mean, median

d3.min, d3.max and d3.extent ignore undefined, null and NaN values, which makes them safer than Math.min(...array). d3.extent returns [min, max], ideal for a scale's domain.

JavaScript
const sales = [{ item: "pen", qty: 12 }, { item: "ink", qty: 5 }, { item: "pad", qty: 20 }];

d3.max(sales, d => d.qty);      // 20
d3.extent(sales, d => d.qty);   // [5, 20]
d3.sum(sales, d => d.qty);      // 37
d3.mean(sales, d => d.qty);     // 12.333...
d3.median(sales, d => d.qty);   // 12

Related functions: d3.deviation and d3.variance for spread, d3.quantile(sorted, p) for percentiles, d3.mode, d3.maxIndex / d3.minIndex (the position of the extreme), and d3.least / d3.greatest (the extreme element, such as the object with the highest qty).

Summaries

Note that null is ignored by D3 but Math.min treats it as 0, so the plain JavaScript way silently returns 0 instead of 5 on this dirty data.

Sorting and comparing

d3.ascending and d3.descending are comparator functions that handle undefined and NaN sensibly. Pass them to Array.prototype.sort, or use d3.sort(array, accessor) which returns a new sorted array without mutating the original. d3.sort(data, d => d.qty) sorts ascending by a field; d3.sort(data, (a, b) => d3.descending(a.qty, b.qty)) sorts descending.

JavaScript
const bySize = d3.sort(sales, d => d.qty);
const top3 = d3.sort(sales, (a, b) => d3.descending(a.qty, b.qty)).slice(0, 3);

Grouping: group, rollup, groups, index

Turning a flat table into categories is one of the most common data tasks.

Function Result
d3.group(data, keyFn) Map from key to array of rows
d3.groups(data, keyFn) Array of [key, rows] pairs
d3.rollup(data, reduceFn, keyFn) Map from key to a summary of that group's rows
d3.rollups(...) The same as an array of [key, value] pairs
d3.index(data, keyFn) Map from key to a single row (keys must be unique)

Pass several key functions to nest more levels: d3.group(data, d => d.year, d => d.city).

group and rollup

Array.from(map, ([key, value]) => ({...})) is the standard way to convert a rollup back to the array-of-objects shape that selections and joins like.

Binning: histograms

d3.bin() creates a histogram generator. You set which value to bin (.value), the range (.domain) and the number of bins (.thresholds). Calling it on your data returns an array of bins; each bin is an array of the original items with x0 and x1 bounds.

JavaScript
const bins = d3.bin()
  .value(d => d.score)
  .domain([0, 100])
  .thresholds(5)(students);

thresholds can be a count, an array of explicit interior cut points (the domain ends are added for you), or a rule like d3.thresholdSturges. Bin lengths give the bar heights for a histogram chart.

A histogram from bins

Generating and transforming sequences

  • d3.range(start, stop, step) returns an array of numbers: d3.range(5) is [0, 1, 2, 3, 4], d3.range(0, 1, 0.25) gives quarters. Excellent for fake data and axis ticks.
  • d3.ticks(a, b, count) gives about count "nice" tick values between a and b; d3.tickStep returns the spacing.
  • d3.cumsum(values) gives running totals; d3.pairs(array) returns neighbouring pairs [a0,a1], [a1,a2]...; d3.zip(a, b) interleaves arrays.
  • d3.shuffle(array) randomizes in place; d3.cross(a, b) makes the cartesian product (useful for grids and matrices); d3.transpose(matrix) flips rows and columns.
  • d3.bisect(sorted, x) finds where x would insert in a sorted array. Charts use bisector to find the data point nearest the mouse (chapter 6).
range, ticks, cumsum, pairs, bisect

Most d3-array functions work on any iterable (arrays, Sets, Maps' values) and accept an accessor as the last argument, so d3.sum(data, d => d.qty) and d3.sum(data.map(d => d.qty)) are equivalent. The accessor form avoids creating a temporary array.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why prefer d3.max(data, d => d.v) over Math.max(...data.map(d => d.v))?

    d3-array skips missing values, so dirty data does not corrupt the result, and the accessor form creates no temporary array.
  2. 2. What does d3.rollup(data, rows => rows.length, d => d.city) return?

    rollup groups by key and then reduces each group's rows with the given function, here to a count.
  3. 3. How do you convert a rollup Map into an array of objects for a join?

    Maps are iterable of [key, value] pairs, so Array.from with a mapping function produces objects.
  4. 4. What is the result of d3.range(0, 1, 0.5)?

    range excludes the stop value, so it returns [0, 0.5].
  5. 5. What does d3.bin() give you?

    Bins are arrays of data items with x0 and x1 properties, ready to draw as histogram bars.

Summary

  • extent, min, max, sum, mean, median and quantile summarize arrays and ignore missing values.
  • group, rollup, groups, rollups and index reshape rows by category; Array.from(map, ...) gets arrays of objects back.
  • d3.bin() builds histograms; range, ticks, cumsum, pairs, cross, transpose and bisect handle sequences.
  • Prefer the accessor form over building temporary arrays.

Next: Scales: Mapping Data to Pixels