Merge pull request #116 from R-ArcGIS/examples

Add examples and returns values to all Rd file

R/add_item.R

@@ -56,6 +56,8 @@
 #'     x, "North Carolina SIDS sample"
 #'   )
 #' }
+#' @returns
+#' A named list containing the url of the newly published service.
 add_item <- function(
     x,
     title,

R/arc-add-update-delete.R

@@ -18,6 +18,9 @@
 #'
 #' `r lifecycle::badge("experimental")`
 #'
+#' For a more detailed guide to adding, updating, and deleting features, view the
+#' tutorial on the [R-ArcGIS Bridge website](https://r.esri.com/r-bridge-site/location-services/workflows/add-delete-update.html).
+#'
 #' Regarding the `match_on` argument:when publishing an object to an ArcGIS Portal
 #' from R, the object's names are provided as the alias. The object's names are
 #' subject to change according to the standards of the ArcGIS REST API. For example.
@@ -27,6 +30,24 @@
 #'
 #' @export
 #' @rdname modify
+#' @examples
+#' if (interactive()) {
+#'   # this is pseudo-code and will not work
+#'   flayer <- arc_open(furl)
+#'
+#'   # add sf objects to existing feature service
+#'   add_features(flayer, sfobj)
+#'
+#'   # delete all features
+#'   delete_features(flayer, where = "1 = 1")
+#'
+#'   # update features
+#'   update_features(flayer, dfobj)
+#' }
+#' @returns
+#' - `add_features()` returns a `data.frame` with columns `objectId`, `uniqueId`, `globalId`, `success`
+#' - `update_features()` returns a list with an element named `updateResults` which is a `data.frame` with columns `objectId`, `uniqueId`, `globalId`, `success`
+#' - `delete_features()` returns a list with an element named `deleteResults` which is a `data.frame` with columns `objectId`, `uniqueId`, `globalId`, `success`
 add_features <- function(
     x,
     .data,

R/arc-open.R

@@ -15,7 +15,48 @@
 #' @seealso arc_select arc_raster
 #' @export
 #' @returns
-#' Depending on the provided URL returns a `FeatureLayer`, `Table`, `FeatureServer`, or `ImageServer`.
+#' Depending on the provided URL returns a `FeatureLayer`, `Table`, `FeatureServer`, `ImageServer`, or `MapServer`.
+#' @examples
+#'
+#'if (interactive()) {
+#'  # FeatureLayer
+#'  furl <- paste0(
+#'    "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest/services/",
+#'    "PLACES_LocalData_for_BetterHealth/FeatureServer/0"
+#'  )
+#'
+#'  arc_open(furl)
+#'
+#'  # Table
+#'  furl <- paste0(
+#'    "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/",
+#'    "USA_Wetlands/FeatureServer/1"
+#'  )
+#'
+#'  arc_open(furl)
+#'
+#'  # ImageServer
+#'  arc_open(
+#'    "https://landsat2.arcgis.com/arcgis/rest/services/Landsat/MS/ImageServer"
+#'    )
+#'
+#'  # FeatureServer
+#'  furl <- paste0(
+#'    "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest/services/",
+#'    "PLACES_LocalData_for_BetterHealth/FeatureServer"
+#'  )
+#'
+#'  arc_open(furl)
+#'
+#'  # MapServer
+#'  map_url <- paste0(
+#'    "https://services.arcgisonline.com/ArcGIS/rest/services/",
+#'    "World_Imagery/MapServer"
+#'  )
+#'
+#'  arc_open(map_url)
+#'
+#'}
 arc_open <- function(url, token = Sys.getenv("ARCGIS_TOKEN")) {
 
   stopifnot("`url` must be of length 1" = length(url) == 1)

R/arc-select.R

@@ -1,9 +1,9 @@
-#' Retrieve a feature layer as simple features or a non-spatial data frame
+#' Query a Hosted Feature Service
 #'
-#' [arc_select()] takes a `FeatureLayer` or `Table` object and returns data from
+#' [arc_select()] takes a `FeatureLayer`, `Table`, of `ImageServer` object and returns data from
 #' the layer as an `sf` object or `tibble` respectively.
 #'
-#' @inheritParams obj_check_layer
+#' @param x an object of class `FeatureLayer`, `Table`, or `ImageServer`.
 #' @param fields a character vector of the field names that you wish to be
 #'   returned. By default all fields are returned.
 #' @param where a simple SQL where statement indicating which features should be
@@ -26,6 +26,28 @@
 #' `r lifecycle::badge("experimental")`
 #'
 #' @export
+#' @examples
+#' if (interactive()) {
+#'   # define the feature layer url
+#'   furl <- paste0(
+#'     "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest",
+#'     "/services/PLACES_LocalData_for_BetterHealth/FeatureServer/0"
+#'   )
+#'
+#'   flayer <- arc_open(furl)
+#'
+#'   arc_select(
+#'     flayer,
+#'     fields = c("StateAbbr", "TotalPopulation")
+#'   )
+#'
+#'   arc_select(
+#'     flayer,
+#'     fields = c("OBJECTID", "PlaceName"),
+#'     where = "TotalPopulation > 1000000"
+#'   )
+#' }
+#' @returns An sf object, or a data.frame
 arc_select <- function(
     x,
     fields = NULL,
@@ -107,7 +129,7 @@ arc_select <- function(
 #' [collect_layer()] is the "workhorse" function that actually executes the
 #' queries for FeatureLayer or Table objects.
 #'
-#' @keywords internal
+#' @noRd
 collect_layer <- function(x,
                           n_max = Inf,
                           token = Sys.getenv("ARCGIS_TOKEN"),
@@ -238,6 +260,7 @@ collect_layer <- function(x,
 #' @param x A `FeatureLayer` or `Table` class object created with [arc_open()].
 #' @inheritParams rlang::args_error_context
 #' @keywords internal
+#' @noRd
 obj_check_layer <- function(x,
                             arg = rlang::caller_arg(x),
                             call = rlang::caller_env()) {
@@ -258,6 +281,7 @@ obj_check_layer <- function(x,
 #' @inheritParams rlang::inherits_any
 #' @inheritParams rlang::args_error_context
 #' @keywords internal
+#' @noRd
 check_inherits_any <- function(x,
                                class,
                                arg = rlang::caller_arg(x),
@@ -286,7 +310,11 @@ check_inherits_any <- function(x,
 #' @export
 #' @examples
 #' if (interactive()) {
-#'  furl <- "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/USA_Major_Cities_/FeatureServer/0"
+#'   furl <- paste0(
+#'     "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/",
+#'     "USA_Major_Cities_/FeatureServer/0"
+#'   )
+#'
 #'  flayer <- arc_open(furl)
 #'  update_params(flayer, outFields = "NAME")
 #' }
@@ -310,6 +338,7 @@ update_params <- function(x, ...) {
 #' Feature Layers with more than 2000 observations.
 #'
 #' @keywords internal
+#' @noRd
 add_offset <- function(offset, request, params) {
   params[["resultOffset"]] <- offset
   req <- httr2::req_url_path_append(request, "query")
@@ -322,6 +351,7 @@ add_offset <- function(offset, request, params) {
 #' acceptable values.
 #'
 #' @keywords internal
+#' @noRd
 validate_params <- function(params, token) {
   # set the token
   params[["token"]] <- token

R/arcgislayers-package.R

@@ -1,4 +1,5 @@
 #' @keywords internal
+#' @noRd
 "_PACKAGE"
 
 ## usethis namespace: start

R/create-service.R

@@ -1,5 +1,7 @@
 #' Create a FeatureServer
 #'
+#' Creates an empty FeatureServer with no additional layers.
+#'
 #' @param service_name Feature Service name.
 #' @param user default `Sys.getenv("ARCGIS_USER")`. Your account's username.
 #' @param description default blank. The description of the feature server.
@@ -19,14 +21,19 @@
 #' @inheritParams add_item
 #'
 #' @returns
-#' If a `FeatureServer` is cerated successfully, a `FeatureServer` object is returned
+#' If a `FeatureServer` is created successfully, a `FeatureServer` object is returned
 #' based on the newly created feature server's url.
 #'
 #' @details
 #'
 #' `r lifecycle::badge("experimental")`
 #'
 #' @export
+#' @examples
+#' if (interactive()) {
+#'   set_auth_token(auth_code())
+#'   create_feature_server("My empty feature server")
+#' }
 create_feature_server <- function(
     service_name,
     user = Sys.getenv("ARCGIS_USER"),

R/dplyr-features.R

@@ -1,9 +1,6 @@
 
 # Select ------------------------------------------------------------------
 
-
-#' @keywords internal
-#' @rdname dplyr
 select.FeatureLayer <- function(x, ...) {
 
   # capture valeus passed to dots
@@ -25,16 +22,10 @@ select.FeatureLayer <- function(x, ...) {
   x
 }
 
-
-#' @rdname dplyr
 select.Table <- select.FeatureLayer
 
-
-
 # Filter ------------------------------------------------------------------
 
-#' @keywords internal
-#' @rdname dplyr
 filter.FeatureLayer <- function(x, ...) {
 
   where_clause <- attr(x, "query")[["where"]]
@@ -54,34 +45,9 @@ filter.FeatureLayer <- function(x, ...) {
 }
 
 
-# Table will use same filtering as feature layer. nothing special
-#' @keywords internal
-#' @rdname dplyr
 filter.Table <- filter.FeatureLayer
 
-
-
 # Collect -----------------------------------------------------------------
 
-
-#> we want to return all fields if nothing specified
-#> so we need to check if null
-#> minimum params we need:
-#>  - where 1=1
-#>  - output = fgeojson
-#>  - token
-
-#' dplyr methods
-#'
-#' @details
-#'
-#' The Feature Layer method of `collect()` will overwrite the `returnGeometry` parameter if set with `update_params()`. Use the `geometry` argument in `collect()` to set the parameter.
-#'
-#' @aliases dplyr
-#' @rdname dplyr
-#' @keywords internal
 collect.FeatureLayer <- collect_layer
-#' @keywords internal
-#' @rdname dplyr
 collect.Table <- collect_layer
-

R/get-estimates.R

@@ -4,7 +4,10 @@
 #'
 #' @references [ArcGIS REST Doc](https://developers.arcgis.com/rest/services-reference/enterprise/get-estimates-feature-service-layer-.htm)
 #' @examples
-#' furl <- "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/USA_Counties_Generalized_Boundaries/FeatureServer/0"
+#' furl <- paste0(
+#'   "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/",
+#'   "USA_Counties_Generalized_Boundaries/FeatureServer/0"
+#' )
 #'
 #' county_fl <- arc_open(furl)
 #' get_layer_estimates(county_fl)

R/print-methods.R

@@ -238,6 +238,7 @@ print.ImageServer <- function(x, ...) {
 #' to fit on the contents of the window.
 #'
 #' @keywords internal
+#' @noRd
 prettify_param <- function(param, query) {
   n_pad <- nchar(param) + 3
   cwidth <- options("width")[["width"]]

R/utils-feature-server.R

@@ -21,6 +21,21 @@
 #'     Each a list containing `FeatureLayer` and `Table`s respectively.
 #'
 #' @export
+#' @examples
+#' if (interactive()) {
+#'   # FeatureServer
+#'   furl <- paste0(
+#'     "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest/services/",
+#'     "PLACES_LocalData_for_BetterHealth/FeatureServer"
+#'   )
+#'
+#'   fserv <- arc_open(furl)
+#'
+#'   fserv
+#'   get_layer(fserv, 0)
+#'   get_layers(fserv, name = c("Tracts", "ZCTAs"))
+#'   get_all_layers(fserv)
+#' }
 get_layer <- function(x, id = NULL, name = NULL, token = Sys.getenv("ARCGIS_TOKEN")) {
 
   # check for mutual exclusivity between id and name

R/utils-spatial-filter.R

@@ -4,11 +4,13 @@
 #' [prepare_spatial_filter()] prepares a named list with ESRI JSON geometry for
 #' use as a spatial filter based on a a `sfc`, `sfg`, or `bbox` input object.
 #'
+#' @inheritParams arcgisutils::validate_crs
 #' @param filter_geom an object of class `bbox`, `sfc` or `sfg` used to filter
 #'   query results based on a predicate function.
 #' @param predicate Spatial predicate to use with `filter_geom`. Default
 #'   `"intersects"`. Possible options are `"intersects"`, `"contains"`,
 #'   `"crosses"`,  `"overlaps"`,  `"touches"`, and `"within"`.
+#' @param error_call default `rlang::caller_env()`.
 #'
 #' @details Using `sfc` objects as `filter_geom`
 #'
@@ -18,16 +20,17 @@
 #'  reference. If the `sfc` is missing a CRS (or is an `sfg` object) it is
 #'  assumed to use the same spatial reference as the FeatureLayer. If the `sfc`
 #'  object has multiple features, the features are unioned with
-#'  [sf::st_union()]. If an `sfc` object has MULTIPOLYGON geometry, the features
-#'  are unioned before being cast to POLYGON geometry with [sf::st_cast()]. All
+#'  [sf::st_union()]. If an `sfc` object has `MULTIPOLYGON` geometry, the features
+#'  are unioned before being cast to `POLYGON` geometry with [sf::st_cast()]. All
 #'  geometries are checked for validity before conversion.
 #'
 #' @returns [prepare_spatial_filter()] returns a named list with the
-#'   geometryType, geometry (as ESRI JSON), and spatial relation predicate.
+#'   `geometryType`, `geometry` (as Esri JSON), and spatial relation predicate.
 #'
-#' @export
 #' @rdname spatial_filter
-#' @keywords internal
+#' @examples
+#' prepare_spatial_filter(sf::st_point(c(0, 5)), 4326, "intersects")
+#' @export
 prepare_spatial_filter <- function(
     filter_geom,
     crs,