In dbca-wa/rGeoCBI: A Burn Severity Assessment Toolkit for Austral Vegetation Communities

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(rOzCBI)
library(ruODK)
library(magrittr)
library(leaflet)
library(reactable)

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

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.

Setup ruODK

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")
)

Download data

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
)

data("bgf")

Calculate OzCBI

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()

Visualise

The data shown here are test data (not real burn gradings) and come from the real form.

Map

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()

Table

Each row expands to show details.

bg_ozcbi %>% reactable_ozcbi_forest()

Calibrate dNBR

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.

Get Landsat/Sentinel imagery pre and post burn: ropenSci/getlandsat
Calculate NBR for each pre and post burn scene as $(NIR - SWIR) / (NIR + SWIR)$ see e.g. tutorial at earthdatascience.org
Calculate $dNBR = NBR_{post} / NBR_{pre}$
Annotate each burn grading ground truthing location with the dNBR at that site
Model $OzCBI = lm(dNBR)$
Predict modelled OzCBI for other sites