diff --git a/NEWS.md b/NEWS.md index 5b121aa..70ad09d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -19,6 +19,7 @@ * Add state abbreviation (`abbr`) column to `citypop` data set. * Update and standardize documentation throughout the page. * Includes updates to formatting, links, and language. +* Rename vignettes to make them easier to find and read in order. ### Bug Fixes * `plot_usmap()` warnings have been cleaned up, including a defunct warning that didn't make sense. diff --git a/README.Rmd b/README.Rmd index 9467e97..b4bff5c 100644 --- a/README.Rmd +++ b/README.Rmd @@ -137,9 +137,9 @@ To read the package vignettes, which explain helpful uses of the package, use `v ```{r vignettes, eval=FALSE} vignette(package = "usmap") -vignette("introduction", package = "usmap") -vignette("mapping", package = "usmap") -vignette("advanced-mapping", package = "usmap") +vignette("usmap1", package = "usmap") # 1. Introduction +vignette("usmap2", package = "usmap") # 2. Mapping the US +vignette("usmap3", package = "usmap") # 3. Advanced Mapping ``` For further help with this package, open an [issue](https://github.com/pdil/usmap/issues) or ask a question on Stack Overflow with the [usmap tag](https://stackoverflow.com/questions/tagged/usmap). diff --git a/README.md b/README.md index 2749415..dcad0d7 100644 --- a/README.md +++ b/README.md @@ -78,9 +78,9 @@ package, use `vignette`: ``` r vignette(package = "usmap") -vignette("introduction", package = "usmap") -vignette("mapping", package = "usmap") -vignette("advanced-mapping", package = "usmap") +vignette("usmap1", package = "usmap") # 1. Introduction +vignette("usmap2", package = "usmap") # 2. Mapping the US +vignette("usmap3", package = "usmap") # 3. Advanced Mapping ``` For further help with this package, open an diff --git a/vignettes/introduction.R b/vignettes/usmap1.R similarity index 100% rename from vignettes/introduction.R rename to vignettes/usmap1.R diff --git a/vignettes/introduction.Rmd b/vignettes/usmap1.Rmd similarity index 100% rename from vignettes/introduction.Rmd rename to vignettes/usmap1.Rmd diff --git a/vignettes/introduction.html b/vignettes/usmap1.html similarity index 100% rename from vignettes/introduction.html rename to vignettes/usmap1.html diff --git a/vignettes/usmap2.R b/vignettes/usmap2.R new file mode 100644 index 0000000..a03f7d6 --- /dev/null +++ b/vignettes/usmap2.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/usmap2.Rmd similarity index 100% rename from vignettes/mapping.Rmd rename to vignettes/usmap2.Rmd diff --git a/vignettes/usmap2.html b/vignettes/usmap2.html new file mode 100644 index 0000000..6f12e0f --- /dev/null +++ b/vignettes/usmap2.html @@ -0,0 +1,695 @@ + + + + +
+ + + + + + + + + + + +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"))
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.
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.
+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")
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.
values
columnvalues
columnName of values column must be specified in values
+parameter if it is not "values"
.
Abbreviations and full names can be mixed if desired.
+ +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):
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.
+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"
The raw US map data for counties or states can be obtained for +further manipulation (and joining with data).
+str(usmap::us_map())
+#> sf [51 × 4] (S3: sf/tbl_df/tbl/data.frame)
+#> $ fips: chr [1:51] "02" "01" "05" "04" ...
+#> $ abbr: chr [1:51] "AK" "AL" "AR" "AZ" ...
+#> $ full: chr [1:51] "Alaska" "Alabama" "Arkansas" "Arizona" ...
+#> $ geom:sfc_MULTIPOLYGON of length 51; first list element: List of 47
+#> ..$ :List of 1
+#> .. ..$ : num [1:9, 1:2] -2396840 -2393291 -2391546 -2387936 -2389504 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:14, 1:2] -2427322 -2425167 -2417701 -2410965 -2408478 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -2427711 -2425161 -2424220 -2426373 -2427538 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:6, 1:2] -2437404 -2433523 -2432560 -2433195 -2436141 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -2438124 -2436202 -2435147 -2435635 -2438224 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:20, 1:2] -2466358 -2463249 -2461108 -2457911 -2455308 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -2552748 -2547440 -2545448 -2545614 -2550872 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:12, 1:2] -2570037 -2566525 -2563447 -2559775 -2562982 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:20, 1:2] -2590162 -2584107 -2579816 -2570785 -2567855 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:77, 1:2] -998192 -995832 -994898 -994108 -994655 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:63, 1:2] -1031446 -1029628 -1027489 -1026720 -1023270 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:45, 1:2] -1079172 -1075690 -1072247 -1069719 -1068935 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:78, 1:2] -1114429 -1114918 -1112822 -1111360 -1113978 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -1559255 -1557005 -1553878 -1554914 -1556086 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:8, 1:2] -1593056 -1590317 -1588256 -1586272 -1587021 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:121, 1:2] -1613128 -1611170 -1609485 -1607142 -1604137 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:14, 1:2] -1608746 -1605500 -1600464 -1591662 -1588388 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:9, 1:2] -1631697 -1630128 -1628077 -1625755 -1626036 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -1662325 -1660945 -1658747 -1658588 -1660341 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:8, 1:2] -1681080 -1677834 -1675396 -1671825 -1673813 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:24, 1:2] -1762717 -1761281 -1761394 -1760050 -1756781 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:19, 1:2] -1782141 -1780843 -1777284 -1772124 -1766769 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:9, 1:2] -1794059 -1793508 -1789766 -1783871 -1783252 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:6, 1:2] -1799022 -1796947 -1796134 -1796425 -1799699 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:5, 1:2] -1807247 -1802071 -1803042 -1806979 -1807247 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:9, 1:2] -1840779 -1832747 -1825286 -1826571 -1828928 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:14, 1:2] -1925210 -1921070 -1915290 -1910986 -1906891 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:13, 1:2] -1939240 -1936090 -1933288 -1925800 -1921299 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:44, 1:2] -1959913 -1956821 -1951540 -1947125 -1944663 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:58, 1:2] -1993832 -1990735 -1987508 -1983260 -1980521 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:1244, 1:2] -1938630 -1934845 -1927284 -1918684 -1906506 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:33, 1:2] -2041898 -2034008 -2031233 -2027955 -2025511 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -2043109 -2037341 -2033361 -2032975 -2036878 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:16, 1:2] -2069708 -2066809 -2064663 -2059491 -2056308 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -2056866 -2053453 -2048984 -2049052 -2053623 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:8, 1:2] -2090569 -2085742 -2081422 -2083407 -2086610 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:6, 1:2] -2106692 -2104793 -2102989 -2104213 -2106597 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:54, 1:2] -2040208 -2038602 -2037831 -2035786 -2032840 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:9, 1:2] -2148479 -2146116 -2142903 -2139188 -2138570 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:13, 1:2] -2099064 -2096034 -2095259 -2088709 -2084839 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:37, 1:2] -2234505 -2225781 -2221026 -2215636 -2210388 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:39, 1:2] -2288942 -2287039 -2282528 -2281643 -2282679 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:17, 1:2] -2311035 -2305247 -2299587 -2296721 -2294960 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:19, 1:2] -2326038 -2322610 -2318343 -2316893 -2312878 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -2350697 -2343602 -2339796 -2341253 -2346126 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:6, 1:2] -2347811 -2344673 -2343866 -2346051 -2348955 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:7, 1:2] -2362307 -2355457 -2353590 -2353421 -2359369 ...
+#> ..- attr(*, "class")= chr [1:3] "XY" "MULTIPOLYGON" "sfg"
+#> - attr(*, "sf_column")= chr "geom"
+#> - attr(*, "agr")= Factor w/ 3 levels "constant","aggregate",..: NA NA NA
+#> ..- attr(*, "names")= chr [1:3] "fips" "abbr" "full"
str(usmap::us_map(regions = "counties"))
+#> sf [3,144 × 5] (S3: sf/tbl_df/tbl/data.frame)
+#> $ fips : chr [1:3144] "02013" "02016" "02020" "02050" ...
+#> $ abbr : chr [1:3144] "AK" "AK" "AK" "AK" ...
+#> $ full : chr [1:3144] "Alaska" "Alaska" "Alaska" "Alaska" ...
+#> $ county: chr [1:3144] "Aleutians East Borough" "Aleutians West Census Area" "Anchorage Municipality" "Bethel Census Area" ...
+#> $ geom :sfc_MULTIPOLYGON of length 3144; first list element: List of 9
+#> ..$ :List of 1
+#> .. ..$ : num [1:24, 1:2] -1762717 -1761281 -1761394 -1760050 -1756781 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:19, 1:2] -1782141 -1780843 -1777284 -1772124 -1766769 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:6, 1:2] -1799022 -1796947 -1796134 -1796425 -1799699 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:5, 1:2] -1807247 -1802071 -1803042 -1806979 -1807247 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:9, 1:2] -1840779 -1832747 -1825286 -1826571 -1828928 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:157, 1:2] -1905044 -1902468 -1898740 -1896702 -1893728 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:14, 1:2] -1925210 -1921070 -1915290 -1910986 -1906891 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:13, 1:2] -1939240 -1936090 -1933288 -1925800 -1921299 ...
+#> ..$ :List of 1
+#> .. ..$ : num [1:6, 1:2] -1944455 -1942803 -1939834 -1942501 -1944477 ...
+#> ..- attr(*, "class")= chr [1:3] "XY" "MULTIPOLYGON" "sfg"
+#> - attr(*, "sf_column")= chr "geom"
+#> - attr(*, "agr")= Factor w/ 3 levels "constant","aggregate",..: NA NA NA NA
+#> ..- attr(*, "names")= chr [1:4] "fips" "abbr" "full" "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
.