updated readme

.Rbuildignore

@@ -2,3 +2,4 @@
 ^\.Rproj\.user$
 ^data-raw$
 ^LICENSE\.md$
+^\.github$

.github/.gitignore

@@ -0,0 +1 @@
+*.html

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,49 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+name: R-CMD-check
+
+jobs:
+  R-CMD-check:
+    runs-on: ${{ matrix.config.os }}
+
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {os: macos-latest,   r: 'release'}
+          - {os: windows-latest, r: 'release'}
+          - {os: ubuntu-latest,   r: 'devel', http-user-agent: 'release'}
+          - {os: ubuntu-latest,   r: 'release'}
+          - {os: ubuntu-latest,   r: 'oldrel-1'}
+
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: ${{ matrix.config.r }}
+          http-user-agent: ${{ matrix.config.http-user-agent }}
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          upload-snapshots: true

R/coef_rqs.R

@@ -6,7 +6,7 @@
 #'    This makes it easy to make plots with confidence intervals for each coefficient.
 #'
 #' @param rqs A `rq` or `rqs` object from `{quantreg}`.
-#' @inheritDotParams quantreg::summary.rq
+#' @param ... Arguments passed on to [quantreg::summary.rq()]
 #'
 #' @import quantreg
 #' @importFrom dplyr mutate bind_rows
@@ -17,6 +17,7 @@
 #'
 #' @returns A `tibble`
 #'
+#' @seealso [quantreg::rq()]
 
 coef_rqs <- function(rqs, ...) {
   summary <- summary(rqs, ...)
@@ -26,9 +27,8 @@ coef_rqs <- function(rqs, ...) {
       \(x)
       x$coefficients %>%
         t() %>%
-        as_tibble() %>%
+        as_tibble(rownames = "value") %>%
         mutate(
-          value = c("coef", "lower_bound", "upper_bound"),
           quant = x$tau
         )
     ) %>%

R/dist_nearest.R

@@ -1,20 +1,33 @@
 #' Distance to the nearest feature
+#'
+#' @description
+#' For each spatial object in x, calculate the distance to the nearest feature in y.
+#'
 #' @param x A `sf` object to calculate distances from.
 #' @param y A `sf` object to retrieve the closest one to each observation in `x`
-#' @param name description An optional argument to set the new column's name, otherwise it is set to "distance".
-#' @param id_feature Specifies if an additional column with `y`'s row id should be inserted. Defaults to FALSE.
+#' @param name An optional argument to set the new column's name, otherwise it is set to "distance".
+#' @param id_feature Specifies if an additional column with `y`'s row id should be inserted. Defaults to `FALSE.`
 #' @param geometry Specifies the name of the geometry column, if different from the default, to reorder variables.
+#' @param drop_units Should units be included? Default: `FALSE`
+#'
 #' @importFrom sf st_nearest_feature st_as_sf st_transform st_crs
 #' @importFrom tibble tibble rowid_to_column
 #' @importFrom dplyr left_join mutate bind_cols
 #' @importFrom units drop_units
+#'
 #' @export
-#' @returns Original `x` with an additional column containing the distance to the closest  `y` feature.
+#'
 #' @details
-#' For each spatial object in x, calculate the distance to the nearest feature in y.
+#' `dist_nearest` First finds the closest feature in `y` to each feature in `x`, calculating then
+#'    pairwise distances faster than e.g. using a for loop and then minimizing distances or
+#'    calculating distance matrices.
+#'
+#' @returns Original `x` with an additional column containing the distance to the closest  `y` feature.
+#'
 #' @example inst/examples/dist_nearest.R
 
-dist_nearest <- function(x, y, name, id_feature = F, geometry = geometry) {
+dist_nearest <- function(x, y, name, id_feature = F, geometry = geometry, drop_units = T) {
+
   closest <- st_nearest_feature(x, y) %>%
     tibble(id_closest = `.`)
 
@@ -25,20 +38,19 @@ dist_nearest <- function(x, y, name, id_feature = F, geometry = geometry) {
 
   if(missing(name)) {
     x <- x %>%
-      mutate(distance = st_distance(distance, ., by_element = TRUE), .before = geometry) %>%
-      drop_units()
+      mutate(distance = st_distance(distance, ., by_element = TRUE), .before = geometry)
   } else {
     x <- x %>%
-      mutate({{name}} := st_distance(distance, ., by_element = TRUE), .before = geometry) %>%
-      drop_units()
+      mutate({{name}} := st_distance(distance, ., by_element = TRUE), .before = geometry)
   }
 
-  if(id_feature == F) {
-    return(x)
-  } else {
-    x <- x %>%
-      bind_cols(closest)
+  if(drop_units) {
+    x <- x %>% drop_units()
+  }
 
-    return(x)
+  if(id_feature) {
+    x <- x %>% bind_cols(closest)
   }
+
+  return(x)
 }

R/geom_sf_rais.R

@@ -1,11 +1,18 @@
-#' RAIS thematic maps using ggplot
-#' @param x A `data.frame` to plot or an object convertible to it.
+#' RAIS maps using ggplot
+#'
+#' @description
+#' An easy way to make maps with data from the Brazilian employer-employee dataset. This function
+#'    requires an already spatialized dataset
+#'
+#' @param x Plot variable.
 #' @param scale_theme Palette theme to be used in the plots, currently "distiller" and "viridis" are supported
 #' @param palette Optional palette specification. For absolute values, defaults to "YlGnBu" when
 #' `scale_theme` = "distiller" or "D" if `scale_theme` = "viridis". For relative values, defaults to "RdBu".
 #' @param direction Palette's direction, defaults to 1.
 #' @param data_format Specify if data is in absolute (default) or relative format.
 #' @param data_level Specify if data represents a point value or growth between two periods.
+#' @param data An object with classes `sf` and `data.frame` (or convertible to it, see
+#'    [ggplot2::fortify()]). Optional; will inherit data from previous layers if provided.
 #' @param auto.labels When `TRUE`, automatically generates title, subtitle, and caption based on `geo_name`,
 #' `geo_level`, and `var_name`. If `FALSE`, specify `title`, `subtitle`, and `caption`.
 #' @param geo_name Name of the geographic area being represented.
@@ -17,9 +24,58 @@
 #' @param faceted Defaults to `FALSE`, change to `TRUE` to use a faceted plot.
 #' @param facet_var A variable to be passed into `ggplot2::vars()` when faceting.
 #' @param faceted_labs Labels for the faceted subplots.
+#'
 #' @import ggplot2
+#'
 #' @export
+#'
 #' @returns A `ggplot` object
+#'
+#' @examples
+#' \dontrun{
+#' # 1 one year
+#'
+#' data("fortaleza")
+#' data("rais_fortaleza")
+#'
+#' ## get geometry data into dataframe
+#' rais_fortaleza <- rais_fortaleza %>%
+#'   left_join(fortaleza) %>%
+#'   sf::st_as_sf() %>%
+#'   filter(year == 2019)
+#'
+#' ## 1.1 inheriting data from ggplot()
+#' rais_fortaleza %>%
+#'   ggplot() +
+#'   geom_sf_rais(n_jobs, var_name = "Jobs", geo_name = "Fortaleza", geo_level = "neighborhood") +
+#'   theme_void()
+#'
+#' ## 1.2 passing data explicitly
+#' ggplot() +
+#'   geom_sf_rais(n_jobs, var_name = "Jobs", geo_name = "Fortaleza", geo_level = "neighborhood",
+#'                data = rais_fortaleza) +
+#'   theme_void()
+#' }
+#'
+#' \dontrun{
+#' # 2 two years (faceted)
+#'
+#' data("fortaleza")
+#' data("rais_fortaleza")
+#'
+#' ## get geometry data into dataframe
+#' rais_fortaleza <- rais_fortaleza %>%
+#'   left_join(fortaleza) %>%
+#'   sf::st_as_sf()
+#'
+#' ## plot
+#' ggplot() +
+#'   geom_sf(data = fortaleza, color = NA) +
+#'   geom_sf_rais(n_jobs, var_name = "Jobs", geo_name = "Fortaleza", geo_level = "neighborhood",
+#'                data = rais_fortaleza,
+#'                faceted = T, facet_var = year) +
+#'   theme_void()
+#' }
 
 geom_sf_rais <- function(
     x,
@@ -28,6 +84,7 @@ geom_sf_rais <- function(
     direction = 1,
     data_format = c("absolute", "relative"),
     data_level = c("level", "growth"),
+    data = NULL,
     auto.labels = TRUE,
     geo_name = NULL, geo_level = NULL, var_name = NULL,
     title = NULL, subtitle = NULL, caption = NULL,
@@ -45,12 +102,13 @@ geom_sf_rais <- function(
     list(
       title = paste0(var_name, " in ", geo_name),
       subtitle = paste0(ifelse(data_format == "absolute", "Total", "Growth rate"),
-                        ifelse(is.null(geo_level), NULL, paste0(" per ", geo_level))),
+                        ifelse(is.null(geo_level), "", paste0(" per ", geo_level))),
       caption = "Note: excludes public administration.\nSource: RAIS/MTE (2023)"
     )
   } else {list(title = title, subtitle = subtitle, caption = caption)}
 
-  p <- list(geom_sf(aes(fill = {{x}}, color = {{x}})))
+  p <- ifelse(is.null(data), list(geom_sf(aes(fill = {{x}}, color = {{x}}))),
+              list(geom_sf(data = data, aes(fill = {{x}}, color = {{x}}))))
 
   if (data_level == "level") {
     scale_fill <- scale_fill_distiller

R/get_osm.R

@@ -1,14 +1,34 @@
-#' Download osm roads
+#' Download osm data
+#'
 #' @description
-#' A convenient wrapper for osm features to get roads easily convertible to `sf` format.
+#' A convenient wrapper for osm features to get some features I need easily convertible to `sf` format.
+#'
 #' @param bbox A bounding box for the search area.
+#'
 #' @import osmdata
-#' @export
+#'
 #' @returns A `list` for each kind of geometry retrieved by osmdata.
+#'
+#' @seealso [osmdata::add_osm_feature()]
+
+
+
+#' @rdname get_osm_
+#' @name get_osm_roads
+#' @export
+#'
 #' @details
 #' Returns values that meet `key` = "highway" and `value` = "motorway", "primary", "secondary",
 #' "tertiary", "residential", "living_street" and "pedestrian". For more info, please check
 #' ["Key:highway"](https://wiki.openstreetmap.org/wiki/Key:highway) page at OSM Wiki.
+#'
+#' @examples
+#' \dontrun{
+#' # Get roads in Brazil's smallest city
+#' geobr::read_municipality(code_muni = 3157336) %>%
+#' sf::st_bbox() %>%
+#' get_osm_roads()
+#' }
 
 get_osm_roads <- function(bbox) {
   query <- opq(bbox, timeout = 50) %>%
@@ -22,16 +42,22 @@ get_osm_roads <- function(bbox) {
 
 
 
-#' Download osm postcodes
-#' @description
-#' A convenient wrapper for osm features to get postcodes easily convertible to `sf` format
-#' @param bbox A bounding box for the search area.
-#' @import osmdata
+#' @rdname get_osm_
+#' @name get_osm_zips
 #' @export
-#' @returns A `list` for each kind of geometry retrieved by osmdata.
+#'
 #' @details
 #' Returns values that meet `key` = "addr:postcode". For more info, please check
 #' ["Key:railway"](https://wiki.openstreetmap.org/wiki/Key:railway) page at OSM Wiki.
+#'
+#' @examples
+#' \dontrun{
+#' # Get postcodes in Brazil's smallest city
+#' geobr::read_municipality(code_muni = 3157336) %>%
+#' sf::st_bbox() %>%
+#' get_osm_zips()
+#' }
+
 
 get_osm_zips <- function(bbox) {
   query <- opq(bbox, timeout = 50) %>%
@@ -45,19 +71,23 @@ get_osm_zips <- function(bbox) {
 
 
 
-#' Download osm rail transit
-#' @description
-#' A convenient wrapper for osm features to get (rail) transit lines and stations
-#' easily convertible to `sf` format
-#' @param bbox A bounding box for the search area.
-#' @import osmdata
+#' @rdname get_osm_
+#' @name get_osm_rail
 #' @export
-#' @returns Object with classes `list`, `osmdata`, and `osmdata_sf`
-#' for each kind of geometry retrieved by osmdata.
+#'
 #' @details
 #' Returns values that meet `key` = "railway" and `value` = "rail", "light_rail", "subway", "tram",
 #' "service", "construction", "usage", "station", and "tram_stop". For more info, please check
 #' ["Key:addr:*"](https://wiki.openstreetmap.org/wiki/Key:addr:*) page at OSM Wiki
+#'
+#' @examples
+#' \dontrun{
+#' # Get railways in Brazil's smallest city
+#' geobr::read_municipality(code_muni = 3157336) %>%
+#' sf::st_bbox() %>%
+#' get_osm_rail()
+#' }
+
 
 get_osm_rail <- function(bbox) {
   query <- opq(bbox, timeout = 50) %>%

R/get_rais.R

@@ -19,10 +19,14 @@
 #' https://basedosdados.org/dataset/3e7c4d58-96ba-448e-b053-d385a829ef00?table=c3a5121e-f00d-41ff-b46f-bd26be8d4af3.
 #' @examples
 #' \dontrun{
+#' # Getting RAIS data for Caete (MG)
+#'
+#' ## setting variables
 #' variables <- "ano, quantidade_vinculos_ativos, cnae_2, indicador_atividade_ano"
 #' source <- "`basedosdados.br_me_rais.microdados_estabelecimentos`"
 #' city <- "id_municipio='3110004'"
 #'
+#' ## download
 #' get_rais(
 #'   variables = variables,
 #'   source = source,