D3 Visualization Options

2021-11-18

Overview

This article covers various options you can specify for D3 visualizations, including:

1. Specifying the version of the D3 library to use

2. Specifying the type of HTML container to render content withing (e.g. “svg”, “canvas”, “div”, etc.) and the ID of the containing element.

3. Enabling users of your visualization to provide options that affect it’s behavior

4. Customizing the sizing behavior of D3 visualizations

D3 Version

You can create D3 visualizations based on various versions of the D3 JavaScript library (currently versions 3, 4, and 5 are supported). The default version is 5 (the most recent release) however you can specify a a different version using thed3_version parameter. For example, to use version 3 you would do this:

r2d3(data, script="barchart.js", d3_version="3")

Note that multiple versions of D3 can co-exist within a single R Markdown document or Shiny application (r2d3 automatically handles ensuring that their namespaces don’t clash).

D3 Container

By defaultr2d3 provides an SVG container for your visualization and make it automatically available to your D3 script in thesvg variable. You can specify an alternate container via thecontainer parameter. For example, to use adiv element instead:

r2d3(data, script="barchart.js", container="div")

In this case, adiv rather than ansvg variable is automatically provided to your D3 script:

// !preview r2d3 data=c(10, 30, 40, 35, 20, 10), container="div"var bars= div  .selectAll("div")  .data(data);bars.enter().append("div")  .style("width",function(d){return4+ d*10+"px";})  .style("background-color","steelblue")  .style("border","1px solid white")  .style("color","white")  .style("padding-left","2px")  .text(function(d){return d;});

Note that when specifying the!preview comment at the top of the script you should also be sure to addcontainer = "div".

By default a random HTML element ID is generated for your visualization’s container. If you want to specify an explicit ID (for example, if you have other JavaScript that needs to explicitly discover and interact with your visualization) then use theelementId parameter. For example:

r2d3(data, script="barchart.js", container="div", elementId="my-element")

User Options

You can access user-level options (e.g. choice of colors) via theoptions object provided to your script. User options are in turn provided a named list (options) passed tor2d3(). For example:

r2d3(  data=c(0.3,0.6,0.8,0.95,0.40,0.20),   script="barchart.js",   options=list(color="orange"))

Theoptions object is then used in the expression.attr('fill', options.color) to make the fill color dynamic:

// !preview r2d3 data=c(0.3, 0.6, 0.8, 0.95, 0.40, 0.20), options = list(color = "orange")var barHeight=Math.floor(height/data.length);svg.selectAll('rect')  .data(data)  .enter().append('rect')    .attr('width',function(d){return d* width;})    .attr('height', barHeight)    .attr('y',function(d, i){return i* barHeight;})    .attr('fill',options.color);

Sizing

When you render a D3 visualization,r2d3 creates an Rhtmlwidget to host the visualization. This means that D3 visualizations inherit the default sizing behavior for htmlwidgets, including:

1. Automatically filling available space in the RStudio Viewer and in standalone web browsers.

2. Conforming to the currently activefig.width andfig.height chunk options withinR Markdown documents.

3. Filling available space when used in aShiny application or aflexdashboard.

In order to take advantage of this dynamic sizing behavior, your should ensure that your D3 visualization uses thewidth andheight variables that are provided automatically. Note the use ofheight in the computation ofbarHeight andwidth in the call to.attr() in this example:

var barHeight=Math.floor(height/data.length);svg.selectAll('rect')  .data(data)  .enter().append('rect')    .attr('width',function(d){return d* width;})    .attr('height', barHeight)    .attr('y',function(d, i){return i* barHeight;})    .attr('fill','steelblue');

Whenever the size of the parent element displaying the visualization changes (e.g. when the user resizes the RStudio Viewer) your D3 script will be re-executed to render at the new size. Note that it’s also possible to handle resizing at a more granular level if you useadvanced rendering callbacks.

Themes

To match themes provided by RStudio and other environments,r2d3 provides atheme object that containsbackground andforeground values that you can use to make your visualization match the environment which it is rendered within.

For example, to match the fill color ofrect elements with the background, we use thetheme.foreground for the stroke andtheme.background for the fill:

// !preview r2d3 data=c(0.3, 0.6, 0.8, 0.95, 0.40, 0.20)var barHeight=Math.floor(height/data.length);svg.selectAll('rect')  .data(data)  .enter().append('rect')    .attr("y",function(d, i){return i* barHeight;})    .attr('width',function(d){return d* width;})    .attr('height', barHeight)    .attr('stroke',theme.foreground)    .attr('fill',theme.background);

You can also explicitly set the theme using ther2d3.theme R option. For example:

options(r2d3.theme=list(  background="#FFFFFF",  foreground="#000000"))

Viewer

Theviewer argument to ther2d3() function enables you to customize how D3 visualizations are viewed when printed from within the RStudio console. The following options are available:

The “external” option is useful if your visualization requires more space than an RStudio pane affords. The “browser” option is useful if you need access to browser debugging tools during development.

Note that theviewer options described above are only fully supported within thepreview release of RStudio v1.2 (as opposed to the current stable release).