In dbca-wa/ruODK: An R Client for the ODK Central API

usethis::edit_r_environ()

# ODK Central web user with read-permitted role on project
ODKC_UN <- "my@email.com"
ODKC_PW <- "my-odkc-password"

# CKAN user with permissions to create a dataset
CKAN_URL <- "https://demo.ckan.org"
CKAN_KEY <- "my-ckan-api-key"

knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
# Data wrangling
# library(stringr)
library(dplyr)
library(fs)
library(ruODK)

# Visualisation
# require(skimr)
library(knitr)
# library(DT)

# Dissemination
library(readr)
# library(ckanr)
# library(googledrive)

# Spatial: see also vignette "spatial"
library(leaflet)
# library(rgeos)
# library(sf)

# Set ruODK defaults to an ODK Central form's OData Service URL
ruODK::ru_setup(
  svc = paste0("https://my-odkc-instance.com/v1/projects/1/forms/form_id.svc"),
  tz = "Australia/Perth", # your local timezone
  odkc_version = "2023.5.1", # your ODKC version, only needed for older versions
  verbose = TRUE
)

loc <- fs::path("media")
fs::dir_create(loc)

Download data

ft <- ruODK::odata_service_get()
ft %>% knitr::kable(.)

data <- ruODK::odata_submission_get(
  table = ft$url[1],
  local_dir = loc,
  wkt = TRUE
)

data_sub1 <- ruODK::odata_submission_get(
  table = ft$url[2],
  local_dir = loc
) %>%
  dplyr::left_join(
    data,
    by = c("submissions_id" = "id")
  )

data_sub2 <- ruODK::odata_submission_get(
  table = ft$url[3],
  local_dir = loc
) %>%
  dplyr::left_join(
    data,
    by = c("submissions_id" = "id")
  )

# repeat for any remaining nested tables

Analyse and visualise data

dplyr::glimpse(data)

For the next examples, have skimr and DT installed.

skimr::skim(data)

DT::datatable(head(data))

leaflet::leaflet(width = 800, height = 600) %>%
  leaflet::addProviderTiles("OpenStreetMap.Mapnik", group = "Place names") %>%
  leaflet::addProviderTiles("Esri.WorldImagery", group = "Aerial") %>%
  leaflet::clearBounds() %>%
  leaflet::addAwesomeMarkers(
    data = data,
    #
    # # Adjust to your coordinate field names
    #
    lng = ~location_longitude,
    lat = ~location_latitude,
    icon = leaflet::makeAwesomeIcon(text = "Q", markerColor = "red"),
    #
    # # With your own field names
    #
    # label = ~ glue::glue("{location_area_name} {encounter_start_datetime}"),
    # popup = ~ glue::glue(
    #   "<h3>{location_area_name}</h3>",
    #   "Survey start {encounter_start_datetime}</br>",
    #   "Reporter {reporter}</br>",
    #   "Device {device_id}</br>",
    #   "<h5>Site</h5>",
    #   '<div><img src="{habitat_morphological_type_photo}"',
    #   ' height="150px" alt="My photo"></img></div>'
    # ),
    #
    # # If there are many submissions, cluster markers for performance:
    clusterOptions = leaflet::markerClusterOptions()
  ) %>%
  leaflet::addLayersControl(
    baseGroups = c("Place names", "Aerial"),
    options = leaflet::layersControlOptions(collapsed = FALSE)
  )

Export

<!-- The form submissions are now extracted and visualised. What's next:

Save data to local files (e.g. CSV).
Compile report (e.g. to HTML).
Compress all outputs as ZIP.
Upload these artifacts to a CKAN data catalogue.
Upload same artifacts to Google Drive.

Notes:

Generate the HTML report once off without the next chunk (eval=F), as the chunk refers to the rendered output file (HTML) before the file is created initially.
Run report always twice to generate (run 1) and upload (run 2) the latest HTML. -->

#------------------------------------------------------------------------------#
# Prepare report and products as local files
#
rep_fn <- "my_report.html" # The file name you save this template under
data_fn <- here::here(loc, "data.csv") %>% as.character() # Main data
data_sub1_fn <- here::here(loc, "data_sub1.csv") %>% as.character() # Sub tbl 1
data_sub2_fn <- here::here(loc, "data_sub2.csv") %>% as.character() # Sub tbl 2
zip_fn <- "products.zip" # Attachments as one zip file (top level)

# Write data tbls to CSV files
readr::write_csv(data, path = data_fn)
readr::write_csv(data_sub1, path = data_sub1_fn)
readr::write_csv(data_sub2, path = data_sub2_fn)

# Compress everything into `zip_fn`, retain relative path to `loc`
zip(zipfile = zip_fn, files = fs::dir_ls(loc))

#------------------------------------------------------------------------------#
# CKAN
#
# Upload to a CKAN data catalogue
# Needs CKAN_URL and API CKAN_KEY with org editor permissions
# See https://docs.ropensci.org/ckanr/
ckanr::ckanr_setup(url = Sys.getenv("CKAN_URL"), key = Sys.getenv("CKAN_KEY"))
ckan_ds_name <- "my-ckan-dataset-slug"

# Run once to create resources on an existing dataset, then comment out
d <- ckanr::package_show(ckan_ds_name)
res_data_main <- ckanr::resource_create(
  package_id = d$id, name = "Main data", upload = data_fn
)
res_data_sub1 <- ckanr::resource_create(
  package_id = d$id, name = "Nested data table 1", upload = data_sub1_fn
)
res_data_sub2 <- ckanr::resource_create(
  package_id = d$id, name = "Nested data table 2", upload = data_sub2_fn
)
# add remaining tables
if (fs::file_exists(rep_fn)) {
  res_report <- ckanr::resource_create(
    package_id = d$id, name = "Data report", upload = rep_fn
  )
}

if (fs::file_exists(zip_fn)) {
  res_zip <- ckanr::resource_create(
    package_id = d$id, name = "All data and attachments", upload = zip_fn
  )
}
# Paste res_data_main$id over RID and keep here, repeat for each resource
r <- ckanr::resource_update(res_data_main$id, path = data_fn)
r <- ckanr::resource_update(res_data_sub1$id, path = data_sub1_fn)
r <- ckanr::resource_update(res_data_sub2$id, path = data_sub2_fn)
if (fs::file_exists(rep_fn)) {
  r <- ckanr::resource_update(res_report$id, path = rep_fn)
}
r <- ckanr::resource_update(res_zip$id, path = zip_fn)

#------------------------------------------------------------------------------#
# Google Drive
#
# Run once per machine, then comment out:
googledrive::drive_auth(use_oob = TRUE)

# Upload to Google Drive
gd_fn <- "My Google Drive folder name"
googledrive::drive_ls(gd_fn) %>% googledrive::drive_rm(.) # Wipe older outputs
if (fs::file_exists(rep_fn)) {
  googledrive::drive_upload(rep_fn, path = rep_fn) # Report as HTML
}
googledrive::drive_upload(data_fn, path = data_fn) # Main data as CSV
googledrive::drive_upload(data_sub1_fn, path = data_sub1_fn) # Sub table 1 as CSV
googledrive::drive_upload(data_sub2_fn, path = data_sub2_fn) # Sub table 2 as CSV
googledrive::drive_upload(zip_fn, path = zip_fn) # All outputs as ZIP