From 93c9eed65bf321fa391bc2debd5f6ff0a93272a4 Mon Sep 17 00:00:00 2001 From: rafapereirabr Date: Sat, 4 Jun 2022 23:26:27 -0300 Subject: [PATCH] update documentation --- R/cumulative_cutoff.R | 27 ++++++++++++-------- R/cumulative_interval.R | 34 +++++++++++++++---------- accessibility.Rproj | 5 ++-- man/cumulative_time_interval.Rd | 30 +++++++++++++--------- man/cumulative_time_threshold.Rd | 26 +++++++++---------- tests/testthat.R | 6 ++--- tests/testthat/test-cumulative_cutoff.R | 14 +++++----- 7 files changed, 79 insertions(+), 63 deletions(-) diff --git a/R/cumulative_cutoff.R b/R/cumulative_cutoff.R index 7dace6e..9f11bc2 100644 --- 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 index 459c8ec..f32e24e 100644 --- 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,7 +68,7 @@ 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) } ) @@ -70,10 +76,10 @@ cumulative_time_interval <- function(data = df, opportunity_colname, start=20, e # 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 index 497f8bf..cba1b6b 100644 --- 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 index c4021a6..ae12b4b 100644 --- a/man/cumulative_time_interval.Rd +++ b/man/cumulative_time_interval.Rd @@ -5,30 +5,36 @@ \title{Cumulative access based on time interval} \usage{ cumulative_time_interval( - data = df, + data, opportunity_colname, - start = 20, - end = 30, - by_col = "from_id", + start, + end, + by_colname, stat = "mean" ) } \arguments{ -\item{data}{A \code{data.frame} with a travel time matrix in long format.} +\item{data}{A \code{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.} -\item{opportunity_colname}{A \code{string} indicating the column name where the -data on number of opportunities is stored.} +\item{opportunity_colname}{A \code{string} indicating the name of the column with +data on the number of opportunities to be considered.} \item{start}{An \code{integer} indicating the \code{start} point of the travel time interval.} \item{end}{An \code{integer} indicating the \code{end} point of the travel time interval.} -\item{by_col}{A string pointing to the name of the column of origin or -destination.} +\item{by_colname}{A \code{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).} -\item{stat}{A \code{string} indicating the summary measure to be used. It -accepts either \code{median} (Default) or \code{mean}.} +\item{stat}{A \code{string} indicating the summary statistic used to aggregate the +accessibility estimates within the time interval. It accepts either \code{median} +(Default) or \code{mean}.} } \value{ A \code{data.table} object. @@ -48,7 +54,7 @@ df <- cumulative_time_interval(data = ttm, opportunity_colname = 'schools', start = 20, end = 30, - by_col = 'from_id', + by_colname = 'from_id', stat ='median') head(df) diff --git a/man/cumulative_time_threshold.Rd b/man/cumulative_time_threshold.Rd index a0a7563..0380693 100644 --- a/man/cumulative_time_threshold.Rd +++ b/man/cumulative_time_threshold.Rd @@ -4,23 +4,23 @@ \alias{cumulative_time_threshold} \title{Cumulative access based on time threshold} \usage{ -cumulative_time_threshold( - data, - opportunity_colname, - cutoff = 20, - by_col = "from_id" -) +cumulative_time_threshold(data, opportunity_colname, cutoff, by_colname) } \arguments{ -\item{data}{A \code{data.frame} with a travel time matrix in long format.} +\item{data}{A \code{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.} -\item{opportunity_colname}{A \code{string} indicating the column name where the -data on number of opportunities is stored.} +\item{opportunity_colname}{A \code{string} indicating the name of the column with +data on the number of opportunities to be considered.} \item{cutoff}{A \code{numeric} value indicating the maximum travel time considered.} -\item{by_col}{A \code{string} pointing to the name of the column of origin or -destination.} +\item{by_colname}{A \code{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).} } \value{ A \code{data.table} object. @@ -40,14 +40,14 @@ ttm <- read.csv(data_path) 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) } \seealso{ diff --git a/tests/testthat.R b/tests/testthat.R index 46b9df2..5f2b012 100644 --- 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 index e101a6e..7c71dbc 100644 --- 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"))