D3js: When to use .datum() and .data()?
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.
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.datamethod, 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, "data" is plural, the "datum" 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)
A very good tutorial with example is here. http://bost.ocks.org/mike/selection/#data