Tutorial: The basics: working with arrays in D3

In this tutorial we’re going to cover some basic stuff in D3: ranges, min and max and merge. These are all pretty straightforward, but nevertheless very useful to have in your D3 toolbox!


Ranges are actually a pretty convenient way to generate a list of numbers. It is modeled after the built-in range method from Python. The full signature of the function looks like this:

d3.range(start, stop, step)

But the stop and step parameters are optional. So if you provide just the start parameter, you would do something like this:


The result of this function call is an array of numbers, starting with 0, and the last number in the array is 4, so 5 is not included:

[0, 1, 2, 3, 4]

Now, if you provide a second argument, it will be interpreted as the stop parameter. Note that the order of the parameters is: start first, and then the stop parameter. So, the result of this:

d3.range(3, 5);

is this:

[3, 4]

Note that again 5 is exclusive. At the moment it is not possible to create descending arrays directly with d3.range(), so if the start value is larger than the stop value, you get an empty array. In order to create a descending array of numbers, you can just call the standard reverse() Javascript function. So, to create the following result:

[4, 3, 2, 1]

you would write this:

d3.range(1, 5).reverse();

The last parameter you can use is the step parameter. If you don’t provide a step argument, it will default to 1. But if you do, then the result of this:

d3.range(5, 10, 2);

is this:

[5, 7, 9]

d3.min() and d3.max()

So, now you know how to generate a list of numbers in an easy way. Next up is the usage of min and max. It is really straightforward: to find the max number of an array of numbers, you use:

d3.max([4, 2, 6, 3, 8, 2]);

which will return 8 of course. Likewise, if you want to find the min number of an array, you use:

d3.min([4, 2, 6, 3, 8, 2]);

which will return 2 in this case.


The d3.merge() can be used to merge an array of arrays so that it becomes one array. It’ll become clear when you see an example. If you have the following 2-dimensional array:

[[1, 2, 3], [4, 5, 6]]

you can turn this into a 1-dimensional array by calling the d3.merge() function:

d3.merge([[1, 2, 3], [4, 5, 6]]);

This will result in the following 1-dimensional array:

[1, 2, 3, 4, 5, 6]

The d3.merge() function will only merge one level. For example, the following 3-dimensional array will not result in a single 1-dimensional array:

d3.merge([[[1, 2], [3]], [[4, 5], [6]]]);

It will however, result in a 2-dimensional array:

[[1, 2], [3], [4, 5], [6]]


  • Kyle Foreman
    June 6, 2011 - 08:03 | Permalink

    Not sure if this feature is new since this tutorial went up, but an even easier way to do descending arrays in d3 is to simply give a negative integer for the step size:

    e.g d3.range(5,1,-1)
    returns [5,4,3,2]

    Thanks for the tutorials!

  • Pingback: Interactive: Athletics world record progression « dataist

  • bct
    November 17, 2011 - 18:49 | Permalink

    “But the stop and step parameters are optional.” I think you mean, the “start” and the step are optional?

  • March 21, 2012 - 13:37 | Permalink

    This is simple enough. Thanks.

    Any thoughts on the use of D3′s post-parse CSV format? The D3 documentation doesn’t really elaborate on it, much, but it is a useful format to work with, in its native form. It looks something like:

    var dataSet1 = [
    {"setName": "Data Set 1", "label": "Label 1", "value": "25"},
    {"setName": "Data Set 1", "label": "Label 2", "value": "10"},
    {"setName": "Data Set 1", "label": "Label 3", "value": "2"},
    {"setName": "Data Set 1", "label": "Label 4", "value": "45"},
    {"setName": "Data Set 1", "label": "Label 5", "value": "15"},
    {"setName": "Data Set 1", "label": "Label 6", "value": "85"}

    I personally find it very useful.

    It would be nice to have a documented tutorial to help people understand the different ways to use and apply such a data format to get to different types of visualizations… like a bar chart, a line chart, a pie chart, etc.

    Anyhow, thanks again for the post. Keep it up!


  • Pingback: D3.js – Data-Driven Documents « rg443blog

  • Leave a Reply

    Your email address will not be published. Required fields are marked *


    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>