Cleanup documentation (#83)

* Added `README.Rmd` to generate `README.md`
  * Allows for R code to directly generate images used in readme.
  * Can serve as another visual test when changes are made to `usmap`.
* Added more interesting plots and examples to readme.
* Added `abbr` state abbreviation column to `citypop` data set.
* Removed `resources` folder.
  * No longer needed as readme images are now stored in `man/figures`.
* Standardized package and function documentation (links, formatting,
language, etc).
* Renamed vignettes.

.Rbuildignore

@@ -15,3 +15,4 @@
 ^LICENSE\.md$
 ^\.lintr$
 ^CRAN-SUBMISSION$
+^README\.Rmd$

NEWS.md

@@ -16,6 +16,10 @@
 * Add `usrivers` dataset featuring major US rivers.
   * The dataset is provided in an `sf` object and is ready to be transformed with `usmap_transform()` and plotted with `plot_usmap() + ggplot2::geom_sf()`.
 * Add visual snapshot tests for more resilient plots, see [Issue #80](https://github.com/pdil/usmap/issues/80).
+* 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.

R/data.R

@@ -1,7 +1,7 @@
 #' Population estimates (2015), county level
 #'
 #' @description US census population estimates by county for 2015. \cr\cr
-#'   The data is formatted for easy merging with output from [usmap::us_map].
+#'   The data is formatted for easy merging with output from [usmap::us_map()].
 #'
 #' @usage data(countypop)
 #'
@@ -28,7 +28,7 @@
 #' Population estimates (2015), state level
 #'
 #' @description US census population estimates by state for 2015. \cr\cr
-#'   The data is formatted for easy merging with output from [usmap::us_map].
+#'   The data is formatted for easy merging with output from [usmap::us_map()].
 #'
 #' @usage data(statepop)
 #'
@@ -55,7 +55,7 @@
 #' Poverty percentage estimates (2014), county level
 #'
 #' @description US census poverty percentage estimates by county for 2014. \cr\cr
-#'   The data is formatted for easy merging with output from [usmap::us_map].
+#'   The data is formatted for easy merging with output from [usmap::us_map()].
 #'
 #' @usage data(countypov)
 #'
@@ -82,7 +82,7 @@
 #' Poverty percentage estimates (2014), state level
 #'
 #' @description US census poverty percentage estimates by state for 2014. \cr\cr
-#'   The data is formatted for easy merging with output from [usmap::us_map].
+#'   The data is formatted for easy merging with output from [usmap::us_map()].
 #'
 #' @usage data(statepov)
 #'
@@ -109,9 +109,9 @@
 #' Most populous city in each state (2010)
 #'
 #' @description The most populous city in each US state, as of the 2010 US Census.\cr\cr
-#'   The data is formatted for transforming with [usmap::usmap_transform].
+#'   The data is formatted for transforming with [usmap::usmap_transform()].
 #'   Once the longitude and latitude is transformed, it can be added to
-#'   [usmap::plot_usmap] using [ggplot2::ggplot] layers.
+#'   [usmap::plot_usmap()] using [ggplot2::ggplot()] layers.
 #'
 #' @usage data(citypop)
 #'
@@ -120,6 +120,7 @@
 #'   \item \code{lon} The longitude of the most populous city.
 #'   \item \code{lat} The latitude of the most populous city.
 #'   \item \code{state} The name of the state containing the city.
+#'   \item \code{abbr} The abbreviation of the state containing the city.
 #'   \item \code{most_populous_city} The name of the city.
 #'   \item \code{city_pop} The population of the city.
 #' }
@@ -138,9 +139,9 @@
 #'
 #' @description US earthquakes with a magnitude of 2.5 or greater, occurring in the
 #'   first half of 2019, from January 1st to June 30th, from USGS.\cr\cr
-#'   The data is formatted for transforming with [usmap::usmap_transform].
+#'   The data is formatted for transforming with [usmap::usmap_transform()].
 #'   Once the longitude and latitude is transformed, it can be added to
-#'   [usmap::plot_usmap] using [ggplot2::ggplot] layers.
+#'   [usmap::plot_usmap()] using [ggplot2::ggplot()] layers.
 #'
 #' @usage data(earthquakes)
 #'
@@ -165,9 +166,9 @@
 #' US Major Rivers (2010)
 #'
 #' @description Major rivers in the United States.\cr\cr
-#'   The data is can be transformed with [usmap::usmap_transform].
+#'   The data is can be transformed with [usmap::usmap_transform()].
 #'   Once the `Shape` strings are transformed, it can be added to
-#'   [plot_usmap] using a [ggplot2::geom_sf] layer.
+#'   [plot_usmap()] using a [ggplot2::geom_sf()] layer.
 #'
 #' @usage data(usrivers)
 #'

R/fips.R

@@ -38,6 +38,8 @@
 #' codes is returned, sorted by the state's abbreviation (e.g. Alaska (AK) comes
 #' before Alabama (AL)).
 #'
+#' @seealso [fips_info()]
+#'
 #' @examples
 #' fips()
 #'
@@ -119,6 +121,8 @@ fips <- function(state, county = c()) {
 #'  If `fips` is omitted, the data frame containing all available states is
 #'  returned.
 #'
+#' @seealso [fips()]
+#'
 #' @examples
 #' fips_info(2)
 #' fips_info("2")
@@ -166,7 +170,7 @@ fips_info.character <- function(fips, sortAndRemoveDuplicates = FALSE) {
 }
 
 #' Gets FIPS info for either states or counties depending on input.
-#' Helper function for S3 method \code{fips_info}.
+#' Helper function for S3 method [fips_info()].
 #' @keywords internal
 get_fips_info <- function(fips, sortAndRemoveDuplicates) {
   if (all(nchar(fips) == 2)) {
@@ -196,9 +200,11 @@ get_fips_info <- function(fips, sortAndRemoveDuplicates) {
   result[, columns]
 }
 
-#' Performs merge while maintaining original sort order.
+#' Merge while maintaining original sort order
+#'
+#' Internal function used by [fips_info()].
 #'
-#' @seealso https://stackoverflow.com/a/61560405/7264964
+#' @seealso \url{https://stackoverflow.com/a/61560405/7264964}
 #' @keywords internal
 static_merge <- function(x, y, ...) {
   x$join_id_ <- seq_len(nrow(x))

R/join-data.R

@@ -14,11 +14,12 @@
 #'   a value in \code{data}. This value must be of the same type as the \code{value}
 #'   column of \code{data}.
 #'
-#' @return A data frame composed of the map data frame (from \code{\link{us_map}}) except
+#' @return A data frame composed of the map data frame (from [us_map()]) except
 #'   an extra column containing the values in \code{data} is included.
 #'
-#'   The result can be plotted using \code{ggplot2}. See \code{\link{us_map}} or
-#'   \code{\link{plot_usmap}} for more details.
+#'   The result can be plotted using [ggplot2::ggplot()] or [plot_usmap()].
+#'
+#' @seealso [plot_usmap()]
 #'
 #' @examples
 #' state_data <- data.frame(fips = c("01", "02", "04"), values = c(1, 5, 8))

R/plot-map.R

@@ -3,7 +3,7 @@
 #' @inheritParams us_map
 #' @param data A data frame containing values to plot on the map. This
 #'   parameter should be a data frame consisting of two columns,
-#'   a fips code (2 characters for state, 5 characters for county)
+#'   a FIPS code (2 characters for state, 5 characters for county)
 #'   and the value that should be associated with that region. The
 #'   columns of \code{data} \emph{must} be \code{fips} or \code{state} and
 #'   the value of the `values` parameter.
@@ -12,26 +12,25 @@
 #' @param theme The theme that should be used for plotting the map. The default
 #'   is \code{theme_map} from \href{https://github.com/jrnold/ggthemes}{ggthemes}.
 #' @param labels Whether or not to display labels on the map. Labels are not displayed
-#'   by default. For now, labels only work for state maps.
-#'   County labels may be added in the future.
+#'   by default.
 #' @param label_color The color of the labels to display. Corresponds to the \code{color}
-#'   option in the \code{\link[ggplot2]{aes}} mapping. The default is \code{"black"}.
+#'   option in the [ggplot2::aes()] mapping. The default is \code{"black"}.
 #'   \href{https://usmap.dev/docs/Rcolor.pdf}{Click here}
 #'   for more color options.
-#' @param ... Other arguments to pass to \code{ggplot2::aes()}. These are
+#' @param ... Other arguments to pass to [ggplot2::aes()]. These are
 #'   often aesthetics, used to set an aesthetic to a fixed value, like \code{color = "red"}
 #'   or \code{size = 3}. They affect the appearance of the polygons used to render
 #'   the map (for example fill color, line color, line thickness, etc.). If any of
 #'   \code{color}/\code{colour}, \code{fill}, or \code{size} are not specified they
 #'   are set to their default values of \code{color="black"}, \code{fill="white"},
 #'   and \code{size=0.4}.
 #'
-#' @return A \code{\link[ggplot2]{ggplot}} object that contains a basic
+#' @return A [ggplot2::ggplot] object that contains a basic
 #'   US map with the described parameters. Since the result is a \code{ggplot}
-#'   object, it can be extended with more \code{geom} layers, scales, labels,
+#'   object, it can be extended with more [ggplot2::Geom] layers, scales, labels,
 #'   themes, etc.
 #'
-#' @seealso \code{\link{usmap}}, \code{\link[ggplot2]{theme}}
+#' @seealso [usmap], [ggplot2::theme()]
 #'
 #' @examples
 #' plot_usmap()
@@ -152,16 +151,13 @@ plot_usmap <- function(regions = c("states", "state", "counties", "county"),
 #' Convenient theme map
 #'
 #' @description
-#' This creates a nice map theme for use in [plot_usmap].
-#' It is borrowed from the `ggthemes` package located at this repository:
-#'   https://github.com/jrnold/ggthemes.
+#' This creates a nice map theme for use in [plot_usmap()].
+#' It originated from the `ggthemes` package located at this repository:
+#'   \url{https://github.com/jrnold/ggthemes}.
 #'
 #' This function was manually rewritten here to avoid the need for
 #'  another package import.
 #'
-#' All theme functions (i.e. `theme_bw`, `theme`, `element_blank`, `%+replace%`)
-#'  come from `ggplot2`.
-#'
 #' @keywords internal
 theme_map <- function(base_size = 9, base_family = "") {
   element_blank <- ggplot2::element_blank()

R/regions.R

@@ -1,4 +1,3 @@
-
 #' New England census division
 #'
 #' @description

R/usmap.R

@@ -3,13 +3,13 @@
 #' @description
 #' It is usually difficult or inconvenient to create US maps that
 #'   include both Alaska and Hawaii in a convenient spot. All map
-#'   data frames produced by this package use the Albers Equal Area
+#'   data presented in this package uses the US National Atlas Equal Area
 #'   projection.
 #'
-#' @section Map data frames:
+#' @section Map data:
 #' Alaska and Hawaii have been manually moved to a new location so that
 #' their new coordinates place them to the bottom-left corner of
-#' the map. These maps can be accessed by using the [us_map] function.
+#' the map. These maps can be accessed by using the [us_map()] function.
 #'
 #' The function provides the ability to retrieve maps with either
 #' state borders or county borders using the \code{regions} parameter
@@ -29,12 +29,18 @@
 #' preparing data to be merged with the map data frame.
 #'
 #' @section Plot US map data:
-#' A convenience function [plot_usmap] has been included which
-#' takes similar parameters to [us_map] and returns a [ggplot2::ggplot2]
+#' A convenience function [plot_usmap()] has been included which
+#' takes similar parameters to [us_map()] and returns a [ggplot2::ggplot2]
 #' object. Since the output is a \code{ggplot} object, other layers can be
 #' added such as scales, themes, and labels. Including data in the function call
 #' will color the map according to the values in the data, creating a choropleth.
 #'
+#' @section Transforming data:
+#' It is also possible to add spatial data to the map, in the form of either
+#' data frames or simple features ([sf::sf]) objects. If necessary, the
+#' data can be transformed to be in the same coordinate reference system as
+#' [usmap] by using [usmap_transform()] and then plotted using [ggplot2::geom_sf()].
+#'
 #' @author Paolo Di Lorenzo \cr
 #' \itemize{
 #'   \item Email: \email{dilorenzo@@hey}
@@ -50,9 +56,10 @@
 #'   \item US Census Shapefiles \cr
 #'     \url{https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.html}
 #'   \item Map Features \cr
-#'     \url{https://en.wikipedia.org/wiki/Map_projection}
-#'     \url{https://en.wikipedia.org/wiki/Albers_projection}
-#'     \url{https://en.wikipedia.org/wiki/Choropleth}
+#'     \url{https://en.wikipedia.org/wiki/Map_projection} \cr
+#'     \url{https://en.wikipedia.org/wiki/Equal-area_projection} \cr
+#'     \url{https://en.wikipedia.org/wiki/Choropleth} \cr
+#'     \url{https://epsg.io/9311} (US National Atlas Equal Area)
 #' }
 #'
 #' @references