29:null 2a:["$","title",null,{"children":"Cartographic Visualization (JSON version) | UW Interactive Data Lab | Observable"}] 2f:T8bd,md` _“The making of maps is one of humanity's longest established intellectual endeavors and also one of its most complex, with scientific theory, graphical representation, geographical facts, and practical considerations blended together in an unending variety of ways.”_ — [H. J. Steward](https://books.google.com/books?id=cVy1Ms43fFYC) Cartography – the study and practice of map-making – has a rich history spanning centuries of discovery and design. Cartographic visualization leverages mapping techniques to convey data containing spatial information, such as locations, routes, or trajectories on the surface of the Earth.

Approximating the Earth as a sphere, we can denote positions using a spherical coordinate system of _latitude_ (angle in degrees north or south of the _equator_) and _longitude_ (angle in degrees specifying east-west position). In this system, a _parallel_ is a circle of constant latitude and a _meridian_ is a circle of constant longitude. The [_prime meridian_](https://en.wikipedia.org/wiki/Prime_meridian) lies at 0° longitude and by convention is defined to pass through the Royal Observatory in Greenwich, England. To "flatten" a three-dimensional sphere on to a two-dimensional plane, we must apply a [projection](https://en.wikipedia.org/wiki/Map_projection) that maps (\`longitude\`, \`latitude\`) pairs to (\`x\`, \`y\`) coordinates. Similar to [scales](https://observablehq.com/@uwdata/scales-axes-and-legends), projections map from a data domain (spatial position) to a visual range (pixel position). However, the scale mappings we've seen thus far accept a one-dimensional domain, whereas map projections are inherently two-dimensional. In this notebook, we will introduce the basics of creating maps and visualizing spatial data with Vega-Lite, including: - Data formats for representing geographic features, - Geo-visualization techniques such as point, symbol, and choropleth maps, and - A review of common cartographic projections. `30:T8e0,md` ~~~ json { "type": "Feature", "id": 8, "properties": {"name": "Colorado"}, "geometry": { "type": "Polygon", "coordinates": [ [[-106.32056285448942,40.998675790862656],[-106.19134826714341,40.99813863734313],[-105.27607827344248,40.99813863734313],[-104.9422739227986,40.99813863734313],[-104.05212898774828,41.00136155846029],[-103.57475287338661,41.00189871197981],[-103.38093099236758,41.00189871197981],[-102.65589358559272,41.00189871197981],[-102.62000064466328,41.00189871197981],[-102.052892177978,41.00189871197981],[-102.052892177978,40.74889940428302],[-102.052892177978,40.69733266640851],[-102.052892177978,40.44003613055551],[-102.052892177978,40.3492571857556],[-102.052892177978,40.00333031918079],[-102.04930288388505,39.57414465707943],[-102.04930288388505,39.56823596836465],[-102.0457135897921,39.1331416175485],[-102.0457135897921,39.0466599009048],[-102.0457135897921,38.69751011321283],[-102.0457135897921,38.61478847120581],[-102.0457135897921,38.268861604631],[-102.0457135897921,38.262415762396685],[-102.04212429569915,37.738153927339205],[-102.04212429569915,37.64415206142214],[-102.04212429569915,37.38900413964724],[-102.04212429569915,36.99365914927603],[-103.00046581851544,37.00010499151034],[-103.08660887674611,37.00010499151034],[-104.00905745863294,36.99580776335414],[-105.15404227428235,36.995270609834606],[-105.2222388620483,36.995270609834606],[-105.7175614468747,36.99580776335414],[-106.00829426840322,36.995270609834606],[-106.47490250048605,36.99365914927603],[-107.4224761410235,37.00010499151034],[-107.48349414060355,37.00010499151034],[-108.38081766383978,36.99903068447129],[-109.04483707103458,36.99903068447129],[-109.04483707103458,37.484617466122884],[-109.04124777694163,37.88049961001363],[-109.04124777694163,38.15283644441336],[-109.05919424740635,38.49983761802722],[-109.05201565922046,39.36680339854235],[-109.05201565922046,39.49786885730673],[-109.05201565922046,39.66062637372313],[-109.05201565922046,40.22248895514744],[-109.05201565922046,40.653823231326896],[-109.05201565922046,41.000287251421234],[-107.91779872584989,41.00189871197981],[-107.3183866123281,41.00297301901887],[-106.85895696843116,41.00189871197981],[-106.32056285448942,40.998675790862656]] ] } } ~~~ `31:T5b8,md` _That's a lot of airports! Obviously, not all of them are major hubs._ Similar to our zip codes dataset, our airport data includes points that lie outside the continental United States. So we again see points in the upper-left corner. We might want to filter these points, but to do so we first need to know more about them. _Update the map projection above to \`albers\` – side-stepping the idiosyncratic behavior of \`albersUsa\` – so that the actual locations of these additional points is revealed!_ Now, instead of showing all airports in an undifferentiated fashion, let's identify major hubs by considering the total number of routes that originate at each airport. We'll use the \`routes\` dataset as our primary data source: it contains a list of flight routes that we can aggregate to count the number of routes for each \`origin\` airport. However, the \`routes\` dataset does not include the _locations_ of the airports! To augment the \`routes\` data with locations, we need a new data transformation: \`lookup\`. The \`lookup\` transform takes a field value in a primary dataset and uses it as a _key_ to look up related information in another table. In this case, we want to match the \`origin\` airport code in our \`routes\` dataset against the \`iata\` field of the \`airports\` dataset, then extract the corresponding \`latitude\` and \`longitude\` fields. _Which U.S. airports have the highest number of outgoing routes?_ `32:T4d3,render({ layer: [ { mark: { type: 'geoshape', fill: '#ddd', stroke: '#fff', strokeWidth: 1 }, data: { values: usa, format: { type: 'topojson', feature: 'states' } } }, { mark: { type: 'circle' }, data: { url: flights }, transform: [ { aggregate: [{ op: 'count', as: 'routes' }], groupby: ['origin'] }, { lookup: 'origin', from: { data: { url: airports }, key: 'iata', fields: ['state', 'latitude', 'longitude'] } }, { filter: 'datum.state !== "PR" && datum.state !== "VI"' } ], encoding: { latitude: { field: 'latitude', type: 'Q' }, longitude: { field: 'longitude', type: 'Q' }, tooltip: [ { field: 'origin', type: 'N' }, { field: 'routes', type: 'Q' } ], size: { field: 'routes', type: 'Q', scale: { range: [0, 1000] }, legend: null }, order: { field: 'routes', type: 'Q', sort: 'descending' } // place smaller circles on top } }, ], projection: { type: 'albersUsa' }, width: 900, height: 500, config: { view: { stroke: null } } })33:T85d,md` Now that we have some experience creating maps, let's take a closer look at cartographic projections. As explained by [Wikipedia](https://en.wikipedia.org/wiki/Map_projection), > _All map projections necessarily distort the surface in some fashion. Depending on the purpose of the map, some distortions are acceptable and others are not; therefore, different map projections exist in order to preserve some properties of the sphere-like body at the expense of other properties._ Some of the properties we might wish to consider include: - _Area_: Does the projection distort region sizes? - _Bearing_: Does a straight line correspond to a constant direction of travel? - _Distance_: Do lines of equal length correspond to equal distances on the globe? - _Shape_: Does the projection preserve spatial relations (angles) between points? Selecting an appropriate projection thus depends on the use case for the map. For example, if we are assessing land use and the extent of land matters, we might choose an area-preserving projection. If we want to visualize shockwaves emanating from an earthquake, we might focus the map on the quake's epicenter and preserve distances outward from that point. Or, if we wish to aid navigation, the preservation of bearing and shape may be more important. We can also characterize projections in terms of the _projection surface_. Cylindrical projections, for example, project surface points of the sphere onto a surrounding cylinder; the "unrolled" cylinder then provides our map. As we further describe below, we might alternatively project onto the surface of a cone (conic projections) or directly onto a flat plane (azimuthal projections). *Let's first build up our intuition by interacting with a variety of projections! Use the controls below to select a projection and explore projection parameters, such as the \`scale\` (zooming) and x/y translation (panning). The rotation ([yaw, pitch, roll](https://en.wikipedia.org/wiki/Aircraft_principal_axes)) controls determine the orientation of the globe relative to the surface being projected upon. (Reload the page to reset the controls.)* `34:T621,md` [**Cylindrical projections**](https://en.wikipedia.org/wiki/Map_projection#Cylindrical) map the sphere onto a surrounding cylinder, then unroll the cylinder. If the major axis of the cylinder is oriented north-south, meridians are mapped to straight lines. [Pseudo-cylindrical](https://en.wikipedia.org/wiki/Map_projection#Pseudocylindrical) projections represent a central meridian as a straight line, with other meridians "bending" away from the center. - [Equirectangular](https://en.wikipedia.org/wiki/Equirectangular_projection) (\`equirectangular\`): Scale \`lat\`, \`lon\` coordinate values directly. - [Mercator](https://en.wikipedia.org/wiki/Mercator_projection) (\`mercator\`): Project onto a cylinder, using \`lon\` directly, but subjecting \`lat\` to a non-linear transformation. Straight lines preserve constant compass bearings ([rhumb lines](https://en.wikipedia.org/wiki/Rhumb_line)), making this projection well-suited to navigation. However, areas in the far north or south can be greatly distorted. - [Transverse Mercator](https://en.wikipedia.org/wiki/Transverse_Mercator_projection) (\`transverseMercator\`): A mercator projection, but with the bounding cylinder rotated to a transverse axis. Whereas the standard Mercator projection has highest accuracy along the equator, the Transverse Mercator projection is most accurate along the central meridian. - [Natural Earth](https://en.wikipedia.org/wiki/Natural_Earth_projection) (\`naturalEarth1\`): A pseudo-cylindrical projection designed for showing the whole Earth in one view.

`35:T541,md` [**Conic projections**](https://en.wikipedia.org/wiki/Map_projection#Conic) map the sphere onto a cone, and then unroll the cone on to the plane. Conic projections are configured by two _standard parallels_, which determine where the cone intersects the globe. - [Conic Equal Area](https://en.wikipedia.org/wiki/Albers_projection) (\`conicEqualArea\`): Area-preserving conic projection. Shape and distance are not preserved, but roughly accurate within standard parallels. - [Conic Equidistant](https://en.wikipedia.org/wiki/Equidistant_conic_projection) (\`conicEquidistant\`): Conic projection that preserves distance along the meridians and standard parallels. - [Conic Conformal](https://en.wikipedia.org/wiki/Lambert_conformal_conic_projection) (\`conicConformal\`): Conic projection that preserves shape (local angles), but not area or distance. - [Albers](https://en.wikipedia.org/wiki/Albers_projection) (\`albers\`): A variant of the conic equal area projection with standard parallels optimized for creating maps of the United States. - [Albers USA](https://en.wikipedia.org/wiki/Albers_projection) (\`albersUsa\`): A hybrid projection for the 50 states of the United States of America. This projection stitches together three Albers projections with different parameters for the continental U.S., Alaska, and Hawaii.

`36:T4e6,md` [**Azimuthal projections**](https://en.wikipedia.org/wiki/Map_projection#Azimuthal_%28projections_onto_a_plane%29) map the sphere directly onto a plane. - [Azimuthal Equal Area](https://en.wikipedia.org/wiki/Lambert_azimuthal_equal-area_projection) (\`azimuthalEqualArea\`): Accurately projects area in all parts of the globe, but does not preserve shape (local angles). - [Azimuthal Equidistant](https://en.wikipedia.org/wiki/Azimuthal_equidistant_projection) (\`azimuthalEquidistant\`): Preserves proportional distance from the projection center to all other points on the globe. - [Orthographic](https://en.wikipedia.org/wiki/Orthographic_projection_in_cartography) (\`orthographic\`): Projects a visible hemisphere onto a distant plane. Approximately matches a view of the Earth from outer space. - [Stereographic](https://en.wikipedia.org/wiki/Stereographic_projection) (\`stereographic\`): Preserves shape, but not area or distance. - [Gnomonic](https://en.wikipedia.org/wiki/Gnomonic_projection) (\`gnomonic\`): Projects the surface of the sphere directly onto a tangent plane. [Great circles](https://en.wikipedia.org/wiki/Great_circle) around the Earth are projected to straight lines, showing the shortest path between points.

`37:T560,md` The examples above all draw from the vega-datasets collection, including geometric (TopoJSON) and tabular (airports, unemployment rates) data. A common challenge to getting started with geographic visualization is collecting the necessary data for your task. A number of data providers abound, including services such as the [United States Geological Survey](https://www.usgs.gov/products/data/all-data) and [U.S. Census Bureau](https://www.census.gov/data/datasets.html). In many cases you may have existing data with a geographic component, but require additional measures or geometry. To help you get started, here is one workflow: 1. Visit [Natural Earth Data](http://www.naturalearthdata.com/downloads/) and browse to select data for regions and resolutions of interest. Download the corresponding zip file(s). 2. Go to [MapShaper](https://mapshaper.org/) and drop your downloaded zip file onto the page. Revise the data as desired, and then "Export" generated TopoJSON or GeoJSON files. 3. Load the exported data from MapShaper for use with Vega-Lite! Of course, many other tools – both open-source and proprietary – exist for working with geographic data. For more about geo-data wrangling and map creation, see Mike Bostock's tutorial series on [Command-Line Cartography](https://medium.com/@mbostock/command-line-cartography-part-1-897aa8f8ca2c). `38:[] 2d:{"id":"d065b84eda504b11","slug":"cartographic-visualization-json","title":"Cartographic Visualization (JSON version)","thumbnail":"e28ef4f78c39245ecdad66389091de6bb5bcf2add517e90c4f91ab943ecb9f1a","access_level":"public","create_time":"$D2024-09-19T22:06:42.468Z","update_time":"$D2024-10-09T01:27:41.712Z","view_time":null,"first_public_time":"$D2024-09-19T22:57:11.845Z","has_unpublished_edits":null,"fork":{"id":"03fb1bc5676f4c26","slug":"cartographic-visualization","title":"Cartographic Visualization","owner":{"id":"33e135341fd39b6b","login":"uwdata","name":"UW Interactive Data Lab"}},"stars":2,"starred":false,"owner":{"type":"team","id":"33e135341fd39b6b","login":"uwdata","name":"UW Interactive Data Lab","avatar_url":"https://avatars-next.observableusercontent.com/3edc7fd13a27b85983daf26162ae9b524d571436d583c3093ebf9cddee4c1ff9","tier":"starter_2024"},"version":1669,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"ecf15dc33ed8cd37","login":"jheer","name":"Jeffrey Heer","avatar_url":"https://avatars-next.observableusercontent.com/230cea705fbda819b9f6b8bc87e05ebecf06d314098901fbd9946af2cdc51be4","tier":null}],"members":[{"type":"individual","id":"ecf15dc33ed8cd37","login":"jheer","name":"Jeffrey Heer","avatar_url":"https://avatars-next.observableusercontent.com/230cea705fbda819b9f6b8bc87e05ebecf06d314098901fbd9946af2cdc51be4","tier":null,"role":"editor"},{"type":"team","id":"33e135341fd39b6b","login":"uwdata","name":"UW Interactive Data Lab","avatar_url":"https://avatars-next.observableusercontent.com/3edc7fd13a27b85983daf26162ae9b524d571436d583c3093ebf9cddee4c1ff9","tier":"starter_2024","role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":31,"collection":null,"type":"notebook","body":{"title":"Cartographic Visualization (JSON version)","cells":[{"id":0,"value":"md`# Cartographic Visualization (JSON version)`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":853,"value":"$2f","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":11,"value":"import { render } from '@vega/vega-lite-api-v5'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":17,"value":"datasets = require('vega-datasets@1')","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":14,"value":"md`\n

\n## Geographic Data: GeoJSON and TopoJSON\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":651,"value":"md`\nUp to this point, we have worked with JSON and CSV formatted datasets that correspond to data tables made up of rows (records) and columns (fields). In order to represent geographic regions (countries, states, _etc._) and trajectories (flight paths, subway lines, _etc._), we need to expand our repertoire with additional formats designed to support rich geometries.\n\n[GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) models geographic features within a specialized JSON format. A GeoJSON \\`feature\\` can include geometric data – such as \\`longitude\\`, \\`latitude\\` coordinates that make up a country boundary – as well as additional data attributes.\n\nHere is a GeoJSON \\`feature\\` object for the boundary of the U.S. state of Colorado:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":672,"value":"$30","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":678,"value":"md`\nThe \\`feature\\` includes a \\`properties\\` object, which can include any number of data fields, plus a \\`geometry\\` object, which in this case contains a single polygon that consists of \\`[longitude, latitude]\\` coordinates for the state boundary. The coordinates continue off to the right for a while should you care to scroll...\n\nTo learn more about the nitty-gritty details of GeoJSON, see the [official GeoJSON specification](http://geojson.org/) or read [Tom MacWright's helpful primer](https://macwright.org/2015/03/23/geojson-second-bite).\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":687,"value":"md`\nOne drawback of GeoJSON as a storage format is that it can be redundant, resulting in larger file sizes. Consider: The U.S. state of Colorado shares boundaries with six other states (seven if you include the corner touching Arizona). Instead of using separate, overlapping coordinate lists for each of those states, a more compact approach is to encode shared borders only once, representing the _topology_ of geographic regions. Fortunately, this is precisely what the [TopoJSON](https://github.com/topojson/topojson/blob/master/README.md) format does!\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":80,"value":"md`Let's load a TopoJSON file of world countries (at 110 meter resolution):`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":19,"value":"world = datasets['world-110m.json']()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":703,"value":"md`\n_Expand the \\`world\\` TopoJSON object above to inspect its contents._\n\nIn the data above, the \\`objects\\` property indicates the named elements we can extract from the data: geometries for all \\`countries\\`, or a single polygon representing all \\`land\\` on Earth. Either of these can be unpacked to GeoJSON data we can then visualize.\n\nAs TopoJSON is a specialized format, we need to instruct Vega-Lite to parse the TopoJSON format, indicating which named object we wish to extract from the topology. The following Vega-Lite JSON indicates that we want to extract GeoJSON features from the \\`world\\` dataset for the \\`countries\\` object:\n\n~~~ json\n{\n \"values\": world,\n \"format\": {\"type\": \"topojson\", \"feature\": \"countries\"}\n}\n~~~\n\nNow that we can load geographic data, we're ready to start making maps!\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":4,"value":"md`\n

\n## Geoshape Marks\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":735,"value":"md`\nTo visualize geographic data, Vega-Lite provides the \\`geoshape\\` mark type. To create a basic map, we can create a \\`geoshape\\` mark and pass it our TopoJSON data, which is then unpacked into GeoJSON features, one for each country of the world:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":24,"value":"render({\n mark: 'geoshape',\n data: {\n values: world,\n format: { type: 'topojson', feature: 'countries' }\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":740,"value":"md`\nIn the example above, Vega-Lite applies a default blue color and uses a default map projection. We can customize the colors and boundary stroke widths using standard mark properties. Using the \\`projection\\` property we can also add our own map projection:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":56,"value":"render({\n mark: { type: 'geoshape', fill: '#2a1d0c', stroke: '#706545', strokeWidth: 0.5 },\n data: {\n values: world,\n format: { type: 'topojson', feature: 'countries' }\n },\n projection: { type: 'mercator' }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":747,"value":"md`\nBy default Vega-Lite automatically adjusts the projection so that all the data fits within the width and height of the chart. We can also specify projection parameters, such as \\`scale\\` (zoom level) and \\`translate\\` (panning), to customize the projection settings. Here we adjust the \\`scale\\` and \\`translate\\` parameters to focus on Europe:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":65,"value":"render({\n mark: { type: 'geoshape', fill: '#2a1d0c', stroke: '#706545' },\n data: {\n values: world,\n format: { type: 'topojson', feature: 'countries' }\n },\n projection: { type: 'mercator', scale: 400, translate: [100, 550] }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":750,"value":"md`_Note how the 110m resolution of the data becomes apparent at this scale. To see more detailed coast lines and boundaries, we need an input file with more fine-grained geometries. Adjust the \\`scale\\` and \\`translate\\` parameters to focus the map on other regions!_`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":818,"value":"md`\nSo far our map shows countries only. Using the \\`layer\\` operator, we can combine multiple map elements. Vega-Lite includes _data generators_ we can use to create data for additional map layers:\n\n- The \\`sphere\\` generator provides a GeoJSON representation of the full sphere of the Earth. We can create an additional \\`geoshape\\` mark that fills in the shape of the Earth as a background layer.\n- The \\`graticule\\` generator creates a GeoJSON feature representing a _graticule_: a grid formed by lines of latitude and longitude. The default graticule has meridians and parallels every 10° between ±80° latitude. For the polar regions, there are meridians every 90°. These settings can be customized using the \\`stepMinor\\` and \\`stepMajor\\` properties.\n\nLet's layer sphere, graticule, and country marks into a reusable map specification:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":807,"value":"map = ({\n layer: [\n {\n mark: { type: 'geoshape', fill: '#e6f3ff' },\n data: { sphere: true }\n },\n {\n mark: { type: 'geoshape', stroke: '#ffffff', strokeWidth: 1 },\n data: { graticule: true }\n },\n {\n mark: { type: 'geoshape', fill: '#2a1d0c', stroke: '#706545', strokeWidth: 0.5 },\n data: {\n values: world,\n format: { type: 'topojson', feature: 'countries' }\n }\n }\n ],\n width: 600,\n height: 400,\n config: { view: { stroke: null } }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":838,"value":"md`\nWe can extend the map with a desired projection and call \\`render()\\` to draw the result. Here we apply a [Natural Earth projection](https://en.wikipedia.org/wiki/Natural_Earth_projection). The _sphere_ layer provides the light blue background; the _graticule_ layer provides the white geographic reference lines.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":815,"value":"render({\n ...map,\n projection: {\n type: 'naturalEarth1',\n scale: 110,\n translate: [300, 200]\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":287,"value":"md`\n

\n## Point Maps\n\nIn addition to the _geometric_ data provided by GeoJSON or TopoJSON files, many tabular datasets include geographic information in the form of fields for \\`longitude\\` and \\`latitude\\` coordinates, or references to geographic regions such as country names, state names, postal codes, _etc._, which can be mapped to coordinates using a [geocoding service](https://en.wikipedia.org/wiki/Geocoding). In some cases, location data is rich enough that we can see meaningful patterns by projecting the data points alone — no base map required!\n\nLet's look at a dataset of 5-digit zip codes in the United States, including \\`longitude\\`, \\`latitude\\` coordinates for each post office in addition to a \\`zip_code\\` field.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":416,"value":"zipcodes = datasets['zipcodes.csv'].url","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":999,"value":"md`\nWe can visualize each post office location using a small (1-pixel) \\`square\\` mark. However, to set the positions we do _not_ use \\`x\\` and \\`y\\` channels. _Why is that?_\n\nWhile cartographic projections map (\\`longitude\\`, \\`latitude\\`) coordinates to (\\`x\\`, \\`y\\`) coordinates, they can do so in arbitrary ways. There is no guarantee, for example, that \\`longitude\\` → \\`x\\` and \\`latitude\\` → \\`y\\`! Instead, Vega-Lite includes special \\`longitude\\` and \\`latitude\\` encoding channels to handle geographic coordinates. These channels indicate which data fields should be mapped to \\`longitude\\` and \\`latitude\\` coordinates, and then applies a projection to map those coordinates to (\\`x\\`, \\`y\\`) positions.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":551,"value":"render({\n mark: { type: 'square', size: 1, opacity: 1 },\n data: { url: zipcodes },\n encoding: {\n longitude: { field: 'longitude', type: 'Q' }, // apply the field named 'longitude' to the longitude channel\n latitude: { field: 'latitude', type: 'Q' } // apply the field named 'latitude' to the latitude channel\n },\n projection: { type: 'albersUsa' },\n width: 900,\n height: 500,\n config: { view: { stroke: null } }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1007,"value":"md`\n_Plotting zip codes only, we can see the outline of the United States and discern meaningful patterns in the density of post offices, without a base map or additional reference elements!_\n\nWe use the \\`albersUsa\\` projection, which takes some liberties with the actual geometry of the Earth, with scaled versions of Alaska and Hawaii in the bottom-left corner. As we did not specify projection \\`scale\\` or \\`translate\\` parameters, Vega-Lite sets them automatically to fit the visualized data. \n\nWe can now go on to ask more questions of our dataset. For example, is there any rhyme or reason to the allocation of zip codes? To assess this question we can add a color encoding based on the first digit of the zip code. We first add a \\`calculate\\` transform to extract the first digit, and encode the result using the color channel:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":289,"value":"render({\n mark: { type: 'square', size: 2, opacity: 1 },\n data: { url: zipcodes },\n transform: [\n { calculate: 'datum.zip_code[0]', as: 'digit' }\n ],\n encoding: {\n longitude: { field: 'longitude', type: 'Q' },\n latitude: { field: 'latitude', type: 'Q' },\n color: { field: 'digit', type: 'N' }\n },\n projection: { type: 'albersUsa' },\n width: 900,\n height: 500,\n config: { view: { stroke: null } }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":565,"value":"md`\n_To highlight specific digits, try adding an [interactive selection](https://observablehq.com/@uwdata/interaction-json) bound to the color legend, such that viewers can shift-click legend entries to dynamically update the map._\n\n(This example is inspired by Ben Fry's classic [zipdecode](https://benfry.com/zipdecode/) visualization!)\n\nWe might further wonder what the _sequence_ of zip codes might indicate. One way to explore this question is to connect each consecutive zip code using a \\`line\\` mark, as done in Robert Kosara's [ZipScribble](https://eagereyes.org/zipscribble-maps/united-states) visualization:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":313,"value":"render({\n mark: { type: 'line', strokeWidth: 0.5 },\n data: { url: zipcodes },\n transform: [\n { filter: '-150 < datum.longitude && 22 < datum.latitude && datum.latitude < 55' },\n { calculate: 'datum.zip_code[0]', as: 'digit' }\n ],\n encoding: {\n longitude: { field: 'longitude', type: 'Q' },\n latitude: { field: 'latitude', type: 'Q' },\n color: { field: 'digit', type: 'N' },\n order: { field: 'zip_code', type: 'O' }\n },\n projection: { type: 'albersUsa' },\n width: 900,\n height: 500,\n config: { view: { stroke: null } }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1041,"value":"md`\n_We can now see how zip codes further cluster into smaller areas, indicating a hierarchical allocation of codes by location, but with some notable variability within local clusters._\n\nIf you were paying careful attention to our earlier maps, you may have noticed that there are zip codes being plotted in the upper-left corner! These correspond to locations such as Puerto Rico or American Samoa, which contain U.S. zip codes but are mapped to \\`null\\` coordinates (\\`0\\`, \\`0\\`) by the \\`albersUsa\\` projection. In addition, Alaska and Hawaii can complicate our view of the connecting line segments. In response, the code above includes an additional filter that removes points outside our chosen \\`longitude\\` and \\`latitude\\` spans.\n_Remove the filter above to see what happens!_\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":7,"value":"md`\n

\n## Symbol Maps\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":495,"value":"md`\nNow let's combine a base map and plotted data as separate layers. We'll examine the U.S. commercial flight network, considering both airports and flight routes. To do so, we'll need three datasets.\nFor our base map, we'll use a TopoJSON file for the United States at 10m resolution, containing features for \\`states\\` or \\`counties\\`:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":647,"value":"usa = datasets['us-10m.json']()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1070,"value":"md`\nFor the airports, we will use a dataset with fields for the \\`longitude\\` and \\`latitude\\` coordinates of each airport as well as the \\`iata\\` airport code — for example, \\`'SEA'\\` for [Seattle-Tacoma International Airport](https://en.wikipedia.org/wiki/Seattle%E2%80%93Tacoma_International_Airport).\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":634,"value":"airports = datasets['airports.csv'].url","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1075,"value":"md`\nFinally, we will use a dataset of flight routes, which contains \\`origin\\` and \\`destination\\` fields with the IATA codes for the corresponding airports:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":637,"value":"flights = datasets['flights-airport.csv'].url","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1081,"value":"md`\nLet's start by creating a base map using the \\`albersUsa\\` projection, and add a layer that plots \\`circle\\` marks for each airport:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":397,"value":"render({\n layer: [\n {\n mark: { type: 'geoshape', fill: '#ddd', stroke: '#fff', strokeWidth: 1 },\n data: {\n values: usa,\n format: { type: 'topojson', feature: 'states' }\n }\n },\n {\n mark: { type: 'circle', size: 9 },\n data: { url: airports },\n encoding: {\n latitude: { field: 'latitude', type: 'Q' },\n longitude: { field: 'longitude', type: 'Q' },\n tooltip: { field: 'iata', type: 'N' }\n }\n },\n ],\n projection: { type: 'albersUsa' },\n width: 900,\n height: 500,\n config: { view: { stroke: null } }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":493,"value":"$31","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":463,"value":"$32","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1199,"value":"md`\nNow that we can see the airports, we may wish to interact with them to better understand the structure of the air traffic network. We can add a \\`rule\\` mark layer to represent paths from \\`origin\\` airports to \\`destination\\` airports, which requires two \\`lookup\\` transforms to retreive coordinates for each end point. In addition, we can use a \\`single\\` selection to filter these routes, such that only the routes originating at the currently selected airport are shown. _Mouseover the map to probe the flight network!_\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1190,"value":"view","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1205,"value":"md`\n_Starting from the static map above, can you build this interactive version?_\n\nIf you'd like to see the code for this interactive map, click through to the linked notebook below, from which this example has been imported:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1188,"value":"import {view} from '@vega/vega-lite-airport-connections'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":22,"value":"md`\n

\n## Choropleth Maps\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":447,"value":"md`\nA [choropleth map](https://en.wikipedia.org/wiki/Choropleth_map) uses shaded or textured regions to visualize data values. Sized symbol maps may be more accurate to read, as people tend to be better at estimating proportional differences between the area of circles than between color shades. Nevertheless, choropleth maps are popular in practice for visualizing rates and useful when too many symbols become perceptually overwhelming.\n\nFor example, while the United States only has 50 states, it has thousands of counties within those states. Let's build a choropleth map of the unemployment rate per county, back in the recession year of 2008. In some cases, input GeoJSON or TopoJSON files might include statistical data that we can directly visualize. In this case, however, we have two files: our TopoJSON file that includes county boundary features (\\`usa\\`), and a separate text file that contains unemployment statistics:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":449,"value":"unemp = datasets['unemployment.tsv'].url","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1421,"value":"md`\nTo integrate our data sources, we will again need to use the \\`lookup\\` transform, augmenting our TopoJSON-based \\`geoshape\\` data with unemployment rates. We can then create a map that includes a \\`color\\` encoding for the looked-up \\`rate\\` field.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":262,"value":"render({\n mark: { type: 'geoshape', stroke: '#aaa', strokeWidth: 0.25 },\n data: {\n values: usa,\n format: { type: 'topojson', feature: 'counties' }\n },\n transform: [\n {\n lookup: 'id',\n from: { data: { url: unemp }, key: 'id', fields: ['rate'] }\n },\n ],\n encoding: {\n color: {\n field: 'rate', type: 'Q',\n scale: { domain: [0, 0.3], clamp: true },\n legend: { format: '%' }\n },\n tooltip: { field: 'rate', type: 'Q' }\n },\n projection: { type: 'albersUsa' },\n width: 890,\n height: 500,\n config: { view: { stroke: null } }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1428,"value":"md`\n*Examine the unemployment rates by county. Higher values in Michigan may relate to the automotive industry. Counties in the [Great Plains](https://en.wikipedia.org/wiki/Great_Plains) and Mountain states exhibit both low **and** high rates. Is this variation meaningful, or is it possibly an [artifact of lower sample sizes](https://medium.com/@uwdata/surprise-maps-showing-the-unexpected-e92b67398865)? To explore, change the upper scale domain (e.g., to \\`0.2\\`) to adjust the color mapping.*\n\nA central concern for choropleth maps is the choice of colors. Above, we use Vega-Lite's default \\`'yellowgreenblue'\\` scheme for heatmaps. Below we compare other schemes, including a _single-hue sequential_ scheme (\\`teals\\`) that varies in luminance only, a _multi-hue sequential_ scheme (\\`viridis\\`) that ramps in both luminance and hue, and a _diverging_ scheme (\\`blueorange\\`) that uses a white mid-point:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":513,"value":"{\n // utility function to generate a map specification for a provided color scheme\n function map(scheme) {\n return {\n mark: { type: 'geoshape' },\n encoding: {\n color: { field: 'rate', type: 'Q', scale: { scheme }, legend: null }\n },\n projection: { type: 'albersUsa' },\n width: 300,\n height: 200\n };\n }\n \n return render({\n hconcat: [\n map('tealblues'),\n map('viridis'),\n map('blueorange')\n ],\n data: {\n values: usa,\n format: { type: 'topojson', feature: 'counties' }\n },\n transform: [\n {\n lookup: 'id',\n from: { data: { url: unemp }, key: 'id', fields: ['rate'] }\n },\n ],\n config: { view: { stroke: null } },\n resolve: { scale: { color: 'independent' } }\n });\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1440,"value":"md`\n_Which color schemes do you find to be more effective? Why might that be? Modify the maps to use other available schemes, as described in the [Vega Color Schemes documentation](https://vega.github.io/vega/docs/schemes/)._\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":86,"value":"md`\n

\n## Cartographic Projections\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":627,"value":"$33","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1240,"value":"render({\n ...map,\n projection: { type, translate, rotate, scale },\n width: 900,\n height: 500,\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1217,"value":"viewof type = menu('Type', [\n 'naturalEarth1',\n 'albers',\n 'azimuthalEqualArea',\n 'azimuthalEquidistant',\n 'conicConformal',\n 'conicEqualArea',\n 'conicEquidistant',\n 'equirectangular',\n 'gnomonic',\n 'mercator',\n 'orthographic',\n 'stereographic',\n 'transverseMercator'\n])","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1230,"value":"viewof scale = slider('Scale', 140, 50, 1000, 1)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1233,"value":"viewof rotate = rotate3D()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1236,"value":"viewof translate = translate2D()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1509,"value":"md`\nFor a similar example that extends Vega-Lite with a large number of additional projections, see the [Vega-Lite Cartographic Projections notebook](https://observablehq.com/@vega/vega-lite-cartographic-projections).\n

\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1381,"value":"md`\n### A Tour of Specific Projection Types\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1277,"value":"{\n const minimap = { ...map, width: 225, height: 225 };\n return render({\n hconcat: [\n { ...minimap, projection: { type: 'equirectangular' }, title: 'equirectangular' },\n { ...minimap, projection: { type: 'mercator' }, title: 'mercator' },\n { ...minimap, projection: { type: 'transverseMercator' }, title: 'transverseMercator' },\n { ...minimap, projection: { type: 'naturalEarth1' }, title: 'naturalEarth1' }\n ],\n config: { view: { stroke: null } },\n spacing: 10\n })\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":91,"value":"$34","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1284,"value":"{\n const minimap = { ...map, width: 180, height: 130 };\n return render({\n hconcat: [\n { ...minimap, projection: { type: 'conicEqualArea' }, title: 'conicEqualArea' },\n { ...minimap, projection: { type: 'conicEquidistant' }, title: 'conicEquidistant' },\n { ...minimap, projection: { type: 'conicConformal', scale: 35, translate: [90, 65] }, title: 'conicConformal' },\n { ...minimap, projection: { type: 'albers' }, title: 'albers' },\n { ...minimap, projection: { type: 'albersUsa' }, title: 'albersUsa' }\n ],\n config: { view: { stroke: null } },\n spacing: 10\n })\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":93,"value":"$35","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":95,"value":"{\n const minimap = { ...map, width: 180, height: 180 };\n return render({\n hconcat: [\n { ...minimap, projection: { type: 'azimuthalEqualArea' }, title: 'azimuthalEqualArea' },\n { ...minimap, projection: { type: 'azimuthalEquidistant' }, title: 'azimuthalEquidistant' },\n { ...minimap, projection: { type: 'orthographic' }, title: 'orthographic' },\n { ...minimap, projection: { type: 'stereographic' }, title: 'stereographic' },\n { ...minimap, projection: { type: 'gnomonic' }, title: 'gnomonic' }\n ],\n config: { view: { stroke: null } },\n spacing: 10\n })\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":88,"value":"$36","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":9,"value":"md`\n

\n## Coda: Wrangling Geographic Data\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1468,"value":"$37","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1487,"value":"md`\n

\n## Summary\n\nAt this point, we've only dipped our toes into the waters of map-making. _(You didn't expect a single notebook to impart centuries of learning, did you?)_ For example, we left untouched topics such as [_cartograms_](https://en.wikipedia.org/wiki/Cartogram) and conveying [_topography_](https://en.wikipedia.org/wiki/Topography) — as in Imhof's illuminating book [_Cartographic Relief Presentation_](https://books.google.com/books?id=cVy1Ms43fFYC). Nevertheless, you should now be well-equipped to create a rich array of geo-visualizations. For more, MacEachren's book [_How Maps Work: Representation, Visualization, and Design_](https://books.google.com/books?id=xhAvN3B0CkUC) provides a valuable overview of map-making from the perspective of data visualization. \n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":149,"value":"md`\n

\n## Imports & Utilities\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":982,"value":"import {printTable} from '@uwdata/data-utilities'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":156,"value":"import {menu, rotate3D, slider, translate2D} from '@jheer/dom-utilities'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W38","stdlib":"1","titling":"auto"}} 2e:"$2d:body"