# 3. Advanced Mapping

#### Paolo Di Lorenzo

#### 2025-08-28

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", linewidth = 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:

- `fill`: fill color of the state/county polygons
- `alpha`: transparency of the state/county polygon fill colors
- `color`/`colour`: line color of the state/county polygons
- `linewidth`: thickness of the state/county polygon lines

## 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()
    #> Coordinate Reference System:
    #>   User input: EPSG:9311
    #>   wkt:
    #> PROJCRS["NAD27 / US National Atlas Equal Area",
    #>     BASEGEOGCRS["NAD27",
    #>         DATUM["North American Datum 1927",
    #>             ELLIPSOID["Clarke 1866",6378206.4,294.978698213898,
    #>                 LENGTHUNIT["metre",1]]],
    #>         PRIMEM["Greenwich",0,
    #>             ANGLEUNIT["degree",0.0174532925199433]],
    #>         ID["EPSG",4267]],
    #>     CONVERSION["US National Atlas Equal Area",
    #>         METHOD["Lambert Azimuthal Equal Area (Spherical)",
    #>             ID["EPSG",1027]],
    #>         PARAMETER["Latitude of natural origin",45,
    #>             ANGLEUNIT["degree",0.0174532925199433],
    #>             ID["EPSG",8801]],
    #>         PARAMETER["Longitude of natural origin",-100,
    #>             ANGLEUNIT["degree",0.0174532925199433],
    #>             ID["EPSG",8802]],
    #>         PARAMETER["False easting",0,
    #>             LENGTHUNIT["metre",1],
    #>             ID["EPSG",8806]],
    #>         PARAMETER["False northing",0,
    #>             LENGTHUNIT["metre",1],
    #>             ID["EPSG",8807]]],
    #>     CS[Cartesian,2],
    #>         AXIS["easting (X)",east,
    #>             ORDER[1],
    #>             LENGTHUNIT["metre",1]],
    #>         AXIS["northing (Y)",north,
    #>             ORDER[2],
    #>             LENGTHUNIT["metre",1]],
    #>     USAGE[
    #>         SCOPE["Statistical analysis."],
    #>         AREA["United States (USA) - onshore and offshore."],
    #>         BBOX[15.56,167.65,74.71,-65.69]],
    #>     ID["EPSG",9311]]

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

#### Example: earthquakes

Here is an example using the provided `earthquakes` dataset:

    library(usmap)
    library(ggplot2)

    eq_transformed <- usmap_transform(earthquakes)

    plot_usmap() +
      geom_sf(data = eq_transformed, aes(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` data set:

    library(usmap)
    library(ggplot2)

    cities_t <- usmap_transform(citypop)

    plot_usmap(fill = "yellow", alpha = 0.25) +
      geom_sf(data = cities_t,
              aes(size = city_pop),
              color = "purple", alpha = 0.5) +
      ggrepel::geom_label_repel(data = cities_t,
                                aes(label = most_populous_city, geometry = geometry),
                                size = 3, alpha = 0.8,
                                label.r = unit(0.5, "lines"), label.size = 0.5,
                                segment.color = "red", segment.size = 1,
                                stat = "sf_coordinates", seed = 1002,
                                max.overlaps = 20) +
      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")

#### Example: major rivers in the United States

Here is an example of transforming and plotting another `sf` object on the map, using the provided `rivers` dataset. In this example the width of the river corresponds to its length, and the color indicates the river system it belongs to.

    library(usmap)
    library(ggplot2)

    rivers_t <- usmap_transform(usrivers)

    plot_usmap("counties", color = "gray80") +
      geom_sf(data = rivers_t, aes(linewidth = Shape_Length, color = SYSTEM, fill = SYSTEM)) +
      scale_linewidth_continuous(range = c(0.3, 1.8), guide = "none") +
      scale_color_discrete(guide = "none") +
      labs(title = "Major Rivers in the United States",
           subtitle = "Source: ESRI 2010",
           fill = "River System") +
      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.