update documentation

ipeaGIT · Jun 5, 2022 · 93c9eed · 93c9eed
1 parent f665594
commit 93c9eed
Show file tree

Hide file tree

Showing 7 changed files with 79 additions and 63 deletions.
diff --git a/R/cumulative_cutoff.R b/R/cumulative_cutoff.R
@@ -3,12 +3,17 @@
 #' The function calculates the number of opportunities accessible under a given
 #' travel time threshold specified by the user.
 #'
-#' @param data A `data.frame` with a travel time matrix in long format.
-#' @param opportunity_colname A `string` indicating the column name where the
-#' data on number of opportunities is stored.
+#' @param data A `data.frame` with a travel time matrix in long format,
+#'   containing the at least the columns of origin, destination, travel time
+#'   from origin to destination, and number of opportunities in destination
+#'   locations.
+#' @param opportunity_colname A `string` indicating the name of the column with
+#'   data on the number of opportunities to be considered.
+#' @param by_colname A `string` with the name of the column of origin or
+#'   destination that should be considered, indicating whether accessibility
+#'   levels should by calculated by each origin (active accessibility) or
+#'   destination (passive accessibility).
 #' @param cutoff A `numeric` value indicating the maximum travel time considered.
-#' @param by_col A `string` pointing to the name of the column of origin or
-#' destination.
 #'
 #' @return A `data.table` object.
 #'
@@ -23,29 +28,29 @@
 #'df <- cumulative_time_threshold(data = ttm,
 #'                                opportunity_colname = 'schools',
 #'                                cutoff = 30,
-#'                                by_col = 'from_id')
+#'                                by_colname = 'from_id')
 #'head(df)
 #'
 #'# Passive accessibility: number of people that can reach each destination
 #'df <- cumulative_time_threshold(data = ttm,
 #'                                opportunity_colname = 'population',
 #'                                cutoff = 30,
-#'                                by_col = 'to_id')
+#'                                by_colname = 'to_id')
 #'head(df)
 #' @family Cumulative access
 #' @export
-cumulative_time_threshold <- function(data, opportunity_colname, cutoff = 20, by_col='from_id'){
+cumulative_time_threshold <- function(data, opportunity_colname, cutoff, by_colname){
 
 
   # check inputs ------------------------------------------------------------
   checkmate::test_data_frame(data)
   checkmate::test_string(opportunity_colname)
-  checkmate::test_string(by_col)
+  checkmate::test_string(by_colname)
   checkmate::assert_number(cutoff, lower = 0)
 
   checkmate::assert_names(names(data), must.include = opportunity_colname,
                           .var.name = "data")
-  checkmate::assert_names(names(data), must.include = by_col,
+  checkmate::assert_names(names(data), must.include = by_colname,
                           .var.name = "data")
 
 
@@ -56,7 +61,7 @@ cumulative_time_threshold <- function(data, opportunity_colname, cutoff = 20, by
   ### TO DO
   # CONVERT the "travel_time" column into a function parameter ?
   colname <- as.name(opportunity_colname)
-  access <- data[travel_time <= cutoff, .(access = sum(eval(colname))), by=by_col]
+  access <- data[travel_time <= cutoff, .(access = sum(eval(colname))), by=by_colname]
 
   return(access)
 }
diff --git a/R/cumulative_interval.R b/R/cumulative_interval.R
@@ -3,16 +3,22 @@
 #' The function calculates the average or median number of opportunities
 #' accessible within a travel time interval specified by the user.
 #'
-#' @param data A `data.frame` with a travel time matrix in long format.
-#' @param opportunity_colname A `string` indicating the column name where the
-#' data on number of opportunities is stored.
+#' @param data A `data.frame` with a travel time matrix in long format,
+#'   containing the at least the columns of origin, destination, travel time
+#'   from origin to destination, and number of opportunities in destination
+#'   locations.
+#' @param opportunity_colname A `string` indicating the name of the column with
+#'   data on the number of opportunities to be considered.
+#' @param by_colname A `string` with the name of the column of origin or
+#'   destination that should be considered, indicating whether accessibility
+#'   levels should by calculated by each origin (active accessibility) or
+#'   destination (passive accessibility).
 #' @param start An `integer` indicating the `start` point of the travel time
 #' interval.
 #' @param end An `integer` indicating the `end` point of the travel time interval.
-#' @param stat A `string` indicating the summary measure to be used. It
-#' accepts either `median` (Default) or `mean`.
-#' @param by_col A string pointing to the name of the column of origin or
-#' destination.
+#' @param stat A `string` indicating the summary statistic used to aggregate the
+#' accessibility estimates within the time interval. It accepts either `median`
+#' (Default) or `mean`.
 #'
 #' @return A `data.table` object.
 #' @examples
@@ -26,25 +32,25 @@
 #'                               opportunity_colname = 'schools',
 #'                               start = 20,
 #'                               end = 30,
-#'                               by_col = 'from_id',
+#'                               by_colname = 'from_id',
 #'                               stat ='median')
 #'head(df)
 #'
 #' @family Cumulative access
 #' @export
-cumulative_time_interval <- function(data = df, opportunity_colname, start=20, end=30, by_col='from_id', stat='mean'){
+cumulative_time_interval <- function(data, opportunity_colname, start, end, by_colname, stat='mean'){
 
   # check inputs ------------------------------------------------------------
   checkmate::test_data_frame(data)
   checkmate::test_string(opportunity_colname)
-  checkmate::test_string(by_col)
+  checkmate::test_string(by_colname)
   checkmate::test_numeric(start)
   checkmate::test_numeric(end)
 
   checkmate::assert_names(names(data), must.include = opportunity_colname,
                           .var.name = "data")
 
-  checkmate::assert_names(names(data), must.include = by_col,
+  checkmate::assert_names(names(data), must.include = by_colname,
                           .var.name = "data")
 
   checkmate::assert_choice(x=stat, choices=c('mean', 'median'))
@@ -62,18 +68,18 @@ cumulative_time_interval <- function(data = df, opportunity_colname, start=20, e
                           temp <-  cumulative_time_threshold(data = data,
                                                              cutoff = i,
                                                              opportunity_colname=opportunity_colname,
-                                                             by_col=by_col)
+                                                             by_colname=by_colname)
                           return(temp)
                           }
                         )
   access <- data.table::rbindlist(access_list)
 
   # summary measure to be used
   if (stat=='mean') {
-    access <- access[, .(access=mean(access, na.rm=T)), by=by_col ] }
+    access <- access[, .(access=mean(access, na.rm=T)), by=by_colname ] }
 
   if (stat=='median') {
-    access <- access[, .(access=median(access, na.rm=T)), by=by_col ] }
+    access <- access[, .(access=median(access, na.rm=T)), by=by_colname ] }
 
   return(access)
   }
diff --git a/accessibility.Rproj b/accessibility.Rproj
@@ -1,7 +1,7 @@
 Version: 1.0
 
-RestoreWorkspace: Default
-SaveWorkspace: Default
+RestoreWorkspace: No
+SaveWorkspace: No
 AlwaysSaveHistory: Default
 
 EnableCodeIndexing: Yes
@@ -18,3 +18,4 @@ StripTrailingWhitespace: Yes
 BuildType: Package
 PackageUseDevtools: Yes
 PackageInstallArgs: --no-multiarch --with-keep.source
+PackageRoxygenize: rd,collate,namespace
diff --git a/man/cumulative_time_interval.Rd b/man/cumulative_time_interval.Rd
diff --git a/man/cumulative_time_threshold.Rd b/man/cumulative_time_threshold.Rd
diff --git a/tests/testthat.R b/tests/testthat.R
@@ -1,6 +1,4 @@
-options(java.parameters = '-Xmx2G')
-
 library(testthat)
-library(r5r)
+library(accessibility)
 
-test_check("r5r")
+test_check("accessibility")
diff --git a/tests/testthat/test-cumulative_cutoff.R b/tests/testthat/test-cumulative_cutoff.R
@@ -8,12 +8,12 @@ testthat::skip_on_cran()
 default_tester <- function(data = ttm,
                            opportunity_colname = 'schools',
                            cutoff = 20,
-                           by_col='from_id') {
+                           by_colname='from_id') {
 
   results <- accessibility::cumulative_time_threshold(data = data,
                                       opportunity_colname = opportunity_colname,
                                       cutoff = cutoff,
-                                      by_col = by_col)
+                                      by_colname = by_colname)
   return(results)
   }
 
@@ -26,11 +26,11 @@ test_that("adequately raises errors", {
   # input data is not a data.frame
   expect_error(default_tester(data = list(ttm)))
 
-  # opportunity_colname and by_col do not exist in data input
+  # opportunity_colname and by_colname do not exist in data input
   expect_error(default_tester(opportunity_colname = 'banana'))
-  expect_error(default_tester(by_col = 'banana'))
+  expect_error(default_tester(by_colname = 'banana'))
   expect_error(default_tester(opportunity_colname = 999))
-  expect_error(default_tester(by_col = 999))
+  expect_error(default_tester(by_colname = 999))
 
   # cutoff value is not positive numeric
   expect_error(default_tester(cutoff = "banana"))
@@ -51,8 +51,8 @@ test_that("output is correct", {
   # different opportunity_colname
   expect_true(is(default_tester(opportunity_colname = 'population'), "data.table"))
 
-  # different by_col
-  expect_true(is(default_tester(by_col = 'from_id'), "data.table"))
+  # different by_colname
+  expect_true(is(default_tester(by_colname = 'from_id'), "data.table"))
 
   # different cutoff values
   expect_true(is(default_tester(cutoff = Inf), "data.table"))