From 9033dcd7e1717d2c0b49a237b6f2f8fed615c211 Mon Sep 17 00:00:00 2001 From: Paolo Di Lorenzo Date: Thu, 24 Feb 2022 12:13:41 -0500 Subject: [PATCH 1/3] Add data format information to mapping vignette --- .gitignore | 2 + usmap.Rproj | 2 +- vignettes/advanced-mapping.R | 63 ++++++ vignettes/advanced-mapping.html | 255 +++++++++++++++++++++++ vignettes/introduction.R | 34 +++ vignettes/introduction.html | 230 +++++++++++++++++++++ vignettes/mapping.R | 130 ++++++++++++ vignettes/mapping.Rmd | 53 +++++ vignettes/mapping.html | 353 ++++++++++++++++++++++++++++++++ 9 files changed, 1121 insertions(+), 1 deletion(-) create mode 100644 vignettes/advanced-mapping.R create mode 100644 vignettes/advanced-mapping.html create mode 100644 vignettes/introduction.R create mode 100644 vignettes/introduction.html create mode 100644 vignettes/mapping.R create mode 100644 vignettes/mapping.html diff --git a/.gitignore b/.gitignore index 0124a57..3066967 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,5 @@ data-raw/PopulationEstimates.xls data-raw/PovertyEstimates.xls doc Meta +/doc/ +/Meta/ diff --git a/usmap.Rproj b/usmap.Rproj index 30e02be..91f38d3 100644 --- a/usmap.Rproj +++ b/usmap.Rproj @@ -18,4 +18,4 @@ StripTrailingWhitespace: Yes BuildType: Package PackageUseDevtools: Yes PackageInstallArgs: --no-multiarch --with-keep.source -PackageRoxygenize: rd,collate,namespace +PackageRoxygenize: rd,collate,namespace,vignette diff --git a/vignettes/advanced-mapping.R b/vignettes/advanced-mapping.R new file mode 100644 index 0000000..50ab818 --- /dev/null +++ b/vignettes/advanced-mapping.R @@ -0,0 +1,63 @@ +## ----setup, include = FALSE--------------------------------------------------- +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) + +## ---- fig.align='center', fig.width=7, fig.height=5, message=FALSE, warning=FALSE---- +usmap::plot_usmap("states", labels = TRUE) + +## ---- fig.align='center', fig.width=7, fig.height=5, message=FALSE, warning=FALSE---- +usmap::plot_usmap("counties", include = c("MA", "CT", "RI"), labels = TRUE) + +## ---- fig.align='center', fig.width=7, fig.height=5, message=FALSE, warning=FALSE---- +usmap::plot_usmap("counties", + include = c("MA", "CT", "RI"), + labels = TRUE, label_color = "blue") + +## ---- fig.align='center', fig.width=7, fig.height=5, message=FALSE, warning=FALSE---- +usmap::plot_usmap("counties", + include = c("MA", "CT", "RI"), + labels = TRUE, label_color = "blue", + fill = "yellow", alpha = 0.25, color = "orange", size = 2) + +## ----------------------------------------------------------------------------- +usmap::usmap_crs()@projargs + +## ---- fig.align='center', fig.width=8, fig.height=5, message=FALSE, warning=FALSE---- +library(usmap) +library(ggplot2) + +eq_transformed <- usmap_transform(earthquakes) + +plot_usmap() + + geom_point(data = eq_transformed, aes(x = lon.1, y = lat.1, size = mag), + color = "red", alpha = 0.25) + + labs(title = "US Earthquakes", + subtitle = "Source: USGS, Jan 1 to Jun 30 2019", + size = "Magnitude") + + theme(legend.position = "right") + +## ---- fig.align='center', fig.width=8, fig.height=5, message=FALSE, warning=FALSE---- +library(usmap) +library(ggplot2) + +cities_t <- usmap_transform(citypop) + +plot_usmap(fill = "yellow", alpha = 0.25) + + ggrepel::geom_label_repel(data = cities_t, + aes(x = lon.1, y = lat.1, label = most_populous_city), + size = 3, alpha = 0.8, + label.r = unit(0.5, "lines"), label.size = 0.5, + segment.color = "red", segment.size = 1, + seed = 1002) + + geom_point(data = cities_t, + aes(x = lon.1, y = lat.1, size = city_pop), + color = "purple", alpha = 0.5) + + scale_size_continuous(range = c(1, 16), + label = scales::comma) + + labs(title = "Most Populous City in Each US State", + subtitle = "Source: US Census 2010", + size = "City Population") + + theme(legend.position = "right") + diff --git a/vignettes/advanced-mapping.html b/vignettes/advanced-mapping.html new file mode 100644 index 0000000..9e45108 --- /dev/null +++ b/vignettes/advanced-mapping.html @@ -0,0 +1,255 @@ + + + + + + + + + + + + + + + + +3. Advanced Mapping + + + + + + + + + + + + + + + + + + + + + + + + + +

3. Advanced Mapping

+

Paolo Di Lorenzo

+

2022-02-24

+ + + +

This vignette will explore some of the more advanced mapping features of usmap. Before continuing, be sure to check out Mapping the US as that will cover more of the basics of plotting US maps and styling them with ggplot2.

+
+

Labels

+

As of usmap 0.4.0, maps with state labels can be created:

+
usmap::plot_usmap("states", labels = TRUE)
+

+

usmap 0.5.0 adds the ability to add county labels:

+
usmap::plot_usmap("counties", include = c("MA", "CT", "RI"), labels = TRUE)
+

+

Labels can be colored using the label_color parameter:

+
usmap::plot_usmap("counties",
+                  include = c("MA", "CT", "RI"),
+                  labels = TRUE, label_color = "blue")
+

+
+
+

ggplot2 aesthetic mapping parameters

+

Parameters used by the map’s aesthetic mapping (ggplot2::aes) can be passed directly via plot_usmap by adding the parameters anywhere at the call site:

+
usmap::plot_usmap("counties",
+                  include = c("MA", "CT", "RI"),
+                  labels = TRUE, label_color = "blue",
+                  fill = "yellow", alpha = 0.25, color = "orange", size = 2)
+

+

Notice in this case we set the fill and alpha parameters to fill in the counties with a semi-transparent yellow color.

+

The following parameters are supported:

+ +
+
+

Transform data frames to match usmap projection

+

Data sets with longitude and latitude coordinates can be transformed to match the projection used in usmap (Albers Equal Area projection). This is convenient for plotting location-specific data and values using ggplot2 layers such as geom_point and geom_label.

+
+

Projection

+

The projection used by usmap can also be accessed by using usmap_crs():

+
usmap::usmap_crs()@projargs
+#> Warning in showSRID(uprojargs, format = "PROJ", multiline = "NO", prefer_proj =
+#> prefer_proj): Discarded datum unknown in Proj4 definition
+#> [1] "+proj=laea +lat_0=45 +lon_0=-100 +x_0=0 +y_0=0 +ellps=sphere +units=m +no_defs"
+

A convenience method called usmap_transform is provided that transforms a data.frame containing longitude/latitude columns to use this projection. (Currently, only data.frames are supported. Other structures may be supported in the future.)

+
+
+

Example: earthquakes

+

Here is an example using the provided earthquakes data set:

+
library(usmap)
+library(ggplot2)
+
+eq_transformed <- usmap_transform(earthquakes)
+
+plot_usmap() +
+  geom_point(data = eq_transformed, aes(x = lon.1, y = lat.1, size = mag),
+             color = "red", alpha = 0.25) +
+  labs(title = "US Earthquakes",
+       subtitle = "Source: USGS, Jan 1 to Jun 30 2019",
+       size = "Magnitude") +
+  theme(legend.position = "right")
+

+
+
+

Example: most populous city in each state

+

And a more comprehensive example using the provided citypop dataset:

+
library(usmap)
+library(ggplot2)
+
+cities_t <- usmap_transform(citypop)
+
+plot_usmap(fill = "yellow", alpha = 0.25) +
+  ggrepel::geom_label_repel(data = cities_t,
+             aes(x = lon.1, y = lat.1, label = most_populous_city),
+             size = 3, alpha = 0.8,
+             label.r = unit(0.5, "lines"), label.size = 0.5,
+             segment.color = "red", segment.size = 1,
+             seed = 1002) +
+  geom_point(data = cities_t,
+             aes(x = lon.1, y = lat.1, size = city_pop),
+             color = "purple", alpha = 0.5) +
+  scale_size_continuous(range = c(1, 16),
+                        label = scales::comma) +
+  labs(title = "Most Populous City in Each US State",
+       subtitle = "Source: US Census 2010",
+       size = "City Population") +
+  theme(legend.position = "right")
+

+

The usmap_transform function, combined with the power of ggplot2 layers can allow for some very unique and complex data visualizations on the US map. The usmap_transform function also handles transforming points in the Alaska/Hawaii area so that they are appropriately displayed on their respective states.

+

Currently, usmap_transform does not trim any points that fall outside the Alaska/Hawaii/US bounding boxes so it is important to prepare the data beforehand by eliminating any points that should not be displayed on the map otherwise it could have undesirable results.

+
+
+ + + + + + + + + + + diff --git a/vignettes/introduction.R b/vignettes/introduction.R new file mode 100644 index 0000000..783b666 --- /dev/null +++ b/vignettes/introduction.R @@ -0,0 +1,34 @@ +## ----setup, include = FALSE--------------------------------------------------- +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) + +## ---- fig.align='center', fig.width=7----------------------------------------- +usmap::plot_usmap() + +## ---- fig.align='center', fig.width=7----------------------------------------- +usmap::plot_usmap(regions = "counties") + +## ---- eval = FALSE------------------------------------------------------------ +# states_df <- usmap::us_map() +# counties_df <- usmap::us_map(regions = "counties") + +## ----------------------------------------------------------------------------- +# Get FIPS code for a state +usmap::fips(state = "MA") +usmap::fips(state = "Massachusetts") + +# Get FIPS code for a county +usmap::fips(state = "NJ", county = "Bergen") +usmap::fips(state = "CA", county = "Orange County") + +# The parameters are NOT case sensitive! +usmap::fips(state = "ca", county = "oRanGe cOUNty") + +## ----------------------------------------------------------------------------- +usmap::fips_info(c("30", "33", "34")) + +## ----------------------------------------------------------------------------- +usmap::fips_info(c("01001", "01003", "01005", "01007")) + diff --git a/vignettes/introduction.html b/vignettes/introduction.html new file mode 100644 index 0000000..b43fb55 --- /dev/null +++ b/vignettes/introduction.html @@ -0,0 +1,230 @@ + + + + + + + + + + + + + + + + +1. Introduction + + + + + + + + + + + + + + + + + + + + + + + + + +

1. Introduction

+

Paolo Di Lorenzo

+

2022-02-24

+ + + +
+

Plotting

+

Plots of US maps in R usually lack Alaska and Hawaii. The reason is plotting takes the literal longitude and latitude coordinates and maps it to a cartesian x-y coordinate graph. Alaska and Hawaii are very far from the mainland US when using this so it can be unwieldy to include them. The usmap package solves this issue by providing data frames which have Alaska and Hawaii moved to a convenient spot just to the bottom left of the contiguous United States.

+
+

Blank US state map

+
usmap::plot_usmap()
+

+
+
+

Blank US county map

+
usmap::plot_usmap(regions = "counties")
+

+
+
+
+

Raw map data

+

The raw US map data for counties or states can be obtained for further manipulation (and joining with data). The default regions is "states".

+
states_df <- usmap::us_map()
+counties_df <- usmap::us_map(regions = "counties")
+
+
+

FIPS codes

+

FIPS codes are defined in the Federal Information Processing Standards by the US government. One usage is uniquely identifying US states and counties (among other things such as identifying countries for the CIA World Factbook). Downloading datasets from the US Census will often include FIPS codes as identifiers so it can be helpful to know what a FIPS code represents. The functions in usmap are built around the FIPS code identification system and so convenience methods for accessing them and performing reverse-lookups have been included.

+
+

State/County FIPS lookup

+
# Get FIPS code for a state
+usmap::fips(state = "MA")
+#> [1] "25"
+usmap::fips(state = "Massachusetts")
+#> [1] "25"
+
+# Get FIPS code for a county
+usmap::fips(state = "NJ", county = "Bergen")
+#> [1] "34003"
+usmap::fips(state = "CA", county = "Orange County")
+#> [1] "06059"
+
+# The parameters are NOT case sensitive!
+usmap::fips(state = "ca", county = "oRanGe cOUNty")
+#> [1] "06059"
+
+
+

FIPS reverse lookup

+

If the FIPS code is known and want to see what state/county it corresponds to, use the reverse lookup function fips_info.

+
usmap::fips_info(c("30", "33", "34"))
+#>   abbr fips          full
+#> 1   MT   30       Montana
+#> 2   NH   33 New Hampshire
+#> 3   NJ   34    New Jersey
+
usmap::fips_info(c("01001", "01003", "01005", "01007"))
+#>      full abbr         county  fips
+#> 1 Alabama   AL Autauga County 01001
+#> 2 Alabama   AL Baldwin County 01003
+#> 3 Alabama   AL Barbour County 01005
+#> 4 Alabama   AL    Bibb County 01007
+
+
+

Further reading

+

More information about FIPS can be read here.

+
+
+

“A map is the greatest of all epic poems. Its lines and colors show the realization of great dreams.” - Gilbert H. Grosvenor, Editor of National Geographic (1903 - 1954)

+
+
+
+ + + + + + + + + + + diff --git a/vignettes/mapping.R b/vignettes/mapping.R new file mode 100644 index 0000000..5b99632 --- /dev/null +++ b/vignettes/mapping.R @@ -0,0 +1,130 @@ +## ----setup, include = FALSE--------------------------------------------------- +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +library(usmap) +library(ggplot2) + +plot_usmap(regions = "counties") + + labs(title = "US Counties", + subtitle = "This is a blank map of the counties of the United States.") + + theme(panel.background = element_rect(color = "black", fill = "lightblue")) + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +library(usmap) +library(ggplot2) + +plot_usmap(include = c("CA", "ID", "NV", "OR", "WA")) + + labs(title = "Western US States", + subtitle = "These are the states in the Pacific Timezone.") + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +library(usmap) +library(ggplot2) + +plot_usmap(data = statepop, values = "pop_2015", color = "red") + + scale_fill_continuous(name = "Population (2015)", label = scales::comma) + + theme(legend.position = "right") + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +library(usmap) +library(ggplot2) + +plot_usmap(data = statepop, values = "pop_2015", color = "red") + + scale_fill_continuous( + low = "white", high = "red", name = "Population (2015)", label = scales::comma + ) + theme(legend.position = "right") + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +library(usmap) +library(ggplot2) + +plot_usmap( + data = statepop, values = "pop_2015", include = c("CA", "ID", "NV", "OR", "WA"), color = "red" + ) + + scale_fill_continuous( + low = "white", high = "red", name = "Population (2015)", label = scales::comma + ) + + labs(title = "Western US States", subtitle = "These are the states in the Pacific Timezone.") + + theme(legend.position = "right") + +## ---- fig.show='hide', message=FALSE, warning=FALSE--------------------------- +df <- data.frame( + fips = c("02", "01", "05", "04"), + values = c(14, 18, 19, 8) +) + +plot_usmap(data = df) + +## ---- fig.show='hide', message=FALSE, warning=FALSE--------------------------- +df <- data.frame( + fips = c("02", "01", "05", "04"), + population = c(14, 18, 19, 8) +) + +plot_usmap(data = df, values = "population") + +## ---- fig.show='hide', message=FALSE, warning=FALSE--------------------------- +df <- data.frame( + state = c("AL", "Alaska", "AR", "AZ"), + values = c(14, 18, 19, 8) +) + +plot_usmap(data = df) + +## ---- fig.show='hide', message=FALSE, warning=FALSE--------------------------- +df <- data.frame( + fips = c("10001", "10003", "10005"), + values = c(93, 98, 41) +) + +plot_usmap(data = df) + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +usmap::plot_usmap(include = .south_region) + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +usmap::plot_usmap(include = .east_south_central) + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +usmap::plot_usmap(include = .south_region, exclude = .east_south_central) + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +usmap::plot_usmap("counties", + include = c(.south_region, "IA"), + exclude = c(.east_south_central, "12")) # 12 = FL + +## ---- fig.align='center', fig.width=7, message=FALSE, warning=FALSE----------- +usmap::plot_usmap("counties", fill = "yellow", alpha = 0.25, + # 06065 = Riverside County, CA + include = c(.south_region, "IA", "06065"), + # 12 = FL, 48141 = El Paso County, TX + exclude = c(.east_south_central, "12", "48141")) + +## ----------------------------------------------------------------------------- +.new_england +.mid_atlantic +.east_north_central +.west_north_central +.south_atlantic +.east_south_central +.west_south_central +.mountain +.pacific + +## ----------------------------------------------------------------------------- +.northeast_region # c(.new_england, .mid_atlantic) +.north_central_region # c(.east_north_central, .west_north_central) +.midwest_region # .north_central_region (renamed in June 1984) +.south_region # c(.south_atlantic, .east_south_central, .west_south_central) +.west_region # c(.mountain, .pacific) + +## ----------------------------------------------------------------------------- +str(usmap::us_map()) + +## ----------------------------------------------------------------------------- +str(usmap::us_map(regions = "counties")) + diff --git a/vignettes/mapping.Rmd b/vignettes/mapping.Rmd index ddc9220..6ff641f 100644 --- a/vignettes/mapping.Rmd +++ b/vignettes/mapping.Rmd @@ -84,6 +84,59 @@ plot_usmap( theme(legend.position = "right") ``` +### Required Data Format + +The data passed to the `data` parameter in `plot_usmap()` must be a data frame +with at least two columns. One of the columns must be named `"fips"` or `"state"` and contain +either the FIPS code, the state abbreviation, or the state name (for county maps +only the FIPS code is supported). The second column must be the values to be plotted +for each region. The default name of the values column is `"values"`. If a different +name is used in the data frame, the name can be specified in the `values` parameter +of `plot_usmap`. Any extra columns in the data frame will be ignored. + +#### FIPS column with default `values` column +```{r, fig.show='hide', message=FALSE, warning=FALSE} +df <- data.frame( + fips = c("02", "01", "05", "04"), + values = c(14, 18, 19, 8) +) + +plot_usmap(data = df) +``` + +#### FIPS column with custom `values` column +Name of values column must be specified in `values` parameter if it is not `"values"`. +```{r, fig.show='hide', message=FALSE, warning=FALSE} +df <- data.frame( + fips = c("02", "01", "05", "04"), + population = c(14, 18, 19, 8) +) + +plot_usmap(data = df, values = "population") +``` + +#### States +Abbreviations and full names can be mixed if desired. +```{r, fig.show='hide', message=FALSE, warning=FALSE} +df <- data.frame( + state = c("AL", "Alaska", "AR", "AZ"), + values = c(14, 18, 19, 8) +) + +plot_usmap(data = df) +``` + +#### Counties +County names are not supported in `plot_usmap` data frames. Use `fips` instead. +```{r, fig.show='hide', message=FALSE, warning=FALSE} +df <- data.frame( + fips = c("10001", "10003", "10005"), + values = c(93, 98, 41) +) + +plot_usmap(data = df) +``` + ## Built-in Regions `usmap` provides some built-in regions based on the [US Census Bureau Regions and Divisions](https://www2.census.gov/geo/pdfs/maps-data/maps/reference/us_regdiv.pdf). These can be used in place of the `include`/`exclude` parameters when using `us_map` or `plot_usmap` and start with a `.` (dot): diff --git a/vignettes/mapping.html b/vignettes/mapping.html new file mode 100644 index 0000000..2e49a10 --- /dev/null +++ b/vignettes/mapping.html @@ -0,0 +1,353 @@ + + + + + + + + + + + + + + + + +2. Mapping the US + + + + + + + + + + + + + + + + + + + + + + + + + +

2. Mapping the US

+

Paolo Di Lorenzo

+

2022-02-24

+ + + +
+

Extending plot_usmap with ggplot2

+

The nice thing about usmap::plot_usmap is it returns a ggplot object object, which means we can add ggplot layers to the plot right out of the box.

+
library(usmap)
+library(ggplot2)
+
+plot_usmap(regions = "counties") + 
+  labs(title = "US Counties",
+       subtitle = "This is a blank map of the counties of the United States.") + 
+  theme(panel.background = element_rect(color = "black", fill = "lightblue"))
+

+
+

Plot only certain states

+
library(usmap)
+library(ggplot2)
+
+plot_usmap(include = c("CA", "ID", "NV", "OR", "WA")) +
+  labs(title = "Western US States",
+       subtitle = "These are the states in the Pacific Timezone.")
+

+
+
+

Add some data to the map

+
library(usmap)
+library(ggplot2)
+
+plot_usmap(data = statepop, values = "pop_2015", color = "red") + 
+  scale_fill_continuous(name = "Population (2015)", label = scales::comma) + 
+  theme(legend.position = "right")
+

+

Notice the comprehensive expandability that can be applied to the map using ggplot2 layers. For example, we might want to use a different color scheme.

+
+
+

Change fill color scale

+
library(usmap)
+library(ggplot2)
+
+plot_usmap(data = statepop, values = "pop_2015", color = "red") + 
+  scale_fill_continuous(
+    low = "white", high = "red", name = "Population (2015)", label = scales::comma
+  ) + theme(legend.position = "right")
+

+

The data-filled map can also be filtered to show certain regions only, like the western states shown above.

+
+
+

Show data in certain states

+
library(usmap)
+library(ggplot2)
+
+plot_usmap(
+    data = statepop, values = "pop_2015", include = c("CA", "ID", "NV", "OR", "WA"), color = "red"
+  ) + 
+  scale_fill_continuous(
+    low = "white", high = "red", name = "Population (2015)", label = scales::comma
+  ) + 
+  labs(title = "Western US States", subtitle = "These are the states in the Pacific Timezone.") +
+  theme(legend.position = "right")
+

+
+
+

Required Data Format

+

The data passed to the data parameter in plot_usmap() must be a data frame with at least two columns. One of the columns must be named "fips" or "state" and contain either the FIPS code, the state abbreviation, or the state name (for county maps only the FIPS code is supported). The second column must be the values to be plotted for each region. The default name of the values column is "values". If a different name is used in the data frame, the name can be specified in the values parameter of plot_usmap. Any extra columns in the data frame will be ignored.

+
+

FIPS column with default values column

+
df <- data.frame(
+  fips = c("02", "01", "05", "04"),
+  values = c(14, 18, 19, 8)
+)
+
+plot_usmap(data = df)
+
+
+

FIPS column with custom values column

+

Name of values column must be specified in values parameter if it is not "values".

+
df <- data.frame(
+  fips = c("02", "01", "05", "04"),
+  population = c(14, 18, 19, 8)
+)
+
+plot_usmap(data = df, values = "population")
+
+
+

States

+

Abbreviations and full names can be mixed if desired.

+
df <- data.frame(
+  state = c("AL", "Alaska", "AR", "AZ"),
+  values = c(14, 18, 19, 8)
+)
+
+plot_usmap(data = df)
+
+
+

Counties

+

County names are not supported in plot_usmap data frames. Use fips instead.

+
df <- data.frame(
+  fips = c("10001", "10003", "10005"),
+  values = c(93, 98, 41)
+)
+
+plot_usmap(data = df)
+
+
+
+
+

Built-in Regions

+

usmap provides some built-in regions based on the US Census Bureau Regions and Divisions. These can be used in place of the include/exclude parameters when using us_map or plot_usmap and start with a . (dot):

+
usmap::plot_usmap(include = .south_region)
+

+
usmap::plot_usmap(include = .east_south_central)
+

+
usmap::plot_usmap(include = .south_region, exclude = .east_south_central)
+

+

This also works with county maps. The regions can also be combined with actual state or FIPS values within the include/exclude parameters:

+
usmap::plot_usmap("counties", 
+                  include = c(.south_region, "IA"), 
+                  exclude = c(.east_south_central, "12"))  # 12 = FL
+

+

You can even include or exclude individual counties (county-level inclusions/exclusions can only be done via their FIPS codes due to duplicate county names across states; for example eight different states have an “Orange County”):

+
usmap::plot_usmap("counties", fill = "yellow", alpha = 0.25,
+                  # 06065 = Riverside County, CA
+                  include = c(.south_region, "IA", "06065"),
+                  # 12 = FL, 48141 = El Paso County, TX
+                  exclude = c(.east_south_central, "12", "48141"))
+

+

These parameters therefore allow for the possibility of some complex compositions of states and counties, to create the exact map that is desired.

+
+

Supported US Census Regions and Divisions

+

The following divisions are supported:

+
.new_england
+#> [1] "CT" "MA" "ME" "NH" "RI" "VT"
+.mid_atlantic
+#> [1] "NJ" "NY" "PA"
+.east_north_central
+#> [1] "IL" "IN" "MI" "OH" "WI"
+.west_north_central
+#> [1] "IA" "KS" "MN" "MO" "NE" "ND" "SD"
+.south_atlantic
+#> [1] "DC" "DE" "FL" "GA" "MD" "NC" "SC" "VA" "WV"
+.east_south_central
+#> [1] "AL" "KY" "MS" "TN"
+.west_south_central
+#> [1] "AR" "LA" "OK" "TX"
+.mountain
+#> [1] "AZ" "CO" "ID" "MT" "NV" "NM" "UT" "WY"
+.pacific
+#> [1] "AK" "CA" "HI" "OR" "WA"
+

Regions are composed of multiple divisions, and the following are supported:

+
.northeast_region      # c(.new_england, .mid_atlantic)
+#> [1] "CT" "MA" "ME" "NH" "RI" "VT" "NJ" "NY" "PA"
+.north_central_region  # c(.east_north_central, .west_north_central)
+#>  [1] "IL" "IN" "MI" "OH" "WI" "IA" "KS" "MN" "MO" "NE" "ND" "SD"
+.midwest_region        # .north_central_region (renamed in June 1984)
+#>  [1] "IL" "IN" "MI" "OH" "WI" "IA" "KS" "MN" "MO" "NE" "ND" "SD"
+.south_region          # c(.south_atlantic, .east_south_central, .west_south_central)
+#>  [1] "DC" "DE" "FL" "GA" "MD" "NC" "SC" "VA" "WV" "AL" "KY" "MS" "TN" "AR" "LA"
+#> [16] "OK" "TX"
+.west_region           # c(.mountain, .pacific)
+#>  [1] "AZ" "CO" "ID" "MT" "NV" "NM" "UT" "WY" "AK" "CA" "HI" "OR" "WA"
+
+
+
+

Raw map data

+

The raw US map data for counties or states can be obtained for further manipulation (and joining with data).

+
str(usmap::us_map())
+#> 'data.frame':    13663 obs. of  9 variables:
+#>  $ x    : num  1091779 1091268 1091140 1090940 1090913 ...
+#>  $ y    : num  -1380695 -1376372 -1362998 -1343517 -1341006 ...
+#>  $ order: int  1 2 3 4 5 6 7 8 9 10 ...
+#>  $ hole : logi  FALSE FALSE FALSE FALSE FALSE FALSE ...
+#>  $ piece: int  1 1 1 1 1 1 1 1 1 1 ...
+#>  $ group: chr  "01.1" "01.1" "01.1" "01.1" ...
+#>  $ fips : chr  "01" "01" "01" "01" ...
+#>  $ abbr : chr  "AL" "AL" "AL" "AL" ...
+#>  $ full : chr  "Alabama" "Alabama" "Alabama" "Alabama" ...
+
str(usmap::us_map(regions = "counties"))
+#> 'data.frame':    55211 obs. of  10 variables:
+#>  $ x     : num  1225889 1244873 1244129 1272010 1276797 ...
+#>  $ y     : num  -1275020 -1272331 -1267515 -1262889 -1295514 ...
+#>  $ order : int  1 2 3 4 5 6 7 8 9 10 ...
+#>  $ hole  : logi  FALSE FALSE FALSE FALSE FALSE FALSE ...
+#>  $ piece : int  1 1 1 1 1 1 1 1 1 1 ...
+#>  $ group : chr  "01001.1" "01001.1" "01001.1" "01001.1" ...
+#>  $ fips  : chr  "01001" "01001" "01001" "01001" ...
+#>  $ abbr  : chr  "AL" "AL" "AL" "AL" ...
+#>  $ full  : chr  "Alabama" "Alabama" "Alabama" "Alabama" ...
+#>  $ county: chr  "Autauga County" "Autauga County" "Autauga County" "Autauga County" ...
+

You can also include only certain states and counties just like in plot_usmap. In fact, the regions and include parameters of plot_usmap are derived directly from their usage in us_map.

+
+ + + + + + + + + + + From 4f8b51f2efdb4d5b87182e1838282f6a2e272639 Mon Sep 17 00:00:00 2001 From: Paolo Di Lorenzo Date: Thu, 24 Feb 2022 12:17:27 -0500 Subject: [PATCH 2/3] Update NEWS.md with mapping vignette example data --- NEWS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index c61d25d..211e22e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,7 +1,7 @@ # usmap 0.5.2.9999 ### New Features -* Added `sortAndRemoveDuplicates` parameter to `fips_info`, see [Issue #47](https://github.com/pdil/usmap/issues/47). +* Add `sortAndRemoveDuplicates` parameter to `fips_info`, see [Issue #47](https://github.com/pdil/usmap/issues/47). * The default (`FALSE`) value changes existing behavior, to retain existing behavior, change the parameter value to `TRUE`. ### Improvements @@ -10,6 +10,7 @@ * Add shape file update history, see [Issue #30](https://github.com/pdil/usmap/issues/30). * Extract map data frame to external [usmapdata](https://github.com/pdil/usmapdata) package to reduce `usmap` package size, see [Issue #39](https://github.com/pdil/usmap/issues/39). * All existing functions (including `us_map()`) should continue to work as usual. +* Add data format examples for `plot_usmap` to "Mapping" vignette, see [Issue #42](https://github.com/pdil/usmap/issues/42). ### Bug Fixes * Fix CRS warnings, see [Issue #40](https://github.com/pdil/usmap/issues/40). From 14656e8232c10c340110284d393034c3e11b9b09 Mon Sep 17 00:00:00 2001 From: Paolo Di Lorenzo Date: Thu, 24 Feb 2022 12:22:44 -0500 Subject: [PATCH 3/3] Clean up .gitignore --- .gitignore | 3 --- 1 file changed, 3 deletions(-) diff --git a/.gitignore b/.gitignore index 3066967..7767042 100644 --- a/.gitignore +++ b/.gitignore @@ -2,9 +2,6 @@ .Rhistory .Rdata .Rproj.user -inst/doc -data-raw/PopulationEstimates.xls -data-raw/PovertyEstimates.xls doc Meta /doc/