Using D3 Built-Ins

D3 defines seven built-in symbol types for use with the d3.symbol() generator; see Figure 5-2. Example 5-1 demonstrates how you can create and use them; the resulting graph is shown in Figure 5-3.

Figure 5-2. Predefined D3 symbol shapes. (If the name of the last symbol confuses you, try pronouncing it!)

The symbol generator is a bit different than the other D3 shape generators because it does not consume a data set. All you can configure are the symbol type and size (see Table 5-1). In particular, there are no provisions to fix the position of the symbol on the graph! Instead, all symbols are rendered at the origin, and you use SVG transforms to move them into their final positions. This is a common idiom when working with D3 and SVG; we will see it often. Some useful information on SVG transformations is in “SVG Transformations”.

Figure 5-3. Using predefined symbols to represent data

function makeSymbols() {
    var data = [ { "x":  40, "y":   0, "val": "A" },              
                 { "x":  80, "y":  30, "val": "A" },
                 { "x": 120, "y": -10, "val": "B" },
                 { "x": 160, "y":  15, "val": "A" },
                 { "x": 200, "y":   0, "val": "C" },
                 { "x": 240, "y":  10, "val": "B" } ];

    var symMkr = d3.symbol().size(81).type( d3.symbolStar );      
    var scY = d3.scaleLinear().domain([-10,30]).range([80,40]);   

    d3.select( "#symbols" ).append( "g" )                         
        .selectAll( "path" ).data(data).enter().append( "path" )  
        .attr( "d", symMkr )                                      
        .attr( "fill", "red" )
        .attr( "transform",                                       
               d=>"translate(" + d["x"] + "," + scY(d["y"]) + ")" );

    var scT = d3.scaleOrdinal(d3.symbols).domain(["A","B","C"]);  

    d3.select( "#symbols" )
        .append( "g" ).attr( "transform", "translate(300,0)" )    
        .selectAll( "path" ).data( data ).enter().append( "path" )
        .attr( "d", d => symMkr.type( scT(d["val"]) )() )         
        .attr( "fill", "none" )                                   
        .attr( "stroke", "blue" ).attr( "stroke-width", 2 )
        .attr( "transform",                                       
               d=>"translate(" + d["x"] + "," + scY(d["y"]) + ")" );
}

Define a data set, consisting of x and y coordinates and an additional “value.”

The d3.symbol() factory function returns a symbol generator instance. Here, we immediately configure the size of the symbols and select the star shape as the type to use. (The size parameter is proportional to the symbol’s area, not its radius.)

Conveniently, the x values in the data set will work as pixel coordinates, but we need a scale object to translate the y values to vertical positions. The inverted range() interval compensates for the upside-down graphical coordinates used by SVG.

Create an initial selection and append a <g> element. This <g> will hold the symbols on the left side of the graph and keep them separate from the ones on the right.

Bind the data and create a new <path> element for each data point.

Populate the d attribute of the previously created <path> element using the symbol generator. Because the symbol generator is already fully configured, we don’t need to do anything else at this point. The symbol generator is not evaluated, but instead is supplied as a function; it will automatically be invoked for each data point by the selection.

Move each newly created <path> element to its final position through an SVG transform, using the scale object to calculate the vertical offset.

For the right side of the graph, we will change the shape of the the symbol according to the third column in the data set. To do so, we need to associate the values from the data set with symbol shapes. An ordinal (or discrete) scale is essentially a hashmap that associates each value in the input domain with a value in the array d3.symbols of available symbol shapes. (See Chapter 7 to learn more about the different scale objects.)

Append a new <g> element for the second set of symbols, and shift it to the right. This shift will also apply to all children of the <g> element.

We can reuse the symbol generator instance created earlier. Here, every time the symbol generator is invoked, its type is set explicitly, based on the value in the data set.

For a change, the symbols are not filled; only the outlines are shown.

The transform to move each symbol into position is exactly the same as before. There is no need to change it, because the entire containing <g> element has been moved to avoid overprinting the stars on the left side.

This example demonstrates the basic techniques; many further variations are possible. For example, not only the shape but also the size and color of each symbol can be varied dynamically. To choose a color, the ordinal scale will come in handy again, like so:

d3.scaleOrdinal(["red","green","blue"]).domain(["A","B","C"]);

Or choose contrasting colors for interior and boundary (fill and stroke) to achieve a different effect.

Custom Symbols

The way generators are used in Example 5-1 may appear a bit opaque, but there is really no magic here. Ultimately, all that happens is that the generator instance returns a string of commands using the <path> element’s command syntax. You can do that. For example, if you define the following function:¹

function arrow() {
    return "M0 0 L16 0 M8 4 L16 0 L8 -4";
}

then you can replace step 6 in Example 5-1 with:

.attr( "d", arrow )

Now try applying a data-dependent rotation, using an appropriate SVG transform, to the generated <path> element! There are many more options.

SVG Fragments as Symbols

The <use> tag lets you reuse arbitrary SVG fragments within a document and hence provides an alternative for creating reusable symbols in SVG.² It is recommended (but not required) that components intended for reuse are defined inside of the SVG document’s <defs> section. (The <defs> section must be part of the SVG document; do not place it into the header of the HTML page, for example!) Example 5-2 shows a document that defines a reusable component inside its <defs> section, and Example 5-3 shows how one might use it. (See Figure 5-4 for the result.)

<svg id="usedefs" width="275" height="100">
  <defs>                                                         
    <g id="crosshair">                                           
      <circle cx="0" cy="0" r="2" fill="none"/>                  
      <line x1="-3" y1="0" x2="-1" y2="0" />
      <line x1="1" y1="0" x2="3" y2="0" />
      <line x1="0" y1="-1" x2="0" y2="-3" />
      <line x1="0" y1="1" x2="0" y2="3" />
    </g>
  </defs>
</svg>

Open a <defs> section as a child of the <svg> element.

Create a <g> element that will be the container for all elements making up the symbol, and assign an id to it. The <use> tag will refer to this symbol via the identifier specified here.

Add the graphical elements for the symbol. Remember that the symbol can be rescaled when it is being used, hence its absolute size is not important here.

function makeCrosshair() {
    var data = [ [180, 1], [260, 3], [340, 2], [420, 4] ];        

    d3.select( "#usedefs" )
        .selectAll( "use" ).data( data ).enter().append( "use" )  
        .attr( "href", "#crosshair" )                             
        .attr( "transform",                                       
               d=>"translate("+d[0]+",50) scale("+2*d[1]+")" )
        .attr( "stroke", "black" )                                
        .attr( "stroke-width", d=>0.5/Math.sqrt(d[1]) );          
}

A minimal data set. The first component of each record will be used for the horizontal position, the second one for the symbol size.

Select the SVG element and bind data as usual, creating a <use> element for each record in the data set.

Set the href attribute for every newly created <use> element to the symbol identifier. The final element in the page will look something like: <use href="#crosshair" ...>.

Use the transform attribute to choose the symbol’s position and size.

Set the stroke color. It is necessary to do so explicitly, because the default value of the stroke attribute is none!

Set the stroke width. To obtain strokes of roughly equal width in the figure, the stroke width must be chosen so as to cancel the effect of the earlier scale transformation.

Figure 5-4. Creating symbols with <use> tags (also see Example 5-3)

Of course, the contents of the <defs> section is no different than the rest of the document, which means that it, too, can be generated dynamically using D3. For example, the following snippet creates a diagonal cross (also called a “saltire”) that can be invoked through <use> tags:³

var d = d3.select("svg").append("defs")
    .append("g").attr("id", "saltire");
d.append("line")
    .attr("x1",-1).attr("y1",1).attr("x2",1).attr("y2",-1);
d.append("line")
    .attr("x1",-1).attr("y1",-1).attr("x2",1).attr("y2",1);

Yet another way is to load the appropriate SVG from a file and insert it into the current document (see Chapter 6 for an example).

Built-In Curves

In addition to straight lines, D3 offers a variety of other curve shapes to connect consecutive points—and you can also define your own. You choose a different curve shape by passing the appropriate curve factory to the line generator, like so:

var lnMkr = d3.line().curve( d3.curveLinear );

The built-in curve factories (see Figure 5-6) fall into two major groups:

• Curves that are completely determined by the data set and that pass exactly through all data points (see Table 5-3).

• Curves that depend on an additional curvature or stiffness parameter and that may not pass exactly through the data points (see Table 5-4).

The built-in curves are primarily intended for information visualization; they were not developed for scientific curve plotting. Curves are drawn in the order of the points in the data set; data points are not reordered based on the x coordinates! The built-in curves make no direct provisions for curve fitting, for filtering noisy data, or for weighting data points according to their local error. If you need such functionality, you will have to implement it yourself, for example, by implementing a custom curve generator (see the next section), or by first processing the input data separately. The D3 Reference Documentation contains additional details and references to the original literature.

Figure 5-6. Built-in curve factories. The values of the adjustable parameter for the bottom row are 0.0 (blue), 0.25, 0.5, 0.75, and 1.0 (red).

d3.curveCardinal.tension(0.5);
d3.curveCatmullRomClosed.alpha(0.25);

Custom Curves

If you are dissatisfied with the built-in curves, you can provide your own curve algorithms by supplying a custom curve factory to the line generator—for example, to implement a fitting or smoothing method.⁴ A curve factory is a function that accepts a single argument and returns an object that implements the curve API. When D3 invokes the factory function, it supplies a d3.path object as the argument. The d3.path facility exposes a turtle graphics interface similar to the command language of the <path> element. Your implementation of the curve API must populate this object according to your algorithm. The curve API, which your custom code must implement, consists of three functions: lineStart(), lineEnd(), and point(x, y)—their semantics will be explained in a moment. Eventually, D3 will turn the path object into a string that can be used to populate the d attribute of a <path> element.

Let’s consider a very simple example, just to explain the mechanism. Example 5-5 implements a curve factory that draws a horizontal line at the median of the vertical positions of all the data points for each line segment. It behaves exactly like the built-in factories; for example, you could use it in Example 5-4 like so:

var lnMkr = d3.line().curve( curveVerticalMedian );

function curveVerticalMedian( context ) {
    return {
        lineStart: function() {
            this.data = [];                                       
        },

        point: function( x, y ) {
            this.data.push( [x, y] );                             
        },

        lineEnd: function() {
            var xrange = d3.extent( this.data, d=>d[0] );         
            var median = d3.median( this.data, d=>d[1] );

            context.moveTo( xrange[0], median );                  
            context.lineTo( xrange[1], median );                  
        }
    };
}

The lineStart() function is called at the beginning of every line segment (remember that every point data point marked as “undefined” ends the current and forces a new line segment). Here, an array is initialized that will hold the data points.

The point(x, y) function is called for every data point with the coordinates of that point. In this case, the coordinates of each point are simply appended to the end of the array.

The lineEnd() function is called at the end of each line segment. Now that all the data points for the current line segment have been collected, the horizontal extent of the data set and the median of the vertical positions can be found, and with this information, we are now ready to draw the desired line.

The context variable is a d3.path instance, which is supplied to the curve factory by the D3 infrastructure. This object exposes functions similar to the command language of the <path> element. All drawing has to be done using this object. Here, we invisibly place the pen at the beginning of the line and…

… draw a visible line to its end.

This is the basic workflow. With a little more work, you can change the lineEnd() function to calculate and draw, for example, a linear regression line, a locally weighted interpolation such as LOESS, or a kernel density estimate.⁵

If the resulting curve is not a straight line, then it will generally be necessary to build it up from individual pieces in a loop. In the following snippet, the horizontal plot interval is broken into 100 steps:

for( var t = xmin; t <= xmax; t += 0.01*(xmax-xmin) ) {
    context.lineTo( t, y(t) );
}

Here, xmin and xmax are the end points of the plot interval, and y(t) is the computed value of the curve at position t.

To calculate the median or a linear regression, the entire data set must be known before computation and drawing can begin. Other curves can be calculated and drawn incrementally—straight lines connecting consecutive points, for example. In this case, the main logic moves from the lineEnd() function to the point() function: for each new data point, the next part of the curve is calculated and the appropriate d3.path methods are called to draw it.

A Simple Component

Let’s say that we want to use, in multiple locations in a graph, a rectangle with rounded corners and a text label centered inside of it (see Figure 5-8). In this kind of situation, it is convenient to keep the relative positioning of the parts within the component (text and border) separate from the positioning of the entire component itself. The sticker() function in Example 5-8 creates both the rectangle and the text inside of it centered at the origin. It is then up to the calling code to move both of them together to the final position.

Figure 5-8. A reusable component

function sticker( sel, label ) {                                  
    sel.append( "rect" ).attr( "rx", 5 ).attr( "ry", 5 )          
        .attr( "width", 70 ).attr( "height", 30 )
        .attr( "x", -35 ).attr( "y", -15 )
        .attr( "fill", "none" ).attr( "stroke", "blue" )
        .classed( "frame", true );                                

    sel.append( "text" ).attr( "x", 0 ).attr( "y", 5 )            
        .attr( "text-anchor", "middle" )
        .attr( "font-family", "sans-serif" ).attr( "font-size", 14 )
        .classed( "label", true )
        .text( label ? label : d => d );                          
}

function makeSticker() {
    var labels = [ "Hello", "World", "How", "Are", "You?" ];
    var scX = d3.scaleLinear()
        .domain( [0, labels.length-1] ).range( [100, 500] );
    var scY = d3.scaleLinear()
        .domain( [0, labels.length-1] ).range( [50, 150] );

    d3.select( "#sticker" )                                       
        .selectAll( "g" ).data( labels ).enter().append( "g" )
        .attr( "transform",
               (d,i) => "translate(" + scX(i) + "," + scY(i) + ")" )
        .call( sticker );

    d3.select( "#sticker" ).append( "g" )                         
        .attr( "transform", "translate(75,150)" )
        .call( sticker, "I'm fine!" )
        .selectAll( ".label" ).attr( "fill", "red" );             
}

A component is simply a function that takes a Selection instance as its first argument. The remaining parameters are arbitrary.

Create and configure the rectangle as a child of the supplied selection. The rectangle is centered at the origin.

Assign a CSS class to the rectangle: this will make it easier to identify it later for styling. The second parameter to classed() is important: true indicates that the class name should be assigned to the element, whereas false indicates that the class name should be removed.

Create and configure the text element and assign it a class name as well.

If a second argument has been supplied when the sticker() function was called, use it as the label. Otherwise, use the data bound to the current node. This makes it possible to use this component regardless of whether data is bound to the target selection or not.

To use this component with bound data, create a <g> element for each data point as usual, and then invoke the sticker() function using call(). This will execute the sticker() function, while supplying the current selection as the first argument. In this case, the “current selection” contains the newly created <g> elements (with their bound data).

To use this component without bound data, again append a <g> element as the container for the sticker, and invoke sticker() via call(), but this time you must supply a label explicitly. The call() facility will simply forward any arguments past the first one when invoking the supplied function.

The CSS class name makes it easy to select part of the component to change its appearance. Keep in mind, however, that selectAll() returns a new selection: any subsequent calls in the chain of function calls will only apply to the elements that matched the ".labels" selector!

Working with Components

A few general comments about working with components:

• A component is usually created inside of a <g> element as the common parent to all parts of the component: for example, so that the entire component can be moved to its final location through an SVG transformation applied to the containing <g> element. This <g> element is usually not created by the component, but by the calling code. If this seems surprising, keep in mind that the component does not return the elements it creates, but adds them directly to the DOM tree. To do so, it needs to know where to add them, and the calling code must supply this information—hence the surrounding code creates the <g> element as the destination for the component to add its results.

• Although a component can be invoked using regular function call syntax, with the destination Selection as the first argument, it is more idiomatic to invoke it “synthetically” using the call() function. The call() function will automatically inject the destination Selection as the first argument and return the same Selection instance, thus enabling method chaining. If you need to gain access to the new DOM elements that were created by the component, use selectAll() with an appropriate selector on the Selection returned by call(). The typical call sequence therefore looks like this:

  d3.select("svg").append("g").attr( "transform", ... )
      .call( component )
      .selectAll( "circle" ).attr( "fill", ... )...

  Also see the very end of Example 5-8 for an example.

• Although it is possible to pass in appearance options (like color and so on) as additional parameters to the component, it is usually more idiomatic to apply them later on using the usual mechanisms of the Selection API (as was done toward the end of Example 5-8). This has the advantage that the appearance of the component is not fixed by its author, but can be changed—as desired—by the user.

A Component to Save Keystrokes

Whereas the sticker component in the previous section can reasonably claim to be reusable, a component can also make sense as nothing more than an ad hoc labor-saving device to save keystrokes in a local scope. For example, imagine that you need to add <text> elements in several spots, all of which should use different text alignments and font sizes. Let’s also assume a situation where it is not possible or practical to collect these presentational attributes in a stylesheet or on a common parent. An ad hoc component like the following can relieve you from having to type the attribute names and function calls for every <text> element explicitly:

function texter( sel, anchor, size ) {
    return sel.attr( "text-anchor", anchor )
        .attr( "font-size", size )
        .attr( "font-family", "sans-serif" );
}

And you use it simply as shorthand where appropriate:

d3.select( ... )
    .append( "text" ).call( texter, "middle", 14 ).text( ... );

Similar ad hoc components might be useful to set the fill and stroke colors of an object in one fell swoop, or to create a circle with its center coordinates and radius in a single call.

SVG Transformations as Components

SVG transformations are extremely useful—but, unfortunately, they are also a bit verbose, in particular when you need to build up the argument string dynamically. A labor (and space) saving device would be welcome! (This section is probably best skipped on first reading.)

It’s easy enough to write a component for that purpose (in this section, I’ll restrict myself to translations for simplicity; extensions to more general SVG transformations are straightforward):

function trsf( sel, dx, dy ) {
    return sel.attr( "transform", "translate("+dx+","+dy+")" );
}

And you would invoke it like any other component:

d3.select( ... ).append("g").call(trsf, 25, 50).append( ... )...

This is fine as far as it goes, but what if the offsets should depend on data bound to a selection? What we want to do is this (compare, for instance, Example 5-8):

d3.select( ... ).data( data ).enter().append( "g" )
    .call( trsf, (d,i)=>..., (d,i)=>... ).append( "circle" )...

But the simple trsf() component just introduced will not work in that situation. In order to handle accessor functions as arguments, the component must distinguish whether these arguments are functions or constants, and evaluate them in the former case. One problem that arises if we want to stay within the published Selection API (instead of poking under the hood) is that the API functions only allow for one accessor function to be evaluated simultaneously, but our trsf() takes two. Hence we need to evaluate the first accessor for all elements of the selection, store the results, then evaluate the second accessor, and finally combine the intermediate results to create the actual transform attribute value. The following code makes use of the d3.local() facility, intended for just this kind of application. It is essentially a hashmap, but expects a DOM Node as key. In this way, it is possible to store an intermediate value per Node:

function trsf( sel, dx, dy ) {
    var dxs = d3.local(), dys = d3.local();
    sel.each( function(d,i) {
        dxs.set( this,
                 typeof dx==="function" ? dx(d,i) : dx||0 ) });
    sel.each( function(d,i) {
        dys.set( this,
                 typeof dy==="function" ? dy(d,i) : dy||0 ) });

    return sel.attr( "transform", function() {
        return "translate(" +
            dxs.get(this) + "," + dys.get(this) + ")"} );
}

A simpler but less clean method is to store the intermediate result in the node itself by adding additional “bogus” properties to it:

sel.each( function(d,i) {
    this.bogus_dx = typeof dx==="function" ? dx(d,i):dx||0 } );

Either way, the trsf() component can now be called as intended. For example, the following code could be added to Example 5-8:

var vs = [ "This", "That" ];
d3.select( "#sticker" ).append( "g" )
    .selectAll( "g" ).data( vs ).enter().append( "g" )
    .call( trsf, (d,i) => 300 + scX(i), (d,i) => scY(i) )
    .call( sticker );