Merge pull request #52 from pdil/feature/improve-plot-usmap-data-vign…

…ette

Add data format information to mapping vignette

.gitignore

@@ -2,8 +2,7 @@
 .Rhistory
 .Rdata
 .Rproj.user
-inst/doc
-data-raw/PopulationEstimates.xls
-data-raw/PovertyEstimates.xls
 doc
 Meta
+/doc/
+/Meta/

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).

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

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")
+

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"))
+

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"))
+

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):