---
title: "Learning D3"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Learning D3}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```

## Introduction

There are a number of excellent resources available for learning how to do data visualization with D3, including online tutorials, self-paced courses, and books. There are also sites that provide numerous examples to learn from. We'll enumerate these resources below as well as provide some tips on mapping the example D3 code you'll encounter back to code that works with **r2d3**. 


## Books

<img src="images/d3_book.jpg" width=130 align="right" style="margin-left: 20px"/>

There are a number of books about D3 available, but only one has been updated to work with more recent versions of D3 (versions 4 and 5). That book is Scott Murray's [Interactive Data Visualization for the Web: An Introduction to Designing with D3](https://www.amazon.com/Interactive-Data-Visualization-Web-Introduction/dp/1491921285/). The book covers D3 from the ground up, presuming no existing experience with data visualization or web development.

The book covers bar charts, scatter plots, pie charts, stacked bar charts, force-directed graphs, and geographic visualizations. The books includes over 140 examples as well as case studies with nine accomplished designers talking about their D3-based projects.

## Online Resources

There are several good self paced online tutorials for learning D3 available, these include:

1) [Intro to D3.js from Square](http://square.github.io/intro-to-d3/)

2) [D3 in Depth from Peter Cook](https://www.d3indepth.com/)

3) [Dashing D3.js](https://www.dashingd3js.com/)

There are also a number of websites that aggregate examples of D3 visualizations, these include:

1) [The D3 Gallery](https://github.com/d3/d3/wiki/Gallery)

2) [Mike Bostock's Blocks](https://bl.ocks.org/mbostock)

3) [VIDA D3 Explorer](https://vida.io/explore)

## Coding D3 for r2d3

When you are learning D3 or translating D3 examples for use with R it's important to keep in mind that D3 examples will generally include code to load data, create an SVG or other root element, and establish a width and height for the visualization. On the other hand with **r2d3**, these variables are *provided automatically* so do not need to be created. Here is some code you'll typically see in D3 examples:

Creating an SVG element to contain the visualization:

```{js, eval=FALSE}
var svg = d3.select("body").append("svg");
```

Hard-coding margins, width, and height for the visualization:

```{js, eval=FALSE}
var margin = {top: 20, right: 20, bottom: 70, left: 40},
    width = 600 - margin.left - margin.right,
    height = 300 - margin.top - margin.bottom;
```

Loading data for the visualization:

```{js, eval=FALSE}
d3.csv("bar-data.csv", function(error, data) {
  
});
```

Code like the above isn't necessary with **r2d3**, since the following variables are provided automatically to your D3 script:

- `data` --- The R data converted to JavaScript.
- `svg` --- The svg container for the visualization
- `width` --- The current width of the container
- `height` --- The current height of the container
- `options` --- Additional options provided by the user
- `theme` --- Colors for the current theme

For example, here's a simple **r2d3** script which makes use of these automatically provided variables:

```{js, eval=FALSE}
// !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('width', function(d) { return d * width; })
    .attr('height', barHeight)
    .attr('y', function(d, i) { return i * barHeight; })
    .attr('fill', 'steelblue');
```


