diff --git a/R/api_url.R b/R/api_url.R index 9175d346..d296dd3d 100644 --- a/R/api_url.R +++ b/R/api_url.R @@ -1,4 +1,4 @@ -# API URL Functions ---------------------------------------------------------------- +# API URL Functions # reverse = TRUE for reverse geocoding ## wrapper function for functions below diff --git a/R/batch_geocoding.R b/R/batch_geocoding.R index 0a145530..322432d7 100644 --- a/R/batch_geocoding.R +++ b/R/batch_geocoding.R @@ -1,4 +1,5 @@ -### Functions for batch geocoding that are called by geo() +# Functions for batch (forward) geocoding that are called by geo() + # Census batch geocoding # @param address_pack packaged addresses object diff --git a/R/documentation.R b/R/documentation.R index c83adde9..edb2af93 100644 --- a/R/documentation.R +++ b/R/documentation.R @@ -1,4 +1,4 @@ -### Functions to produce documentation +# Functions to produce documentation # Functions return a character vector with one element per line # to produce roxygen documentation # see: https://roxygen2.r-lib.org/articles/rd-formatting.html#dynamic-r-code diff --git a/R/geo.R b/R/geo.R index 1dc1eb1b..165f2026 100644 --- a/R/geo.R +++ b/R/geo.R @@ -99,7 +99,7 @@ progress_geo <- function(pb = NULL, ...) { #' with the name of the `method` (service) it applies to. The possible parameters #' are shown below with their default values. #' -#' - `census_return_type` (default: `"locations"`): set to "geographies" to return +#' - `census_return_type` (default: `"locations"`): set to `"geographies"` to return #' additional geography columns. Make sure to use `full_results = TRUE` if using #' the "geographies" setting. #' - `iq_region` (default: `"us"`): set to "eu" to use the European Union API endpoint diff --git a/R/geo_methods.R b/R/geo_methods.R index 47b78a55..731beed5 100644 --- a/R/geo_methods.R +++ b/R/geo_methods.R @@ -1,3 +1,7 @@ +# The functions in this file are deprecated and will be removed in a future +# version of tidygeocoder + + #' Convenience functions for calling `geo()` #' #' @description The `method` for `geo()` is specified in the function name. @@ -98,8 +102,6 @@ geo_cascade <- function(...) { } - - ## private cascade geocoding function ## called from geo() for method = 'cascade' cascade_geocoding <- function(..., cascade_order = c('census', 'osm')) { diff --git a/R/geocode_combine.R b/R/geocode_combine.R index 9ad7d457..903f4f83 100644 --- a/R/geocode_combine.R +++ b/R/geocode_combine.R @@ -2,7 +2,7 @@ get_queries_parameter_documentation <- function() { return(c( "a list of queries, each provided as a list of parameters. The queries are", - "executed in the order provided by the [geocode] function.", + "executed by the [geocode] function in the order provided.", "(ex. `list(list(method = 'osm'), list(method = 'census'), ...)`)" )) } @@ -20,8 +20,8 @@ get_global_params_parameter_documentation <- function() { #' @description Passes address inputs in character vector form to the #' [geocode_combine] function for geocoding. #' -#' Note that address inputs must be specified for queries either in `queries` (for each query) -#' or `global_params` (for all queries). For example `global_params = list(address = 'address')` +#' Note that address inputs must be specified for queries either with the `queries` parameter (for each query) +#' or the `global_params` parameter (for all queries). For example `global_params = list(address = 'address')` #' passes addresses provided in the `address` parameter to all queries. #' #' @param queries `r get_queries_parameter_documentation()` diff --git a/R/global_variables.R b/R/global_variables.R index 85b80561..58eab881 100644 --- a/R/global_variables.R +++ b/R/global_variables.R @@ -1,4 +1,5 @@ -### Global package variables +# Global package variables + pkg.globals <- new.env() diff --git a/R/input_handling.R b/R/input_handling.R index e23a2abd..ddeebe84 100644 --- a/R/input_handling.R +++ b/R/input_handling.R @@ -1,3 +1,8 @@ +# By default tidygeocoder only sends unique inputs to geocoding services +# but preserves duplicates in outputs. These functions perform the +# deduplication and "re-deduplication" to facilitate that. + + # utility function for packaging either lat longs or address data # takes a dataframe input # cords = TRUE if processing coordinates @@ -84,6 +89,8 @@ package_addresses <- function(address = NULL, # so that we can return them in the same order that they were passed # this function assumes that the results are in the same order as package$unique # Args: +# package: the output of package_inputs() or package_addresses() +# results: the results returned by the geocoding service # unique_only: if TRUE then only unique results are returned # return_inputs: if TRUE then include inputs in the returned results # diff --git a/R/query_factory.R b/R/query_factory.R index a896b8fa..34c9a4fa 100644 --- a/R/query_factory.R +++ b/R/query_factory.R @@ -1,4 +1,5 @@ -### Functions for constructing API queries +# Functions for constructing API queries + # Get API Key from environmental variables get_key <- function(method) { diff --git a/R/reverse_batch_geocoding.R b/R/reverse_batch_geocoding.R index b0472889..072b588b 100644 --- a/R/reverse_batch_geocoding.R +++ b/R/reverse_batch_geocoding.R @@ -1,4 +1,4 @@ -### Functions for reverse batch geocoding that are called by reverse_geo() +# Functions for reverse batch geocoding that are called by reverse_geo() # Reverse Batch geocoding with geocodio diff --git a/R/tidygeocoder.R b/R/tidygeocoder.R index 4bc8f9f2..ea36b7c8 100644 --- a/R/tidygeocoder.R +++ b/R/tidygeocoder.R @@ -3,7 +3,7 @@ #' The [geocode] and [geo] functions are for forward geocoding while #' the [reverse_geocode] and [reverse_geo] functions are for reverse geocoding. #' Refer to the documentation on the `method` argument in the [geo] and [reverse_geo] functions -#' for more details on the available geocoder services. Also see `vignette("tidygeocoder")` +#' for more details on the available geocoding services. Also see `vignette("tidygeocoder")` #' for example usage. #' @keywords internal diff --git a/R/utils.R b/R/utils.R index 5bd72726..91686081 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,4 +1,4 @@ -### Put common utility functions here +# Common utility functions # utility function for extracting setting values according to the method column diff --git a/man/geo.Rd b/man/geo.Rd index 2f92675e..a81ff390 100644 --- a/man/geo.Rd +++ b/man/geo.Rd @@ -151,7 +151,7 @@ Used for testing.} with the name of the \code{method} (service) it applies to. The possible parameters are shown below with their default values. \itemize{ -\item \code{census_return_type} (default: \code{"locations"}): set to "geographies" to return +\item \code{census_return_type} (default: \code{"locations"}): set to \code{"geographies"} to return additional geography columns. Make sure to use \code{full_results = TRUE} if using the "geographies" setting. \item \code{iq_region} (default: \code{"us"}): set to "eu" to use the European Union API endpoint diff --git a/man/geo_combine.Rd b/man/geo_combine.Rd index 6801cdb0..56ae1950 100644 --- a/man/geo_combine.Rd +++ b/man/geo_combine.Rd @@ -21,7 +21,7 @@ geo_combine( } \arguments{ \item{queries}{a list of queries, each provided as a list of parameters. The queries are -executed in the order provided by the \link{geocode} function. +executed by the \link{geocode} function in the order provided. (ex. \code{list(list(method = 'osm'), list(method = 'census'), ...)})} \item{global_params}{a list of parameters to be used for all queries @@ -56,8 +56,8 @@ tibble (dataframe) Passes address inputs in character vector form to the \link{geocode_combine} function for geocoding. -Note that address inputs must be specified for queries either in \code{queries} (for each query) -or \code{global_params} (for all queries). For example \code{global_params = list(address = 'address')} +Note that address inputs must be specified for queries either with the \code{queries} parameter (for each query) +or the \code{global_params} parameter (for all queries). For example \code{global_params = list(address = 'address')} passes addresses provided in the \code{address} parameter to all queries. } \examples{ diff --git a/man/geocode_combine.Rd b/man/geocode_combine.Rd index 47de54e7..708bba16 100644 --- a/man/geocode_combine.Rd +++ b/man/geocode_combine.Rd @@ -19,7 +19,7 @@ geocode_combine( \item{.tbl}{dataframe containing addresses} \item{queries}{a list of queries, each provided as a list of parameters. The queries are -executed in the order provided by the \link{geocode} function. +executed by the \link{geocode} function in the order provided. (ex. \code{list(list(method = 'osm'), list(method = 'census'), ...)})} \item{global_params}{a list of parameters to be used for all queries diff --git a/man/reverse_geo.Rd b/man/reverse_geo.Rd index 4b1c95fc..027cae1b 100644 --- a/man/reverse_geo.Rd +++ b/man/reverse_geo.Rd @@ -113,7 +113,7 @@ Used for testing.} with the name of the \code{method} (service) it applies to. The possible parameters are shown below with their default values. \itemize{ -\item \code{census_return_type} (default: \code{"locations"}): set to "geographies" to return +\item \code{census_return_type} (default: \code{"locations"}): set to \code{"geographies"} to return additional geography columns. Make sure to use \code{full_results = TRUE} if using the "geographies" setting. \item \code{iq_region} (default: \code{"us"}): set to "eu" to use the European Union API endpoint diff --git a/man/tidygeocoder-package.Rd b/man/tidygeocoder-package.Rd index 549fac0a..9d5d2986 100644 --- a/man/tidygeocoder-package.Rd +++ b/man/tidygeocoder-package.Rd @@ -9,7 +9,7 @@ The \link{geocode} and \link{geo} functions are for forward geocoding while the \link{reverse_geocode} and \link{reverse_geo} functions are for reverse geocoding. Refer to the documentation on the \code{method} argument in the \link{geo} and \link{reverse_geo} functions -for more details on the available geocoder services. Also see \code{vignette("tidygeocoder")} +for more details on the available geocoding services. Also see \code{vignette("tidygeocoder")} for example usage. } \seealso{ diff --git a/vignettes/developer_notes.Rmd b/vignettes/developer_notes.Rmd index 852a6d0b..586082a4 100644 --- a/vignettes/developer_notes.Rmd +++ b/vignettes/developer_notes.Rmd @@ -82,17 +82,14 @@ This section documents how to add support for a new geocoding service to the pac * Update the `extract_results()` function which is used for parsing single addresses (ie. not batch geocoding). You can see examples of how I've tested out parsing the results of geocoding services [here](https://github.com/jessecambon/tidygeocoder/tree/main/sandbox/query_debugging). * In a similar fashion, update the `extract_reverse_results()` function for reverse geocoding. * Update the `extract_errors_from_results()` function to extract error messages for invalid queries. -* **[R/geo_methods.R](https://github.com/jessecambon/tidygeocoder/blob/main/R/geo_methods.R)** - * Add a new `geo_()` convenience function to [R/geo_methods.R](https://github.com/jessecambon/tidygeocoder/blob/main/R/geo_methods.R). Note that these functions are deprecated and will be phased out in the future. * If applicable, add new tests to the scripts in the [tests directory](https://github.com/jessecambon/tidygeocoder/tree/main/tests/testthat) for the method. Note that tests should avoid making a HTTP query (ie. use `no_query = TRUE` in the `geo()` and `geocode()` functions). * **[R/global_variables.R](https://github.com/jessecambon/tidygeocoder/blob/main/R/global_variables.R)** - * If applicable, add your service to one of the global variables. + * If applicable, add your service to one of the global variables. ### Other Files These files don't necessarily need to be updated. However, you might need to make changes to these files if the service you are implementing requires some non-standard workarounds. - * **[R/query_factory.R](https://github.com/jessecambon/tidygeocoder/blob/main/R/query_factory.R)** * Houses the functions used to create and execute API queries. * **[R/documentation.R](https://github.com/jessecambon/tidygeocoder/blob/main/R/documentation.R)**