This vignette will provide a worked example of accessing and downloading the burn grading submissions, and calculating the OzCBI from the raw data.
Request an ODK Central account here. You will receive a registration email. Your username will be your email address, you can choose your own password. With those credentials, you have read access to ODK Central, the place where burn grading submissions are uploaded to.
This step is required only once for every data analyst.
For details, refer to ruODK vignette “setup”.
Set default credentials and settings to simplify work with
ruODK later. Credentials live as environment variables in
your .Renviron file. Changes to .Renviron
require a restart of the R session.
usethis::edit_r_environ()
# Paste with your credentials
ODKC_URL <- "https://odkc.dbca.wa.gov.au"
ODKC_UN <- "YOUR_EMAIL"
ODKC_PW <- "YOUR_PASSWORD"
ODKC_PID <- 4
ODKC_FID <- "FMS-verify-severity"
# Save .Renviron and restart your R session.Since we’ll only work with one form and have set the necessary
settings as defaults, ruODK will default to our form
without any further ado.
If you need to navigate between forms, you can set up
ruODK with the respective OData service URL:
# ODK Central's OData URL contains base URL, project ID, and form ID
# ODK Central credentials can live in .Renviron, see vignette "setup"
ruODK::ru_setup(
svc = paste0(
"https://odkc.dbca.wa.gov.au/v1/projects/4/",
"forms/FMS-verify-severity.svc"
),
un = Sys.getenv("ODKC_UN"),
pw = Sys.getenv("ODKC_PW")
)For an overview on accessing data from ODK Central, read the ODK Central docs.
For a background on accessing data from R, refer to ruODK vignette “odata-api”.
In a pinch, we can always download a ZIP archive of all submissions and all photos from ODK Central.
Here, we’ll use ruODK to download submissions from ODK
Central with verbose output.
bgf <- ruODK::odata_submission_get(
verbose = F,
tz = "Australia/Perth",
local_dir = fs::path("media"),
wkt = T
)Task: Parse raw data into numeric scale values, apply OzCBI formula.
Values are coded as numbers 0.0, 0.5, 1.0, 1.5 through to 3.0.
Fraction of coverages (fcov) also are prefixed with their grade, which
ranges from 0.0 to 1.0 in increments of 0.25. Each grade is three digits
(two decimals). extract_grading() extracts the numerical
grade from these character values.
The function add_ozcbi_forest() is highly specific to
the underlying form “Burn Grading Forest”. It translates the form fields
to the generic form calculate_ozcbi_forest(), which can be
fed by data from any other compatible data source.
bg_ozcbi <- bgf %>% add_ozcbi_forest()The data shown here are test data (not real burn gradings) and come from the real form.
The helper function map_ozcbi_forest() provides a
leaflet map with labels and popups. The source code of
map_ozcbi_forest() can serve as a starting point for other
customised maps.
bg_ozcbi %>% map_ozcbi_forest()Note This section is pending review and refinement. Currently, this is a manual process happening outside of R. We could imagine to integrate that process into this package as follows.