Package 'MazamaSpatialPlots'

County level thematic map

Description

Uses the tmap package to generate a thematic map at the county level. Input consists of a dataframe with countyFIPS identifiers.

Data to plot is specified with parameter argument. If parameter is mult-valued, mutliple plots will be generated and displayed as "facets".

The returned object is a tmap ggplot object which can be further modified with tmap or ggplot options.

Usage

countyMap(
  data = NULL,
  parameter = NULL,
  state_SFDF = "USCensusStates_02",
  county_SFDF = "USCensusCounties_02",
  breaks = NULL,
  palette = "brewer.blues",
  conusOnly = TRUE,
  stateCode = NULL,
  projection = NULL,
  stateBorderColor = "gray50",
  countyBorderColor = "white",
  title = NULL,
  showLegend = TRUE,
  legendTitle = NULL,
  legendOrientation = c("portrait", "landscape"),
  legendPosition = NULL
)

Arguments

data	Dataframe containing values to plot. This dataframe must contain a column named countyFIPS with the 5-digit FIPS code.
parameter	Name of the column in data to use for coloring the map.
state_SFDF	simple features data frame with US states. It's data @slot must contain a column named stateCode if either conusOnly = TRUE or the stateCode argument is specified.
county_SFDF	simple features data frame with US counties. It's data @slot must always contain a column named and countyFIPS and a column named stateCode if either conusOnly = TRUE or the stateCode argument is specified.
breaks	Numeric vector of break points.
palette	A vector of colors or palette name from the cols4all package (see cols4all::c4a).
conusOnly	Logical specifying Continental US state codes. Ignored when the stateCode argument is specified.
stateCode	Vector of state codes to include on the map.
projection	Named projection, e.g. "EPSG:4326" or "WGS84" or proj4string.
stateBorderColor	Color used for state borders.
countyBorderColor	Color used for county borders.
title	Vector of text strings to use as individual plot titles. This must be the same length as 'parameter'.
showLegend	Logical specifying whether or not to show the legend.
legendTitle	Text string to use as the legend title.
legendOrientation	Orientation of the legend. Either "portrait" or "landscape".
legendPosition	A tm_pos object generated with tmap::tm_pos_in() or tmap::tm_pos_out().

Value

A ggplot object.

Examples

library(MazamaSpatialPlots)
mazama_initialize()

countyMap(
  data = example_US_countyCovid,
  parameter = "cases",
  breaks = c(0,100,200,500,1000,2000,5000,10000,20000,50000,1e6),
  title = "COVID-19 Cases on June 01 2020"
)

countyMap(
  data = example_US_countyCovid,
  parameter = "deaths",
  state_SFDF = USCensusStates_02,
  county_SFDF = USCensusCounties_02,
  breaks = c(0, 1, 50, 100, 250, 500, 1000, 2500, 3000),
  palette = "brewer.or_rd",
  stateCode = c( "NY", "PA", "MD", "NJ", "DE"),
  stateBorderColor = "black",
  countyBorderColor = 'grey70'
) +
  tmap::tm_layout(
    attr.color = 'white',
    bg.color = "dodgerblue4"
  ) +
  tmap::tm_title(
    text = "COVID-19 Deaths* in the Mid Atlantic",
    size = 2.0,
    color = "white",
  ) +
  tmap::tm_credits("*as of June 01, 2020", col = "white", position = "left")

---

Example county Covid dataset

Description

The example_US_countyCovid dataset provides a small county dataset to use in code examples. The code for creating it demonstrates creation of a dataest that is compatible with countyMap().

This dataset was generated on 2020-06-12 by running:

library(dplyr)
library(MazamaSpatialUtils)

fileUrl <- "https://raw.githubusercontent.com/nytimes/covid-19-data/master/us-counties.csv"

col_names <- c("date", "countyName", "stateName", "countyFIPS", "cases", "deaths")
col_types = "Dcccii"

outputColumns <- c("stateCode", "stateName", "countyFIPS", "countyName", "cases", "deaths")

# After a little trial and error, the following works well:

example_US_countyCovid <-
  readr::read_csv(
    file = fileUrl,
    skip = 1,                    # Skip the header line
    col_names = col_names,
    col_types = col_types
  ) %>%
  dplyr::mutate(
    stateCode = MazamaSpatialUtils::US_stateNameToCode(stateName),
  ) %>%
  dplyr::filter(.data$date == lubridate::ymd("2020-06-01")) %>%
  dplyr::select(!!outputColumns)

save(example_US_countyCovid, file = "data/example_US_countyCovid.rda")

Usage

example_US_countyCovid

Format

A tibble with 52 rows and 3 columns of data.

---

Example state obesity dataset

Description

The example_US_stateObesity dataset provides a small state dataset to use in code examples. The code for creating it demonstrates creation of a dataest that is compatible with stateMap().

This dataset was generated on 2020-06-09 by running:

library(dplyr)
library(MazamaSpatialUtils)

fileUrl <- paste0("http://data-lakecountyil.opendata.arcgis.com/datasets/",
                  "3e0c1eb04e5c48b3be9040b0589d3ccf_8.csv")

col_names <- c("FID", "stateName", "obesityRate", "SHAPE_Length", "SHAPE_Area")
col_types = "icddd"

outputColumns <- c("stateCode", "stateName", "obesityRate")

# After a little trial and error, the following works well:

example_US_stateObesity <-
  readr::read_csv(
    file = fileUrl,
    skip = 1,                    # Skip the header line
    col_names = col_names,
    col_types = col_types
  ) %>%
  dplyr::mutate(
    stateCode = MazamaSpatialUtils::US_stateNameToCode(stateName)
  ) %>%
  dplyr::select(!!outputColumns)

save(example_US_stateObesity, file = "data/example_US_stateObesity.rda")

Usage

example_US_stateObesity

Format

A tibble with 52 rows and 3 columns of data.

---

Initialize with MazamaScience standard directories

Description

Convenience function to initialize spatial data for US state and county maps. Wraps the following setup lines:

MazamaSpatialUtils::setSpatialDataDir(spatialDataDir)

MazamaSpatialUtils::loadSpatialData("USCensusCounties_02")
MazamaSpatialUtils::loadSpatialData("USCensusStates_02")

Usage

mazama_initialize(spatialDataDir = "~/Data/Spatial")

Arguments

spatialDataDir

Directory where spatial datasets are found, Default: "~/Data/Spatial"

Value

No return value.

Examples

library(MazamaSpatialPlots)

# Set up directory for spatial data
spatialDataDir <- tempdir() # typically "~/Data/Spatial"
MazamaSpatialUtils::setSpatialDataDir(spatialDataDir)

exists("USCensusStates_02")
mazama_initialize(spatialDataDir)
exists("USCensusStates_02")
class(USCensusStates_02)

---

State level thematic map

Description

Uses the tmap package to generate a thematic map at the state level. Input consists of a dataframe with stateCode identifiers.

Data to plot is specified with parameter argument. If parameter is mult-valued, mutliple plots will be generated and displayed as "facets".

The returned object is a tmap ggplot object which can be further modified with tmap or ggplot options.

Usage

stateMap(
  data = NULL,
  parameter = NULL,
  state_SFDF = "USCensusStates_02",
  breaks = NULL,
  palette = "brewer.blues",
  conusOnly = TRUE,
  stateCode = NULL,
  projection = NULL,
  stateBorderColor = "gray50",
  title = NULL,
  showLegend = TRUE,
  legendTitle = NULL,
  legendOrientation = "portrait",
  legendPosition = NULL
)

Arguments

data	Dataframe containing values to plot. This dataframe must contain a column named stateCode with the 2-character state code.
parameter	Name of the column in data to use for coloring the map.
state_SFDF	simple features data frame with US states. It's data @slot must contain a column named stateCode with the 2-character state code.
breaks	Numeric vector of break points.
palette	A vector of colors or palette name from the cols4all package (see cols4all::c4a).
conusOnly	Logical specifying Continental US state codes. Ignored when the stateCode argument is specified.
stateCode	Vector of state codes to include on the map.
projection	Named projection, e.g. "EPSG:4326" or "WGS84" or proj4string.
stateBorderColor	Color used for state borders.
title	Vector of text strings to use as individual plot titles. This must be the same length as 'parameter'.
showLegend	Logical specifying whether or not to show the legend.
legendTitle	Text string to use as the legend title.
legendOrientation	Orientation of the legend. Either "portrait" or "landscape".
legendPosition	A tm_pos object generated with tmap::tm_pos_in() or tmap::tm_pos_out().

Value

A ggplot object.

Examples

library(MazamaSpatialPlots)

stateMap(
  data = example_US_stateObesity,
  parameter = "obesityRate",
  stateBorderColor = "white",
  title = "2018 Obesity by State"
)

# Example of customization using tm_layout and breaks parameter
stateMap(
  data = example_US_stateObesity,
  parameter = "obesityRate",
  breaks = seq(20,38,3),
  stateBorderColor = 'black'
) +
  tmap::tm_layout(
    frame = TRUE,
    frame.double.line = TRUE,
    bg.color = "grey85",
    inner.margins  = .05
  ) +
  tmap::tm_title(
    text = 'Obesity Rate by State',
    size = 1.5,
    position = tmap::tm_pos_in("center", "top"),
    fontfamily = "serif"
  )

# Example using stateCode
stateMap(
  data = example_US_stateObesity,
  parameter = "obesityRate",
  stateCode = c('ME', 'NH', 'VT', 'MA', 'RI', 'CT'),
  stateBorderColor = 'black',
  legendPosition = tmap::tm_pos_in("right", "bottom")
) +
  tmap::tm_layout(
    frame = TRUE,
    frame.double.line = TRUE,
    bg.color = "grey85",
    inner.margins  = .08
  ) +
  tmap::tm_title(
    text = 'Obesity Rates in New England',
    size = 1.5,
    fontface = 2,
    fontfamily = "serif",
    position = tmap::tm_pos_in("center", "top")
  )

---

US Census Counties simple features data frame

Description

The USCensusCounties_02 dataset provides a SFDF of US counties to use in code examples. It is created from converting a US county borders shapefile to a simple features data frame with additional columns of data. The code for creating it demonstrates creation of a SFDF that is compatible with countyMap(). See the MazamaSpatialUtils package for the function convertUSCensusCounties() that creates this SFDF.

This dataset was generated on 2022-11-07 by running:

library(MazamaSpatialUtils)

setSpatialDataDir("~/Data/Spatial_0.8")

MazamaSpatialUtils::convertUSCensusCounties()

MazamaSpatialUtils::loadSpatialData("USCensusCounties_02")

save(USCensusCounties_02, file = "data/USCensusCounties_02.rda")

Usage

USCensusCounties_02

Format

A simple features data frame (SFDF) with 3169 observations and 9 variables.

---

US Census State simple features data frame

Description

The USCensusStates_02 dataset provides a SFDF of US states to use in code examples. It is created by converting a US state borders shapefile to a simple features data frame with additional columns of data. The code for creating it demonstrates creation of a SFDF that is compatible with stateMap(). See the MazamaSpatialUtils package for the function convertUSCensusStates() that creates this SFDF.

This dataset was generated on 2022-11-007 by running:

library(MazamaSpatialUtils)

setSpatialDataDir("~/Data/Spatial_0.8")

MazamaSpatialUtils::convertUSCensusStates()

MazamaSpatialUtils::loadSpatialData("USCensusStates_02")

save(USCensusStates_02, file = "data/USCensusStates_02.rda")

Usage

USCensusStates_02

Format

A simple features data frame (SFDF) with 52 observations and 8 variables.

---

Validate proper setup of MazamaSpatialUtils

Description

The MazamaSpatialUtils package mus be properly installed and initialized before using functions from the MazamaSpatialPlots package.

This helper function is useful when building automated plot-generation systems.

Usage

validateMazamaSpatialUtils()

Value

Invisibly returns TRUE if no error message has been generated.

---