D3 - Data (Operator|Join) (Data binding to elements)

Card Puncher Data Processing

About

The data operator (binds|joins) input data to selected nodes.

The data join is a general pattern that can be used to create, update or destroy elements whenever data changes.

The data-join takes as input an array of data and an array of document elements, and returns three selections:

  • The enter selection represents “missing” elements (incoming data) that you may need to create and add to the document.
  • The update selection represents existing elements (persisting data) that you may need to modify (for example, repositioning).
  • The exit selection represents “leftover” elements (outgoing data) that you may need to remove from the document.
  • The merge selection that unify the enter and update selections.

The data-join doesn’t modify the document itself. It computes enter, update and exit, and then you apply the desired operations to each. That affords expressiveness: for example, to animate elements as they enter and exit.

For each entry in the data array, we need a corresponding element in the document. This is the purpose of the data-join: a concise method for transforming a document :

  •  adding,
  • removing,
  • or modifying elements 

So that the element visual corresponds to data.

The data-join is something you use often — when first creating a visualization, and again whenever the data changes.

Key

By default, data is joined to elements by index: the first element to the first datum, and so on.

For precise control over data-element correspondence, a key function can be passed to the data operator.

Matching key values preserve object constancy across transitions.

Process

Data Node Join D3 Data Join

The output of a join between data (blue) and nodes (orange) are three sub-selections:

  • the enter sub-selection: The data without corresponding nodes,
  • the update sub-selection: The data with nodes,
  • the exit sub-selection: The nodes without corresponding data.

For example, if data is joined to the empty selection, the enter operator returns placeholder nodes for each incoming datum; these nodes can then be instantiated via append or insert.

The delineation of enter, update and exit allows precise control of the element lifecycle.

In terms of relational algebra, given data D and nodes N:

  • the enter selection is D ⟕ N (left join),
  • the exit selection is N ⟕ D (right join),
  • and the update selection is <math>D \Join N</math> (inner join).

Operator

data

data operator: The updating nodes are simply returned by the data operator, convenient for the common case where the enter and exit selections are empty.

Example where the svg element is empty

d3.select('svg').selectAll('circle').data(data)

result in an array of placeholder element to bind data

exit

exit operator: If new data is joined to an existing selection, the exit operator returns elements currently in the document that are not bound to the new data to allow removal.

enter

enter operator: If new data is joined to an empty selection, the enter operator returns data not bound to existing elements to allow elements addition.

Example where the svg element is empty

d3.select('svg').selectAll('circle').data(data).enter()

result in an array of javascript objects with a __data__ field

merge

The merge method unify the enter and update selections.

Example

From General Update Pattern 4.0

var text = g
  .selectAll("text")
  .data(data, key); // JOIN
text.exit() // EXIT
    .remove();
text.enter() // ENTER
  .append("text")
    .text(function(d) { return d; })
  .merge(text) // ENTER + UPDATE
    .attr("x", function(d, i) { return i * 32; });

Documentation / Reference





Discover More
Card Puncher Data Processing
D3 - (Architecture|Design)

D3’s atomic operand is the selection: a filtered set of elements queried from the current document. Operators act on selections, modifying content. Data joins bind input data to elements, enabling...
Card Puncher Data Processing
D3 - (Element) Lifecycle (The three state: Enter, Update, Exit)

The element lifecycle in D3 has the three state: enter, update and exit They are the output of a data join operation Defining the state of the element during a data join is crucial for efficientdynamic...
Card Puncher Data Processing
D3 - Data

Input Data is specified as an array of arbitrary values, such as: numbers, strings or objects. The data format and their related processing is agnostic. : The data operator binds input data...
Card Puncher Data Processing
D3 - Getting Started

Whether you’re building a static chart or a dynamic one with fluid transitions and object constancy, your code remains roughly the same. See also: The...
Card Puncher Data Processing
D3 - Operator

Operators act on selections, modifying content. Operator values are specified either as constants or functions; the latter (the functions) are evaluated for each element. (The functions are evaluated...
Data Node Join
D3 - Subselection (select, selectAll)

Whereas the top-level select methods query the entire document, a selection’s select and selectAll operators restrict queries to descendants of each selected element; we call this subselection. ...



Share this page:
Follow us:
Task Runner