D3js: When to use .datum() and .data()?

Question

I often see .datum when an area chart is used. For example:

svg = d3.select("#viz").append("svg").datum(data)

Are there any rules of thumb for when .datum is needed?

var area = d3.svg.area()  
    .x(function(d) { return x(d.x); })  
    .y0(height)  
    .y1(function(d) { return y(d.y); });  

var svg = d3.select("body").append("svg")  
    .attr("width", width)  
    .attr("height", height);  

svg.append("path") 
    .datum(data)
    .attr("d", area); 

Answer 1

I think the documentation gives a good answer to this question: https://github.com/mbostock/d3/wiki/Selections#wiki-datum.

Basically, the point is that in some cases you are not interested in the enter/exit sets when you do a selection. If this is the case, which often seems to be the case for the full chart, you use datum.

Update: It depends: when you expect no dynamic updates, which seems to be the case in your given example, datum is okay. Why? Because there is no path svg element yet, there is only one path element and once it is added it will not change.

If you where to have multiple path elements and dynamic changes (e.g. after each second the oldest data element gets removed and a new one gets added), than you will need data. This will give you three sets: the sets of graphic elements for which no data exists any longer, the set of elements for which the data is updated and the set of elements for which no data item existed before (respectively, the enter, update and exit sets). Once you need this I suggest you read up on the d3 documentation.

Obviously, calculating these three sets is not without a cost. In practice, this should only become a problem when you're working with "large" (I think d3 scales up to 10s of thousands of items) data sets.

Answer 2

A very good tutorial with example is here. http://bost.ocks.org/mike/selection/#data

Answer 3

Others linked to the tutorial, but I think the API reference on selection.datum gives the accepted answer:

Gets or sets the bound data for each selected element. Unlike the selection.data method, this method does not compute a join (and thus does not compute enter and exit selections).

Since it does not compute a join, it does not need to know a key function. Therefore, notice the signature difference between the two, only the data function accepts a key function

• selection.datum([value])
• selection.data([values[, key]])

I think the tutorial for data gives another more basic difference which is analogous to the meaning of the words "data" and "datum". That is, the former is plural, the latter is singular. Therefore, data can be joined in two ways:

Joined to groups of elements via selection.data.

Assigned to individual elements via selection.datum.

@Hugolpz' gist gives nice examples of the significance of "groups" vs "individuals". Here, json represents an array of data. Notice how datum binds the entire array to one element. If we want to achieve the same with data we must first put json inside another array.

• var chart = d3.select("body").append("svg").data([json])
• var chart = d3.select("body").append("svg").datum(json)