Learn how to build data visualizations with the popular D3 library.

Introduction to D3

D3 "injects" data visualizations onto a web page's Document Object Model and associates data with a set of selected DOM elements. So before we go too far, let's understand the first part of the process- [the selection](https://bost.ocks.org/mike/selection/).

For D3 to inject or bind data to elements, a D3 selection of elements needs to be created. _D3 selections_ are created with the `.selectAll()` or `.select()` methods.

Both methods take one CSS3 selector string as their parameter. CSS3 selectors are strings include anything from an HTML element name such as `h1` to a class prepended with a `.`, or an id prepended with the `#` symbol. 
+ The `.select()` method returns the first element that matches a selector string. 
+ The `.selectAll()` returns an array-like structure with grouped nodes for all the elements that match the selector. 

Each element in the selection includes a reference to its parent node in the DOM.

Take a look at the following examples:
```js
d3.select('#visualization');
d3.selectAll('div');
```

+ The `.select()` element only selects the first element that matches the selector, an element with an id of `visualization`.
+ The `.selectAll()` element returns all of the elements that match the `div` selector in the DOM

Note: To create a selection, the elements do NOT need to exist in the DOM. Say you want to visualize 500 rows of data and associate them with 500 circle elements. Those elements don't need to exist inside your web page in order for d3 to "theoretically" select them. Think of selecting theoretical elements as a "prepping your stage" step. You do this so that you can eventually create those elements and bind data to each in the later steps. We will re-visit this concept in later exercises. 



Selection

So far, our code has been associating data with existing elements inside our **index.html** file. What would happen if those elements weren't already in there? We previously mentioned the idea of "hypothetically" selecting elements so that we could prep them to bind data. How do we turn theoretical elements into real ones to visualize with data? With the `.enter()` and `.append()` methods! 

But first, a quick refresher on the `.data()` method. The `.data()` method is invoked on a selection and takes a parameter of an array of any type. It returns an update selection with the data bound to the elements. This update selection works as the object invoked on the next step:

+ The `.enter()` method consolidates the difference between the number of existing elements in the selection and the number of elements in the dataset. It is invoked on the update selection that `.data()` returns. If there are more data points than existing "selected" elements, `.enter()` creates placeholder elements and returns an enter selection which specifies which elements need to be added. For example, if there were 0 existing elements in the update selection and 10 data points, enter would compute 10 elements in the enter selection. If there were 3, then it would compute 7 in the enter selection. The `.enter()` method does not actually append the elements, it just computes how many need to be added.

+ Lastly the `.append("element")` method takes a string parameter with the element name you wish to append, it then analyzes the selection that gets handed off to it, and generates the specified elements on the DOM. It returns a reference to the elements it created. 

Note: If you ever want to analyze the data in the selection and log it to the console, you can always use the `.nodes()` method on your selection. This method will log the array of grouped nodes in the selection. 

After making a selection, creating a new visualization, whose elements are not already in the DOM, usually follows the `.data()` `.enter()` and `.append()` pattern:
```js
let dataset = [55,34,23,22,59];
d3.select("body")
   .selectAll("div")
   .data(dataset)
   .enter()
   .append("div");
```
+ Everything after `.data()` will therefore get executed five times
+ The `.enter()` method created five placeholder elements because there were no `div` elements in the DOM 
+ Five div's were appended with the div elements
+ Those divs each have a `_data_` property with the values of `55`, `34`, `2`, `22`, `59`, respectively  
+ Each step of the chain returned a reference to those elements. 

Enter and Append

Congrats on completing your first d3 visualization! With these basic skills, you can start building more complex visualizations by using some of the D3 pre-packaged methods. There are plenty of visualizations you can leverage now that you understand the mechanisms of how elements are added to the DOM and data is associated with them:

+ Selections are array-like data structures that include a reference to the elements with D3 methods and their hierarchy in the DOM. You can create a selection with `.selectAll()` or a single-item selection with `.select()`
+ The `.data()`, `.enter()` and `.append()` methods all work in unison to create elements and associate their corresponding data with the existing DOM
+ The `d` parameter inside functions used in a D3 context represents the datum associated with the element at hand
+ The `.attr()` and `.style()` methods allow you to customize the appearance of each element based on data.
+ The `.on()` method can bind an event listener on the elements in the selection.

Review

Before we wrap up, let's take a second to analyze the chaining syntax that is a D3 signature.

In the previous exercise, we referenced the following code:
```js
let dataset = [55,34,23,22,59];

d3.select("body")
 .selectAll("div")
   .data(dataset)
   .enter()
 .append("div")
   .text("Some text");
```
At first, this style may just seem like one big chain! But the key takeaway is that the methods that precede others in the chain return what is needed for the next step in the chain. By chaining, you can save some lines of code in your program. 

You'll see that the d3 community will indent some parts of the chains with four spaces, and other parts of the chain with two. The lines with two spaces indicate that the selection has changed:

``` js
var h1 = d3.selectAll("section")
    .style("background", "steelblue")
  .append("h1")
    .text("Hello!");
```

Chaining and Returning

Now that you've selected the elements and understand a bit about selections, let's insert and associate data per element. You accomplish this with one main method: `.data()`.

The `.data()` method takes an array of any type as its parameter and binds a datum to each element in the selection returned by `.selectAll()`:

```js
let dataset = [55,34,23,22,59];
d3.selectAll("p")
   .data(dataset);
```

+ If the _n_ is the length of the dataset passed into `.data()` and there is an equal or greater number of `<p>` elements, then every step that follows `.data()` in the chain is executed _n_ number of times.  In the example above, we have five items inside `dataset` and we assume there are five `<p>` elements in the HTML. Every instruction that follows the `.data()` method is therefore executed five times. 
+ In this example, we used an array of numbers, but we could have just as easily used an array of complex objects. The `.data()` function accepts an array of any type.

So is the data associated with the elements *or* the selection? With the elements! The data is bound to elements as a property, we'll explore this in later steps. Binding data to the elements allows the data to remain associated with the elements on the DOM even after you want to re-use the `.selectAll()` method to create a new selection. 

Data-Element Relationship

Now that you know how to access the datum associated with each element, it's possible to start customizing the appearance of each element with two powerful methods: `.attr()` and `.style()`.

+ The `.attr()` method takes two parameters, the HTML attribute you wish to change and the value you wish to assign it. 
+ Similarly, the `.style()` method takes two parameters, the CSS property you wish to change and the value you wish to assign it.

As we saw in the previous exercise, both of these methods can take their second argument as a function that returns the desired value for the property or attribute. 

Let's take a look to build on the example we've seen throughout the lesson:

```js
let dataset = [55,34,23,22,59];

let svg = d3.select("body")
            .selectAll("div")
            .data(dataset)
            .attr("id", function(d,i){ return "element-" + i; })
            .style("width", function(d){
                   return d + "px";
            });
```
Focusing on the last four lines of the example above, observe that both `.attr()` and `.style()` levereged an anonymous function with the `d` parameter to set the values based on the element data.
+ The `.attr()` method changed the HTML attribute `id` to be based on the element index in the dataset
+ The `.style()` method computed the width to be a function of the datum value

You can style your elements according to the value of their data and change the styling based on different conditions.



Styling your data 

You've learned the basic d3 design pattern of:

+ Creating a selection
+ Associating data with that selection
+ Appending elements to the DOM  
+ Modifying the elements based on the data

Let's take a second to put it all together, and build some interactivity on top. After all, another powerful aspect of d3 is that it has access to DOM events.

The `.on()` method takes a string parameter with the name of the event and a function to handle that event when it is triggered. The `.on()` method binds an event listener to the elements in the selection. Take a look at the following example:

```js
selection
    .on("mouseover", function(d,i) {
          d3.select(this).text(d);
    });
```
In the code above, each element in the selection would have an event listener that binds text to the elements when they event is triggered on each element individually. Notice that in the body of the function, we use the `this` keyword. In the function's context, `this` refers to the event's DOM element. The code modifies the text on mouse over, by selecting it with d3 and appending new text.

You can pass different types of events, some of the most popular events include `"click"`, `"mouseover"`, `"mouseout"`, `"mouseenter"` and more. 

Interactivity with events

The name [d3](https://d3js.org/) comes from the three D's in the term "Data-Driven Documents." This JavaScript data-visualization library rose in popularity because of a few game-changing features:

+ d3 revolutionized the way data visualizations are built natively for the web by associating data with elements on a website's Document Object Model.
+ d3 is a visually elegant library that offers a wide range of pre-packaged visualizations (from Tree-models to Sankey funnels) 
+ d3 leaves a lot of room for creative customization because the elements the data are bound to can be styled like any regular DOM element
+ d3 supports interactivity triggered by browser events

In this lesson, we won't be creating the fanciest d3 visualization you've ever seen. We'll enter the world of d3 by taking our time to understand how data is bound to elements and how to customize the appearance of our elements based on this data.

Why D3?

So once we've associated the data with the elements, how do we access the data and start manipulating our elements based on those values? You'll need a function with a `d` param to access each datum associated per element. Think of the `d` as representing the d in data or datum. Remember that the steps that follow `.data()` method are executed the total number of elements in the dataset.

In the previous exercise, you pasted an anonymous function with a `d` parameter. This is because the `d` parameter represents the value bound to each element in the d3 chain. Say we wanted to change the text inside a div to display the numbers in the array as text:

```js
let dataset = [55,34,23,22,59];

let svg = d3.select("body")
                 .selectAll("div")
                 .data(dataset)
                 .text(function(d) {
                         return d;
                  });
```
+ In this example, the `.text()` method took an anonymous function with a `d` parameter that returns the data value inside each of the `div` elements. d3 will append that value as the text inside each of the five `div` elements it created from the `dataset` array. Note: If the data were of type object, it would append the entire object and we could access each of their properties accordingly.

+ The `.data()` method assigns the correct value to the `d` parameter, or the first parameter, for the elements in question.

+ The functions you use don't always need to be anonymous, but you do need to include a `d` parameter, or a first argument, if you want to access the data. You can also optionally include an `i` parameter, or second parameter, if you want to access the index. Your JavaScript functions can be named and as complex as you wish, but for clarity's sake, we used an anonymous one that simply returns the `d` value in this example. If we wanted to introduce more complicated logic like conditionals, a loop, or append other text, we could achieve this just like we would in the body of any other function.