# 2. Mapping the US

#### Paolo Di Lorenzo

#### 2025-08-28

## 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_2022", color = "red") +
      scale_fill_continuous(name = "Population (2022)", 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_2022", color = "red") +
      scale_fill_continuous(
        low = "white", high = "red", name = "Population (2022)", 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_2022", include = c("CA", "ID", "NV", "OR", "WA"), color = "red"
      ) +
      scale_fill_continuous(
        low = "white", high = "red", name = "Population (2022)", 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).

    usmap::us_map()
    #> Simple feature collection with 52 features and 3 fields
    #> Geometry type: MULTIPOLYGON
    #> Dimension:     XY
    #> Bounding box:  xmin: -2584074 ymin: -2602555 xmax: 2516258 ymax: 731628.1
    #> Projected CRS: NAD27 / US National Atlas Equal Area
    #> First 10 features:
    #>    fips abbr                 full                           geom
    #> 1    02   AK               Alaska MULTIPOLYGON (((-2390688 -2...
    #> 2    01   AL              Alabama MULTIPOLYGON (((1091785 -13...
    #> 3    05   AR             Arkansas MULTIPOLYGON (((482022.2 -9...
    #> 4    04   AZ              Arizona MULTIPOLYGON (((-1386064 -1...
    #> 5    06   CA           California MULTIPOLYGON (((-1716581 -1...
    #> 6    08   CO             Colorado MULTIPOLYGON (((-787705.6 -...
    #> 7    09   CT          Connecticut MULTIPOLYGON (((2156162 -83...
    #> 8    11   DC District of Columbia MULTIPOLYGON (((1950799 -40...
    #> 9    10   DE             Delaware MULTIPOLYGON (((2037480 -28...
    #> 10   12   FL              Florida MULTIPOLYGON (((1853163 -20...

    usmap::us_map(regions = "counties")
    #> Simple feature collection with 3222 features and 4 fields
    #> Geometry type: MULTIPOLYGON
    #> Dimension:     XY
    #> Bounding box:  xmin: -2584074 ymin: -2602555 xmax: 2516258 ymax: 731628.1
    #> Projected CRS: NAD27 / US National Atlas Equal Area
    #> First 10 features:
    #>     fips abbr   full                       county
    #> 1  02013   AK Alaska       Aleutians East Borough
    #> 2  02016   AK Alaska   Aleutians West Census Area
    #> 3  02020   AK Alaska       Anchorage Municipality
    #> 4  02050   AK Alaska           Bethel Census Area
    #> 5  02060   AK Alaska          Bristol Bay Borough
    #> 6  02063   AK Alaska          Chugach Census Area
    #> 7  02066   AK Alaska     Copper River Census Area
    #> 8  02068   AK Alaska               Denali Borough
    #> 9  02070   AK Alaska       Dillingham Census Area
    #> 10 02090   AK Alaska Fairbanks North Star Borough
    #>                              geom
    #> 1  MULTIPOLYGON (((-1757988 -2...
    #> 2  MULTIPOLYGON (((-2390688 -2...
    #> 3  MULTIPOLYGON (((-1513326 -2...
    #> 4  MULTIPOLYGON (((-1899724 -2...
    #> 5  MULTIPOLYGON (((-1681144 -2...
    #> 6  MULTIPOLYGON (((-1472549 -2...
    #> 7  MULTIPOLYGON (((-1452955 -2...
    #> 8  MULTIPOLYGON (((-1581283 -1...
    #> 9  MULTIPOLYGON (((-1788018 -2...
    #> 10 MULTIPOLYGON (((-1508063 -1...

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