Merge pull request #17 from R-ArcGIS/joint-arcgispackages-post

Examples using arcgis & arcgisbinding

_freeze/location-services/workflows/using-arcgis-arcgisbinding/execute-results/html.json

@@ -0,0 +1,17 @@
+{
+  "hash": "c00a22aee497167a94299b580e1c42d9",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\ntitle: \"Using `arcgis` with `arcgisbinding`\"\nsubtitle: \"Combining the two packages for workflows that span ArcGIS Pro and ArcGIS location services\"\nfreeze: true\n--- \n\n\n\n\nWhile both are components of the R-ArcGIS Bridge, `arcgis` and `arcgisbinding` serve distinct purposes: \n\n- `arcgis` *bridges* to ArcGIS location services, enabling web-based workflows from R\n- `arcgisbinding` *binds* to ArcGIS Pro, enabling data i/o and other desktop software-based processes from R\n\nHowever, there may be instances where you want to combine the functionality of these two R packages in a single workflow. The below code samples demonstrate how these packages can be used together, as well as alongside popular spatial R packages like `terra` and `sf`.\n\n## Extract imagery of the Ouarkziz crater\n\nThis sample shows how to extract and resample multispectral Landsat imagery from ArcGIS Living Atlas using `arcgis` and `arcgisbinding`. Both packages also work with `terra`, so you can easily plot, write, and integrate with other R-based raster analysis workflows.\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# install.packages('arcgis')\n\nlibrary(terra)\nlibrary(raster)\nlibrary(arcgis)\nlibrary(arcgisbinding)\narc.check_product()\n```\n:::\n\n```\nproduct: ArcGIS Pro (13.2.0.49743)\nlicense: Advanced\nversion: 1.0.1.306 \n```\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# ArcGIS Living Atlas Landsat2 imagery service URL \nrurl <- \"https://landsat2.arcgis.com/arcgis/rest/services/Landsat/MS/ImageServer\"\n\n# use arcgis to extract the natural color imagery\nimg_srv <- arc_open(rurl)\nimg_srv\n```\n:::\n\n```\n<ImageServer <11 bands, 26 fields>>\nName: Landsat/MS\nDescription: Multispectral Landsat image service covering the lan\nExtent: -20037507.07 20037507.84 -9694091.07 9691188.93 (xmin, xmax, ymin, ymax)\nResolution: 30 x 30\nCRS: 3857\nCapabilities: Catalog,Image,Metadata\n```\n\n::: {.cell}\n\n```{.r .cell-code}\nimg <- arc_raster(\n  img_srv,\n  \"-846028\", # xmin\n  \"-833783\", # xmax\n  \"3373101\", # ymin\n  \"3380738\", # ymax\n)\nimg\n```\n:::\n\n```\nclass       : SpatRaster \ndimensions  : 400, 400, 11  (nrow, ncol, nlyr)\nresolution  : 30.6125, 30.6125  (x, y)\nextent      : -846028, -833783, 3370797, 3383042  (xmin, xmax, ymin, ymax)\ncoord. ref. : WGS 84 / Pseudo-Mercator (EPSG:3857) \nsource      : x_____xTRXJxJ6XbIPSrPxM-nRAvA..x_____x_ags_8564ca38_5048_4d92_ad3e_750f12824416.tif \nnames       : Coast~rosol, Blue, Green, Red, NearInfrared, Short~red_1, ... \n```\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# use terra to view the imagery\nplotRGB(img, stretch = \"lin\")\n```\n:::\n\n![](images/ouarkziz-crater-RGB.png)\n\n::: {.cell}\n\n```{.r .cell-code}\n# use arcgisbinding to resample and view SWIR\nbbox <- c(-846028, # xmin\n          3373101, # ymin\n          -833783, # xmax\n          3380738) # ymax\nresampled <- arc.raster(arc.open(rurl), bands=1, nrow=300, ncol=300, resample_type=\"CubicConvolution\", extent=bbox)\nswir <- as.raster(resampled)\nplot(swir)\n```\n:::\n\n![](images/ouarkziz-crater-SWIR.png)\n\n::: {.cell}\n\n```{.r .cell-code}\n# use terra to write out the natural color & SWIR rasters\nwriteRaster(img, \"ouarkziz-crater-RGB.tif\", overwrite=TRUE)\nwriteRaster(swir, \"ouarkziz-crater-SWIR.tif\", overwrite=TRUE)\n```\n:::\n\n\nData Source: [Multispectral Landsat](https://www.arcgis.com/home/item.html?id=d9b466d6a9e647ce8d1dd5fe12eb434b) \n\n[Learn more about the Ouarkziz crater in Algeria.](https://earthobservatory.nasa.gov/images/77851/ouarkziz-impact-crater-algeria)\n\n\n## Use local data to update an ArcGIS Online feature service\n\nImagine that you are in charge of maintaining a feature service for your organization that needs to be updated on a regular basis. To avoid dealing with tedious and error-prone manual updates, you can use a scheduled R script to make these updates automatically.\n\nIn this example, the user maintains an ArcGIS Online feature service containing data representing fatal car accidents in Missouri. Periodically, the user receives data updates in a file geodatabase. The workflow below uses `arcgisbinding` to read the feature class into R and convert it to an `sf` object. Then, `arcgis` uses the `sf` object to add the new features to the feature service.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(sf)\nlibrary(arcgis)\nlibrary(arcgisbinding)\narc.check_product()\n```\n:::\n\n```\nproduct: ArcGIS Pro (13.2.0.49743)\nlicense: Advanced\nversion: 1.0.1.306 \n```\n\n::: {.cell}\n\n```{.r .cell-code}\n# use arcgisbinding to read in feature class\nfcpath = \"C:\\\\Data\\\\FARS_update.gdb\\\\FARS_2021\"\nfc <- arc.open(fcpath)\nfc\n```\n:::\n\n```\ndataset_type    : FeatureClass\npath            : C:\\Data\\FARS_update.gdb\\FARS_2021 \nfields          : OBJECTID, Shape, state, statename, st_case, \nfields          : peds, pernotmvit, ve_total, ve_forms, pvh_invl, \nfields          : persons, permvit, county, countyname, city, \nfields          : cityname, month, monthname, day, dayname, \n          ... Truncated ...\nextent          : xmin=-162.5944, ymin=17.96028, xmax=-65.65091, ymax=66.89788\ngeometry type   : Point\nWKT             : GEOGCS[\"GCS_WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_1984\"...\nWKID            : 4326 \n```\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# use arcgisbinding to filter data to Missouri and convert to sf\nsqlquery <- \"STATENAME = 'Missouri'\"\nfcdata <- arc.select(fc, where_clause=sqlquery)\nsfdata <- arc.data2sf(fcdata) # project to 3857\n\n# use arcgis to set token\ntoken <- auth_binding()\nset_arc_token(token)\n```\n:::\n\nIn this case, the token is set using the active portal in ArcGIS Pro (via `{arcgisbinding}`). Note that other [authorization methods](../connecting-to-a-portal.qmd) could be used here, such as `auth_code()` or `auth_user()`.\n\n::: {.cell}\n\n```{.r .cell-code}\n# use arcgis to access feature service\nfsurl <- \"https://services1.arcgis.com/hLJbHVT9ZrDIzK0I/arcgis/rest/services/Fatal_Vehicle_Accidents_in_Missouri/FeatureServer/0\"\nflyr <- arc_open(fsurl)\nflyr\n```\n:::\n\n```\n<FeatureLayer>\nName: Missouri_Fatal_Accidents\nGeometry Type: esriGeometryPoint\nCRS: 3857\nCapabilities: Query\n```\nAccess to this feature service is restricted (i.e., it is not shared to \"Everyone\" in ArcGIS Online). Because the user that requested the token *does* have access to read and modify this feature service, they are able to access the feature service and its metadata, as well as make changes to the data. Learn more about how access to items is managed in ArcGIS Online [here](https://doc.arcgis.com/en/arcgis-online/share-maps/share-items.htm).\n\n::: {.cell}\n\n```{.r .cell-code}\n# use sf to project new data to the same crs as flyr\nsfdataprj <- st_transform(sfdata, st_crs(flyr))\n\n# use arcgis to add the new features\nadd_res <- add_features(flyr, sfdataprj)\ntail(add_res)\n```\n:::\n\n```\n    objectId uniqueId globalId success\n926     9287     9287       NA    TRUE\n927     9288     9288       NA    TRUE\n928     9289     9289       NA    TRUE\n929     9290     9290       NA    TRUE\n930     9291     9291       NA    TRUE\n931     9292     9292       NA    TRUE\n```\nThe result of the `add_features()` function provides fine-grained information about the success (or failure) of the feature additions. Here, all 931 new features were successfully added to the feature service. If you were running this process as an automated script, you may want to capture and log any features that failed.\n",
+    "supporting": [
+      "using-arcgis-arcgisbinding_files"
+    ],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {},
+    "preserve": {},
+    "postProcess": true
+  }
+}

_quarto.yml

@@ -30,6 +30,7 @@ website:
           - location-services/publishing.qmd
           - location-services/workflows/add-delete-update.qmd
           - location-services/workflows/overwrite-feature-service.qmd
+          - location-services/workflows/using-arcgis-arcgisbinding.qmd
           - section: Tutorials
             contents:
               - location-services/tutorials/shiny-dash/index.qmd

location-services/gallery.yml

@@ -28,6 +28,11 @@
       href: https://r.esri.com/r-bridge-site/location-services/workflows/overwrite-feature-service.html
       code: workflows/overwrite-feature-service.qmd
       thumbnail: images/gallery-overwrite.png
+    - title: Using arcgis with arcgisbinding
+      subtitle: Create workflows that use multiple R-ArcGIS Bridge packages
+      href: https://r.esri.com/r-bridge-site/location-services/workflows/using-arcgis-arcgisbinding.html
+      code: workflows/using-arcgis-arcgisbinding.qmd
+      thumbnail: images/gallery-multiple.png
 
 
 - category: Tutorials

location-services/workflows/using-arcgis-arcgisbinding.qmd

@@ -0,0 +1,181 @@
+---
+title: "Using `arcgis` with `arcgisbinding`"
+subtitle: "Combining the two packages for workflows that span ArcGIS Pro and ArcGIS location services"
+freeze: true
+--- 
+
+```{r include = FALSE}
+knitr::opts_chunk$set(eval = FALSE)
+```
+
+While both are components of the R-ArcGIS Bridge, `arcgis` and `arcgisbinding` serve distinct purposes: 
+
+- `arcgis` *bridges* to ArcGIS location services, enabling web-based workflows from R
+- `arcgisbinding` *binds* to ArcGIS Pro, enabling data i/o and other desktop software-based processes from R
+
+However, there may be instances where you want to combine the functionality of these two R packages in a single workflow. The below code samples demonstrate how these packages can be used together, as well as alongside popular spatial R packages like `terra` and `sf`.
+
+## Extract imagery of the Ouarkziz crater
+
+This sample shows how to extract and resample multispectral Landsat imagery from ArcGIS Living Atlas using `arcgis` and `arcgisbinding`. Both packages also work with `terra`, so you can easily plot, write, and integrate with other R-based raster analysis workflows.
+
+
+```{r message = FALSE}
+# install.packages('arcgis')
+
+library(terra)
+library(raster)
+library(arcgis)
+library(arcgisbinding)
+arc.check_product()
+```
+```
+product: ArcGIS Pro (13.2.0.49743)
+license: Advanced
+version: 1.0.1.306 
+```
+
+```{r}
+# ArcGIS Living Atlas Landsat2 imagery service URL 
+rurl <- "https://landsat2.arcgis.com/arcgis/rest/services/Landsat/MS/ImageServer"
+
+# use arcgis to extract the natural color imagery
+img_srv <- arc_open(rurl)
+img_srv
+```
+```
+<ImageServer <11 bands, 26 fields>>
+Name: Landsat/MS
+Description: Multispectral Landsat image service covering the lan
+Extent: -20037507.07 20037507.84 -9694091.07 9691188.93 (xmin, xmax, ymin, ymax)
+Resolution: 30 x 30
+CRS: 3857
+Capabilities: Catalog,Image,Metadata
+```
+```{r}
+img <- arc_raster(
+  img_srv,
+  "-846028", # xmin
+  "-833783", # xmax
+  "3373101", # ymin
+  "3380738", # ymax
+)
+img
+```
+```
+class       : SpatRaster 
+dimensions  : 400, 400, 11  (nrow, ncol, nlyr)
+resolution  : 30.6125, 30.6125  (x, y)
+extent      : -846028, -833783, 3370797, 3383042  (xmin, xmax, ymin, ymax)
+coord. ref. : WGS 84 / Pseudo-Mercator (EPSG:3857) 
+source      : x_____xTRXJxJ6XbIPSrPxM-nRAvA..x_____x_ags_8564ca38_5048_4d92_ad3e_750f12824416.tif 
+names       : Coast~rosol, Blue, Green, Red, NearInfrared, Short~red_1, ... 
+```
+
+```{r}
+# use terra to view the imagery
+plotRGB(img, stretch = "lin")
+```
+![](images/ouarkziz-crater-RGB.png)
+```{r}
+# use arcgisbinding to resample and view SWIR
+bbox <- c(-846028, # xmin
+          3373101, # ymin
+          -833783, # xmax
+          3380738) # ymax
+resampled <- arc.raster(arc.open(rurl), bands=1, nrow=300, ncol=300, resample_type="CubicConvolution", extent=bbox)
+swir <- as.raster(resampled)
+plot(swir)
+```
+![](images/ouarkziz-crater-SWIR.png)
+```{r}
+# use terra to write out the natural color & SWIR rasters
+writeRaster(img, "ouarkziz-crater-RGB.tif", overwrite=TRUE)
+writeRaster(swir, "ouarkziz-crater-SWIR.tif", overwrite=TRUE)
+```
+
+Data Source: [Multispectral Landsat](https://www.arcgis.com/home/item.html?id=d9b466d6a9e647ce8d1dd5fe12eb434b) 
+
+[Learn more about the Ouarkziz crater in Algeria.](https://earthobservatory.nasa.gov/images/77851/ouarkziz-impact-crater-algeria)
+
+
+## Use local data to update an ArcGIS Online feature service
+
+Imagine that you are in charge of maintaining a feature service for your organization that needs to be updated on a regular basis. To avoid dealing with tedious and error-prone manual updates, you can use a scheduled R script to make these updates automatically.
+
+In this example, the user maintains an ArcGIS Online feature service containing data representing fatal car accidents in Missouri. Periodically, the user receives data updates in a file geodatabase. The workflow below uses `arcgisbinding` to read the feature class into R and convert it to an `sf` object. Then, `arcgis` uses the `sf` object to add the new features to the feature service.
+
+```{r message = FALSE}
+library(sf)
+library(arcgis)
+library(arcgisbinding)
+arc.check_product()
+```
+```
+product: ArcGIS Pro (13.2.0.49743)
+license: Advanced
+version: 1.0.1.306 
+```
+```{r}
+# use arcgisbinding to read in feature class
+fcpath = "C:\\Data\\FARS_update.gdb\\FARS_2021"
+fc <- arc.open(fcpath)
+fc
+```
+```
+dataset_type    : FeatureClass
+path            : C:\Data\FARS_update.gdb\FARS_2021 
+fields          : OBJECTID, Shape, state, statename, st_case, 
+fields          : peds, pernotmvit, ve_total, ve_forms, pvh_invl, 
+fields          : persons, permvit, county, countyname, city, 
+fields          : cityname, month, monthname, day, dayname, 
+          ... Truncated ...
+extent          : xmin=-162.5944, ymin=17.96028, xmax=-65.65091, ymax=66.89788
+geometry type   : Point
+WKT             : GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984"...
+WKID            : 4326 
+```
+
+```{r}
+# use arcgisbinding to filter data to Missouri and convert to sf
+sqlquery <- "STATENAME = 'Missouri'"
+fcdata <- arc.select(fc, where_clause=sqlquery)
+sfdata <- arc.data2sf(fcdata) # project to 3857
+
+# use arcgis to set token
+token <- auth_binding()
+set_arc_token(token)
+```
+In this case, the token is set using the active portal in ArcGIS Pro (via `{arcgisbinding}`). Note that other [authorization methods](../connecting-to-a-portal.qmd) could be used here, such as `auth_code()` or `auth_user()`.
+```{r eval}
+# use arcgis to access feature service
+fsurl <- "https://services1.arcgis.com/hLJbHVT9ZrDIzK0I/arcgis/rest/services/Fatal_Vehicle_Accidents_in_Missouri/FeatureServer/0"
+flyr <- arc_open(fsurl)
+flyr
+```
+```
+<FeatureLayer>
+Name: Missouri_Fatal_Accidents
+Geometry Type: esriGeometryPoint
+CRS: 3857
+Capabilities: Query
+```
+Access to this feature service is restricted (i.e., it is not shared to "Everyone" in ArcGIS Online). Because the user that requested the token *does* have access to read and modify this feature service, they are able to access the feature service and its metadata, as well as make changes to the data. Learn more about how access to items is managed in ArcGIS Online [here](https://doc.arcgis.com/en/arcgis-online/share-maps/share-items.htm).
+```{r message = FALSE}
+# use sf to project new data to the same crs as flyr
+sfdataprj <- st_transform(sfdata, st_crs(flyr))
+
+# use arcgis to add the new features
+add_res <- add_features(flyr, sfdataprj)
+tail(add_res)
+```
+```
+    objectId uniqueId globalId success
+926     9287     9287       NA    TRUE
+927     9288     9288       NA    TRUE
+928     9289     9289       NA    TRUE
+929     9290     9290       NA    TRUE
+930     9291     9291       NA    TRUE
+931     9292     9292       NA    TRUE
+```
+The result of the `add_features()` function provides fine-grained information about the success (or failure) of the feature additions. Here, all 931 new features were successfully added to the feature service. If you were running this process as an automated script, you may want to capture and log any features that failed.