Merge pull request #5 from Fernandez-Lab-WSU/paula-review

General update in docs, vignettes and tests

R/apply_weekly_lag.R

@@ -1,22 +1,21 @@
-#' Apply a 7 day lag to the variable n_crisis
+#' Apply a 7 day lag to the variable `n_crisis`
 #'
 #' @description Applying a week lag to the data will create raster images
 #' showing the mobility a week before the date of interest.
-#' This function works only for quadkeys without NAs.
+#' This function works only for QuadKeys without NAs.
 #'
-#' @param data A dataset
+#' @param data A data.frame
 #'
 #' @importFrom rlang .data
 #'
-#' @return A dataframe with the extra columns n_crisis_lag_7 and
-#' percent_change_7.
+#' @return A data.frame with the extra columns `n_crisis_lag_7` and
+#' `percent_change_7`.
 #'
-#' n_crisis_lag_7, is the same variable defined as n_crisis in the Facebook
-#' dataset with a 7 day lag applied.
-#'
-#' percent_change_7 is the difference between the n_crisis value between weeks
-#' expressed as percentage.
+#' * `n_crisis_lag_7`, is the same variable defined as `n_crisis`
+#' in the Facebook mobility data.frame with a 7 day lag applied.
 #'
+#' * `percent_change_7` is the difference between 
+#' the `n_crisis` value between weeks expressed as percentage.
 #'
 #' @export
 #'
@@ -36,7 +35,6 @@
 #'                                                 percent_change = 'c')) 
 #'  
 #' apply_weekly_lag(files)
-#'
 apply_weekly_lag <- function(data) {
   out_data <- c()
 

R/create_qk_grid.R

@@ -14,9 +14,9 @@
 #'
 #' @importFrom rlang .data
 #'
-#' @return A list returning the QuadKeys as a dataframe (data),
-#' the number of rows (num_rows)
-#' and columns (num_cols) of the grid.
+#' @return A list returning the QuadKeys as a data.frame (`data`),
+#' the number of rows (`num_rows`)
+#' and columns (`num_cols`) of the grid.
 #'
 #' @export
 #'
@@ -89,11 +89,15 @@ create_qk_grid <- function(xmin, xmax, ymin, ymax, zoom) {
   }
 
   # define the dimensions of the matrix
-  num_rows <- abs(resy)
-  num_cols <- abs(resx)
+  num_tiles_rows <- abs(resy) 
+  num_tiles_cols <- abs(resx) 
 
   # create all the possible combinations of columns and rows
-  grid <- expand.grid(c = 0:num_cols, r = 0:num_rows)
+  # I start with 0 because I want the first tiles in `tilesmn$tileX`
+  # and `tilesmn$tileY` to be counted.
+  # This is equivalent to say that I want the bounding box 
+  # included inside the grid.
+  grid <- expand.grid(c = 0:num_tiles_cols, r = 0:num_tiles_rows)
 
   # calculate tileX and tileY for each combination
   data <- grid |>
@@ -114,7 +118,7 @@ create_qk_grid <- function(xmin, xmax, ymin, ymax, zoom) {
 
   return(list(
     data = data,
-    num_rows = num_rows,
-    num_cols = num_cols
+    num_rows = num_tiles_rows+1, #+1 as I was counting the zero
+    num_cols = num_tiles_cols+1
   ))
 }

R/create_stars_raster.R

@@ -1,22 +1,41 @@
-#' Create a stars raster
+#' Create a `stars` raster
 #'
 #' @description The use of a template enables the creation of an accurate
 #' raster, even in the presence of NAs.
 #'
-#' @param template A spatial dataset (sf) with the polygon grid used as template
+#' @param template A `sf` POLYGON data.frame to use as template.
+#' Check [stars::st_as_stars()] documentation for more details.
 #' @param nx Integer; number of cells in x direction.
 #' @param ny Integer; number of cells in y direction.
-#' @param data A spatial dataframe (sf) with the variable we want to represent
-#' in the raster.
+#' @param data A  `sf` POLYGON data.frame with the variable
+#' we want to represent in the raster.
 #' @param var The column name of the variable to plot.
 #'
 #' @seealso \code{\link{st_as_stars}}, \code{\link{st_rasterize}}
 #'
-#' @return A stars object
+#' @return A `stars` object.
 #' @export
 #'
 #' @examples
 #'
+#' # Basic workflow
+#'
+#' # read the file with the data
+#' path <- paste0(system.file("extdata", package = 'quadkeyr'),
+#'                "/cityA_2020_04_15_0000.csv")
+#' data <- read.csv(path)
+#' data <- format_fb_data(data)
+#'
+#' complete_polygon_grid <- add_regular_polygon_grid(data = data)
+#'
+#' stars_object <- create_stars_raster(data = complete_polygon_grid$data,
+#'                                     template = complete_polygon_grid$data,
+#'                                     var = "percent_change",
+#'                                     nx = complete_polygon_grid$num_cols,
+#'                                     ny = complete_polygon_grid$num_rows)
+#' stars_object
+#'
+#' # Other workflow
 #' grid <- create_qk_grid(
 #'   xmin = -59,
 #'   xmax = -57,
@@ -30,16 +49,15 @@
 #' polygrid <- grid_to_polygon(grid_coords)
 #'
 #' data("data_provided")
-#'
 #' data_raster <- polygrid |>
 #'   dplyr::inner_join(data_provided,
 #'     by = c("quadkey")
 #'   )
 #'
 #' raster <- create_stars_raster(
 #'   template = data_raster,
-#'   nx = grid$num_cols + 1,
-#'   ny = grid$num_rows + 1,
+#'   nx = grid$num_cols,
+#'   ny = grid$num_rows,
 #'   data = data_raster,
 #'   var = "variable"
 #' )
@@ -51,15 +69,16 @@ create_stars_raster <- function(template,
   # data should be in sf format
   data_sf <- sf::st_sf(data)
   # create raster template
-  raster_tmplt <- stars::st_as_stars(sf::st_bbox(sf::st_as_sf(template)),
-    values = NA_real_,
-    ny = ny,
-    nx = nx
-  )
-
+  raster_tmplt <-
+    stars::st_as_stars(
+      sf::st_bbox(sf::st_as_sf(template)),
+      values = NA_real_,
+      ny = ny,
+      nx = nx
+    )
+
   r <- stars::st_rasterize(data_sf[, c(as.character(var))],
-    template = raster_tmplt
-  )
-
+                           template = raster_tmplt)
+
   return(r)
 }

R/data.R

@@ -1,6 +1,6 @@
 #' data_provided: fake dataset
 #'
-#' A data frame simulating a variable asociated with QuadKey numbers.
+#' A data.frame simulating a variable asociated with QuadKeys.
 #'
 #' @format ## `data_provided`
 #' A data frame with 360 rows and 2 columns:
@@ -10,9 +10,9 @@
 #' }
 "data_provided"
 
-#' result_read_fb_mobility_data: Fake dataset
+#' `result_read_fb_mobility_data`: Fake dataset
 #'
-#' A data frame similar to a the potential output of read_all_files().
+#' A data frame similar to a the potential output of `read_fb_mobility_files`.
 #'
 #' @format ## `result_read_fb_mobility_data`
 #' A data frame with 134,492 rows and 9 columns:

R/get_coords.R

@@ -9,8 +9,8 @@
 #' @seealso \code{\link{tileXY_to_pixelXY}}
 #' @seealso \code{\link{pixelXY_to_latlong}}
 #'
-#' @return A spatial dataframe (sf) containing the tiles XY coordinates
-#' (tileX, tileY), the QuadKey (quadkey), and a POINT geometry column.
+#' @return A `sf` POINT data.frame containing the tiles XY coordinates
+#' (`tileX`, `tileY`), the QuadKeys (`quadkey`), and a `geometry` column.
 #'
 #' @export
 #'
@@ -61,15 +61,15 @@ get_qk_coord <- function(data) {
 #' @description Reads the tile XY coordinates and extracts the
 #' lat/long coordinates of the upper-left corner of the QuadKey.
 #'
-#' @param data A dataframe with columns named tileX and tileY
+#' @param data A dataframe with columns named `tileX` and `tileY`
 #' @param zoom Zoom or Level of detail, 
 #' from 1 (lowest detail) to 23 (highest detail).
 #'
 #' @seealso \code{\link{tileXY_to_pixelXY}}
 #' @seealso \code{\link{pixelXY_to_latlong}}
 #'
-#' @return  A spatial dataframe (sf) containing the tiles XY coordinates
-#' (tileX, tileY)  and a column for POINT geometry.
+#' @return  A `sf` POINT data.frame containing the tiles XY coordinates
+#' (`tileX`, `tileY`), a `quadkey` and a `geometry` column.
 #'
 #' @export
 #'
@@ -134,31 +134,3 @@ get_tile_coord <- function(data, zoom) {
 
   return(data)
 }
-
-
-#' Convert data.frame with quadkey column to a sf POLYGON data.frame
-#'
-#' @param data A data.frame with a quadkey column
-#'
-#' @return The same original data.frame with a sf POLYGON data.frame with a
-#' geometry column.
-#'  
-#' @export
-#'
-#' @examples
-#' 
-#' path <- paste0(system.file("extdata", package = 'quadkeyr'), 
-#'                                     "/cityA_2020_04_15_0000.csv")
-#' data <- read.csv(path)
-#' data <- format_fb_data(data)
-#'
-#' quadkey_df_to_polygon(data)
-quadkey_df_to_polygon <- function(data){
-
-        data |> 
-        dplyr::rowwise() |> 
-        dplyr::mutate(quadkey_to_polygon(.data$quadkey)) |> # tidyselect
-        as.data.frame() |>  # remove class rowwise_df
-        sf::st_sf() 
-
-}