Preliminaries



First you need to install a few things:

Node TopoJSON From terminal run: npm install -g topojson

Makefile

The first step is to create your Makefile. Mike Bostock has an excellent explanation of why and how to use Makefiles. I won’t go into much detail, but you can use my makefile. Save it as a text file called Makefile and then create a directory called build. Then download the csv data for the map here (save it in the same directory as your makefile). Now use your makefile:

Download the map data This can be run with the make build/gz_2010_us_040_00_20m.zip command in the terminal Extracttheshapefile and convertittoTopoJSON withyourcsv data merged in This is done using the make build/states.json command

You should now have a file called states.json in your build directory.

A few things I want to point out in the Makefile:

id-property='STATE,id'

This command is how we tell the program which variables to merge by. We are telling it to merge on our csv data when our id variable matches the STATE variable in the shapefile . These variables are the numeric IDs for the states.

--external-properties=state_data.csv

This tells it where to find our data.

--properties='rate=+d.properties["value"]'

This adds a rate property to our states.json file using the value variable from our csv data. Now every state will have a rate property that we can access.

You can see how you can easily change the above values to incorporate your own state data into the states.json file. All you have to do is update the Makefile to reflect your data and properties and then re-run the “make build/states.json”

HTML Code

Create an index.html file in your directory and copy my code from here. From examining the code you can get a decent idea of how it works, but I want to point out a few things:

var num_format = d3.format( " ,.0f " );

This is how you can create a number format in D3. Use these so your numbers look nice.

var color = d3.scale.quantize(). domain ([ 25 , 63 ]).range(colorbrewer.Greens[ 7 ]);

D3 scales are awesome. The quantize scale is taking in our domain – basically the range for our median rank data – and mapping it to seven buckets using the color brewer. That way we now have seven colors to use for our map.

function (d) {return d.properties.rate == null ? " #000000 " : color(d.properties.rate);

Here you are using a function and passing it d. You can think of d as basically being our state. So d.properties.rate is the rate for our state. And this function will be applied to all states. My function is of the form a == b ? c : d. This is saying if a == b then do c else do d. So what I am accomplishing with this function is coloring the states black that have no rate data and coloring the other states according to our color scale defined above. Pretty cool.

function ( x ) { return d.properties.cost == null ? 'No Ranked Schools' : 'Median In-State Cost: $' + num_format(d.properties.cost) + " <br/>" + " Median Rank: " + num_format(d.properties.rank) + " <br/> " + " Number of Schools: " + d.properties.number;}

Here is another example of using a function to create the text you see when the mouse scrolls over a state. We are using our number format and <br/> to create line breaks in the text.

Legend

At the end of the html file we create the legend. Basically we are passing the range of our color scale as data:

data (color.range())

And then filling in a rectangle with those colors:

style ( " fill " , function ( d , i ) { return d; })

After that we define some text attributes that show the words “Highest” and “Lowest” next to our scale. I got the x and y values for the text through trial and error. I am sure, though, there is a better way.

Get it running

The easiest way for me to locally host my D3 map is to use Python. If you don’t have Python, check out my introduction to Python – it has installation instructions. Within the terminal, in the same directory as your index.html file, type (I think this may only work with Python 2):

python -m SimpleHTTPServer 8888 &

Then in your web browser navigate to:

http://localhost:8888/

You should hopefully see your map! Also, if you want to get this up so you can share it with people, I would recommend using GitHub Pages. Basically you just create a new repository and push up your index and map data files. Very easy.

Final Notes

I hope this guide was useful. My goal was to provide a very fast way to create your own D3 map and to understand some of the more important parts of the process. This guide leaves out a lot of details, though. If you want a better understanding of D3, check out some of the books and sites that I have found useful.

You will also notice that I didn’t talk at all about the data. This is because I am just using these data to create a map; not for analytical purposes. My hope is that once you get the map working you will modify it to use some new data that you find interesting. If you do, please share your map with me on twitter @tyler_folkman.

If you want to know a tiny bit more about the data see my original post. This post will also show you the final version of the map.

Also, if you have any problems following this guide, please let me know either through a comment or by contacting me. I would love to help / fix any bugs in my explanation. Thanks!

Special thanks to these great sites that helped me figure this out:

http://bost.ocks.org/mike/bubble-map/

https://suffenus.wordpress.com/2014/01/07/making-interactive-maps-with-d3-for-total-beginners/