2f:T515,[**Plot.geo**](https://observablehq.com/@observablehq/plot-geo) draws geographic features and other polygonal geometry, and combined with other marks (_e.g._ dot, line, density, etc.) provides a user-friendly way to build maps with [Observable Plot](https://observablehq.com/@observablehq/plot-mapping). Here, we’ll use it to build a choropleth map — a map that uses color, shading or patterns to visualize aggregate values by geographic region (for example, median income by county, or carbon emissions per capita). We walk through: - Joining spatial data to attribute values - Creating a choropleth map using the geo mark - Customizing the map by layering additional marks and updating aesthetics - Adding interactivity with tooltips and Observable Inputs You can temporarily make edits to this notebook in [tinker mode](https://observablehq.com/@observablehq/tinker-mode). To store your changes, [fork](https://observablehq.com/@observablehq/fork-suggest-merge) this notebook to make updates in your own copy. If you are new to Observable, we recommend checking out [Learning Observable](https://observablehq.com/collection/@observablehq/intro-to-observable) and [Build your first map with Observable Plot](https://observablehq.com/@observablehq/build-your-first-map-with-observable-plot).30:[{"id":"12cf35e3c83562dab947814a4e43921f5539e7e7b0aed000e00273ffb2ee58ea110d5d0e42861c8ae7a76c83d849eae74718210aa8921c71d5a341934a19b6f9","href":"https://static.observableusercontent.com/files/12cf35e3c83562dab947814a4e43921f5539e7e7b0aed000e00273ffb2ee58ea110d5d0e42861c8ae7a76c83d849eae74718210aa8921c71d5a341934a19b6f9","name":"first-choropleth-preview@1.png","type":"image/png","lastModified":1702841766425.993,"size":1803085},{"id":"783cf2bf259e16d662d92c9f59ec97e564c50841c5984f2bb6f65a6d31f8c1b80846bffb65cb654dc2b587ac96f0007ab68c24bacce33655fd785e46020aff74","href":"https://static.observableusercontent.com/files/783cf2bf259e16d662d92c9f59ec97e564c50841c5984f2bb6f65a6d31f8c1b80846bffb65cb654dc2b587ac96f0007ab68c24bacce33655fd785e46020aff74","name":"us-counties-10m.json","type":"application/json","lastModified":1702841766425.993,"size":842177},{"id":"264c40907f911956deecc23a2206dca5da4a0ab8ce5716806a55dd0e3a80f7920151b4a6b9d909a4100d97b205efb845c2ef8b6f525d2ab274e919e31e0e7e32","href":"https://static.observableusercontent.com/files/264c40907f911956deecc23a2206dca5da4a0ab8ce5716806a55dd0e3a80f7920151b4a6b9d909a4100d97b205efb845c2ef8b6f525d2ab274e919e31e0e7e32","name":"us_broadband.csv","type":"text/csv","lastModified":1702841766425.993,"size":3221585}] 2d:{"title":"Build your first choropleth map with Observable Plot","cells":[{"id":0,"value":"# Build your first choropleth map with Observable Plot","pinned":false,"hidden":false,"mode":"md"},{"id":1089,"value":"This tutorial walks through the process of building a choropleth map of home broadband access in the U.S. by county. Here’s a preview of what we’ll make:","pinned":false,"hidden":false,"mode":"md"},{"id":1091,"value":"firstChoroplethPreview = FileAttachment(\"first-choropleth-preview@1.png\").image({width: 700})","pinned":false,"hidden":false,"mode":"ojs"},{"id":54,"value":"---\n## Introduction","pinned":false,"hidden":false,"mode":"md"},{"id":16,"value":"$2f","pinned":false,"hidden":false,"mode":"md"},{"id":404,"value":"---\n## Meet the data","pinned":false,"hidden":false,"mode":"md"},{"id":415,"value":"We’ll create and customize a choropleth map of broadband internet access in the United States by county. Data were originally collected by the U.S. Census Bureau America Community Survey and retrieved from the [ASU Center on Technology, Data and Society Broadband Data Portal](https://techdatasociety.asu.edu/broadband-data-portal/dataaccess/countydata).\n\nThe *us_broadband* data (from the attached us_broadband.csv file) is previewed below in an interactive [Data Table](https://observablehq.com/@observablehq/data-table-cell) cell, where **id** is the [county FIPS identifier](https://en.wikipedia.org/wiki/FIPS_county_code), and **broadband** is the estimated proportion of county residents with home broadband that year. ","pinned":false,"hidden":false,"mode":"md"},{"id":2222,"value":"us_broadband","pinned":false,"hidden":false,"mode":"ojs"},{"id":426,"value":"The data provides county-level estimates for home broadband access, but is missing geospatial information that would allow us to plot the values on a map. We’ll get spatial polygons for each county from the attached us-counties-10m.json file, which contains national, state, and county-level boundaries:","pinned":false,"hidden":false,"mode":"md"},{"id":325,"value":"us = FileAttachment(\"us-counties-10m.json\").json()","pinned":true,"hidden":false,"mode":"ojs"},{"id":866,"value":"County polygons are accessed from the object above using:","pinned":false,"hidden":false,"mode":"md"},{"id":580,"value":"counties = topojson.feature(us, us.objects.counties)","pinned":true,"hidden":false,"mode":"ojs"},{"id":834,"value":"We can quickly make a map of county boundaries in Plot with only a projection (see our documentation on [Plot Projections](https://observablehq.com/@observablehq/plot-projections)) and the _counties_ object as a geo mark: ","pinned":false,"hidden":false,"mode":"md"},{"id":836,"value":"Plot.plot({\n projection: \"albers-usa\", // Set the projection\n marks: [\n Plot.geo(counties, {stroke: \"black\"}) // Add county boundaries using the geo mark \n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1240,"value":"try_it(htl.html`Try it! Within the curly braces where the stroke (line color) option is specified above, add a fill attribute to update the fill color of all counties to a constant color (e.g. fill: \"purple\").`)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1135,"value":"To make it a choropleth map, we need to link the spatial polygon for each county to a value for broadband access, then update the county fill colors based on that value.","pinned":false,"hidden":false,"mode":"md"},{"id":434,"value":"---\n## Linking spatial polygons to attribute values","pinned":false,"hidden":false,"mode":"md"},{"id":454,"value":"To start, let’s make a choropleth map for the most recent year in the dataset (2018). First, we’ll make a 2018 subset from the larger dataset: ","pinned":false,"hidden":false,"mode":"md"},{"id":667,"value":"us_broadband_2018 = us_broadband.filter(d => d.year === 2018)","pinned":true,"hidden":false,"mode":"ojs"},{"id":505,"value":"Next, we’ll create a new [Map object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) to map broadband access values to county FIPS string (id) from the us_broadband_2018 subset. Map() is a common, useful way to create key-value pairs in JavaScript so that we can access values from multiple data sources using unique keys. Map objects have well-known counterparts in other languages and software, like [dictionaries in Python](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) and [vlookups](https://support.microsoft.com/en-us/office/vlookup-function-0bbc8083-26fe-4963-8ab8-93a18ad188a1) in Excel. ","pinned":false,"hidden":false,"mode":"md"},{"id":509,"value":"broadband_access_2018 = new Map(us_broadband_2018.map(({id, broadband}) => [id, broadband]))","pinned":true,"hidden":false,"mode":"ojs"},{"id":680,"value":"How does that help us? We can now get the broadband estimate for any county using just the FIPS code. For example, the code below returns the broadband access value for FIPS 06037 (Los Angeles County, California) in 2018: ","pinned":false,"hidden":false,"mode":"md"},{"id":514,"value":"broadband_access_2018.get(\"06037\") ","pinned":true,"hidden":false,"mode":"ojs"},{"id":694,"value":"The spatial data _counties_ also contains FIPS codes (labeled in the original data as “ID”) associated with the spatial polygon for each county. Because we have mapped broadband access to FIPS code, and because our _counties_ data contains FIPS codes, we can link the county spatial polygons to the broadband access value. \n\nFor example, the following will return the broadband access value for the first FIPS code in the counties data (“04015” = Mohave County, Arizona): ","pinned":false,"hidden":false,"mode":"md"},{"id":1477,"value":"mohaveCounty = counties.features[0]","pinned":true,"hidden":false,"mode":"ojs"},{"id":1482,"value":"mohaveCountyID = mohaveCounty.id","pinned":true,"hidden":false,"mode":"ojs"},{"id":728,"value":"mohave2018broadbandAccess = broadband_access_2018.get(mohaveCountyID)","pinned":true,"hidden":false,"mode":"ojs"},{"id":913,"value":"We can confirm the same outcome by manually adding the Mohave County FIPS code:","pinned":false,"hidden":false,"mode":"md"},{"id":911,"value":"broadband_access_2018.get(\"04015\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":1250,"value":"try_it(htl.html`Try it! Update the code above to return the estimated broadband access for Cook County, Illinois (FIPS code 17031) in 2018.`)","pinned":false,"hidden":false,"mode":"ojs"},{"id":809,"value":"---\n## Build a basic choropleth map","pinned":false,"hidden":false,"mode":"md"},{"id":812,"value":"Now that we can link broadband estimates to the _counties_ spatial data via the FIPS code, we can make our choropleth map. Let’s start with a bare-bones version by adding: \n\n1. The projection (albers-usa, mercator, etc. — learn more about built-in [Plot Projections](https://observablehq.com/@observablehq/plot-projections))\n2. Spatial polygons for U.S. counties (our counties object, which we used before)\n3. A fill color based on the 2018 broadband access for each county (using the map/lookup we just made!)","pinned":false,"hidden":false,"mode":"md"},{"id":821,"value":"Plot.plot({\n projection: \"albers-usa\",\n marks: [\n Plot.geo(\n counties,\n { fill: (d) => broadband_access_2018.get(d.id) } // Fill color depends on broadband value\n )\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1003,"value":"We can read the fill attribute code above as follows: “Fill each polygon from the _counties_ data based on the value of the broadband estimate associated with each FIPS code (id) in _counties_.” Note that we don’t specify a color scheme, so the default “Turbo” palette is used (see other options in [Color Schemes](https://observablehq.com/@d3/color-schemes)).","pinned":false,"hidden":false,"mode":"md"},{"id":831,"value":"We’ve successfully made a choropleth map! But we’re missing some important information needed to interpret the colors (_i.e._, a legend), and we might want to update the look and feel of the map. Let’s customize it a bit.","pinned":false,"hidden":false,"mode":"md"},{"id":847,"value":"---\n## Customization","pinned":false,"hidden":false,"mode":"md"},{"id":1218,"value":"We need to update our map to make it more readable and easy to interpret. For example, without a legend it is impossible (from the map alone) to understand the patterns and value scale. And, by default the colors are mapped to the extent of the data. Here, that means that the color scale doesn't extend from 0 to 100% broadband access, which we would expect for a choropleth map showing _proportions_. The result is exaggerated differences in broadband access proportions between regions. We can better handle this by hard coding a domain for our color scale. \n\n- Updating the fill color scheme and scale\n- Adding and customizing a legend","pinned":false,"hidden":false,"mode":"md"},{"id":578,"value":"Plot.plot({\n projection: \"albers-usa\",\n marks: [\n Plot.geo(counties, {fill: d => broadband_access_2018.get(d.id)})\n ],\n color: {\n scheme: \"spectral\", // Change color scheme\n unknown: \"#ddd\", // Polygons with unknown broadband values are gray\n type: \"linear\", // Linear scale for color progression\n legend: true, // Add the legend\n label: \"% of county population with home broadband\", // Update legend label\n percent: true, // Convert value to a percent (from a proportion)\n domain: [0, 100] // Update the value domain to span 0 to 100% access\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1261,"value":"try_it(htl.html`Try it! Update the code above by choosing a different continuous color scheme (see options in Plot: Scales) and adjusting the domain to see how the map changes.`)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1285,"value":"It might also be helpful to see the state outlines. Let’s add them as an additional layer to our map. We’ll access the state boundaries from the _us_ data:","pinned":false,"hidden":false,"mode":"md"},{"id":1288,"value":"states = topojson.feature(us, us.objects.states)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1291,"value":"Then add a new geo mark with the state boundaries: ","pinned":false,"hidden":false,"mode":"md"},{"id":1296,"value":"Plot.plot({\n projection: \"albers-usa\",\n marks: [\n Plot.geo(counties, {fill: d => broadband_access_2018.get(d.id)}),\n Plot.geo(states, {stroke: \"#fff\", strokeWidth: 0.5}) // New layer with state boundaries\n ],\n color: {\n scheme: \"Spectral\", \n unknown: \"#ddd\",\n type: \"linear\", \n legend: true, \n label: \"% of county population with home broadband\", \n percent: true, \n domain: [0, 100] \n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1303,"value":"try_it(htl.html`Try it! Update the stroke (line color) and strokeWidth attributes of the state borders in the map above.`)","pinned":false,"hidden":false,"mode":"ojs"},{"id":862,"value":"---\n## Adding interactivity","pinned":false,"hidden":false,"mode":"md"},{"id":1063,"value":"### Tooltips\n","pinned":false,"hidden":false,"mode":"md"},{"id":859,"value":"\nThe fill color in our static choropleth map shows general patterns in broadband access across the country. A user might also want to know the actual broadband estimate value is for a county of interest. Let’s add tooltips that reveal the county name and broadband access estimate as a user hovers over the map.","pinned":false,"hidden":false,"mode":"md"},{"id":1150,"value":"First, we import the addTooltips function from [Mike Freeman](https://observablehq.com/@mkfreeman)'s [Plot Tooltips notebook](https://observablehq.com/@mkfreeman/plot-tooltip). Learn more about [Observable imports](https://observablehq.com/@observablehq/import) to quickly access functions and content from other notebooks in Observable.","pinned":false,"hidden":false,"mode":"md"},{"id":1140,"value":"import {addTooltips} from \"@mkfreeman/plot-tooltip\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":1154,"value":"Then, we’ll wrap our Plot code in the addTooltips function, and add a **title** attribute within the geo mark to customize what appears when hovering: ","pinned":false,"hidden":false,"mode":"md"},{"id":1447,"value":"percent = d3.format(\".2%\") // Function to convert values to percent format with two digits","pinned":true,"hidden":false,"mode":"ojs"},{"id":1450,"value":"percent(0.12343423432) // Example usage of the percent function created above, which we use to format our tooltip text in the choropleth below","pinned":true,"hidden":false,"mode":"ojs"},{"id":1158,"value":"addTooltips( // Add tooltips\n Plot.plot({\n projection: \"albers-usa\",\n marks: [\n Plot.geo(counties, {\n fill: (d) => broadband_access_2018.get(d.id),\n title: (d) =>\n `${d.properties.name} County \\n ${percent(\n broadband_access_2018.get(d.id) // Custom tooltip text\n )}`\n }), \n Plot.geo(states, { stroke: \"#fff\", strokeWidth: 0.5 })\n ],\n color: {\n scheme: \"Spectral\",\n unknown: \"#ddd\",\n type: \"linear\",\n label: \"% of county population with home broadband\",\n legend: true,\n percent: true,\n domain: [0, 100]\n }\n })\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1070,"value":"### Slider Input","pinned":false,"hidden":false,"mode":"md"},{"id":1072,"value":"[Observable inputs](https://observablehq.com/@observablehq/inputs) provide a lightweight method to add interactive elements like radio buttons, sliders, and check boxes to a notebook. Here, we make our map interactive in several steps: \n\n1. Create a slider input for year in the broadband dataset\n2. Subset the broadband data to keep observations for the selected year\n3. Create a choropleth map from the that subset","pinned":false,"hidden":false,"mode":"md"},{"id":1382,"value":"The [range slider](https://observablehq.com/@observablehq/input-range) below is updated from an Input snippet in the [Add Cell menu](https://observablehq.com/@observablehq/adding-cells):","pinned":false,"hidden":false,"mode":"md"},{"id":935,"value":"viewof yearSelect = Inputs.range(d3.extent(us_broadband, d => d.year), \n {label: \"Year:\", step: 1, value: d3.max(us_broadband, d => d.year)})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1395,"value":"Using the value of the slider (_yearSelect_) we create a subset of *us_broadband*, then map broadband values for that year to the FIPS code:","pinned":false,"hidden":false,"mode":"md"},{"id":940,"value":"broadband_select_year = us_broadband.filter(d => d.year === yearSelect)","pinned":true,"hidden":false,"mode":"ojs"},{"id":945,"value":"broadband_access_select_year = new Map(broadband_select_year.map(({id, broadband}) => [id, broadband]))","pinned":true,"hidden":false,"mode":"ojs"},{"id":1409,"value":"For our final step, we update the Plot code (shown below) to use the mapped broadband values for the selected year in the range slider. When the slider value is updated, data for the selected year is shown on the map. ","pinned":false,"hidden":false,"mode":"md"},{"id":947,"value":"vizofyear = Plot.plot({\n projection: \"albers-usa\",\n marks: [\n Plot.geo(counties, {\n fill: (d) => broadband_access_select_year.get(d.id) // Fill color based on values from subset for the selected year in slider\n }),\n Plot.geo(counties, { strokeWidth: 0.05 }),\n Plot.geo(states, { stroke: \"#fff\", strokeWidth: .5 })\n ],\n color: {\n scheme: \"Spectral\",\n unknown: \"#ddd\",\n type: \"linear\",\n label: \"% of county population with home broadband\",\n legend: true,\n percent: true,\n domain: [0, 100]\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1356,"value":"---\n## Wrap-up\n\nIn this tutorial, we made both static and interactive choropleth maps of broadband access by U.S. county. Some major takeaways: \n\n- By mapping a key (in this case, county FIPS code) to an attribute value using a Map object, we can join values to spatial polygons to update their fill color\n- We can customize maps in Observable Plot using the same options and arguments used in other Plot chart types\n- We can quickly add interactivity with tooltips to reveal information on hover, or by linking map data or elements to Observable Inputs","pinned":false,"hidden":false,"mode":"md"},{"id":890,"value":"---\n## Learn more\n\nExplore our additional resources on mapmaking with Observable Plot! \n\n- [Mapping with Plot](https://observablehq.com/@observablehq/plot-mapping)\n- [Plot.geo documentation](https://observablehq.com/@observablehq/plot-geo)\n- [Plot: Projections](https://observablehq.com/@observablehq/plot-projections)\n- [Build your first map with Observable Plot](https://observablehq.com/@observablehq/build-your-first-map-with-observable-plot)","pinned":false,"hidden":false,"mode":"md"},{"id":1236,"value":"---\n## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":1458,"value":"us_broadband = FileAttachment(\"us_broadband.csv\").csv().then(data => data.filter(d => d.broadband !== \"\").map(d => ({\n state: d.statenam,\n county: d.county,\n year: +d.year,\n id: d.id.slice(-5),\n broadband: +d.broadband\n})))","pinned":true,"hidden":false,"mode":"ojs"},{"id":1238,"value":"import {try_it} from \"@observablehq/notes\"","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W30","stdlib":"1","titling":"auto"}