Add occurrences example vignette #25

Author: daxkellie

_pkgdown.yml

@@ -8,6 +8,8 @@ template:
     bootswatch: cerulean
 development:
   mode: release
+project: 
+  render: ['*.qmd']
 navbar:
   structure:
     left:
@@ -22,6 +24,11 @@ navbar:
     quickstart:
       text: Quick start guide
       href: articles/quick_start_guide.html
+    articles:
+      text: Examples
+      menu:
+      - text: Standardise occurrence-based data
+        href: articles/occurrence-example.html
     news:
       text: News
       href: news/index.html

vignettes/dummy-dataset-sb.xlsx

@@ -0,0 +1,122 @@
+---
+title: "Standardise an Occurrences dataset"
+author: "Dax Kellie & Martin Westgate"
+date: '2025-02-04'
+output:
+  rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Standardise an Occurrences dataset}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+Data of species observations is referred to as *occurrence* data. In Living Atlases like the Atlas of Living Australia (ALA), this is the default type of data stored. 
+
+Using occurrence-based datasets assume that all observations are independent of each other. The benefit of this assumption is that observational data can remain simple in structure - every observation is made at a specific place and time. This simplicity allows all occurrence-based data to be aggregated and used together. 
+
+Let's see how to build an occurrence-based dataset using galaxias.
+
+## The dataset
+
+Let's use an small example dataset of bird observations taken from 4 different site locations. This dataset has many different types of data like landscape type and age class. Importantly for standardising to Darwin Core, this dataset contains the scientific name (`species`), coordinate location (`lat` & `lon`) and date of observation (`date`).
+
+```{r}
+#| warning: false
+#| message: false
+library(galaxias)
+library(dplyr)
+library(readxl)
+
+obs <- read_xlsx("dummy-dataset-sb.xlsx",
+                 sheet = 1) |>
+  janitor::clean_names()
+
+obs |> 
+  gt::gt() |>
+  gt::opt_interactive(page_size_default = 5)
+```
+
+
+## Standardise to Darwin Core
+
+To determine what we need to do to standardise our dataset, let's use `suggest_workflow()`. The output tells us we have one matching Darwin Core term in our data already (`sex`), but we are missing all minimum required Darwin Core terms.
+
+```{r}
+obs |>
+  suggest_workflow()
+```
+
+The suggested workflow provided tells us which functions we can use to rename, modify or add columns that we're missing. `set_` functions are specialised wrappers around `dplyr::mutate()`, with additional functionality to support Darwin Core. 
+
+For simplicity, let's do the easy part first of renaming columns we already have in our dataset to use accepted standard Darwin Core terms. `set_` functions will check to make sure each column is correctly formatted. We'll save our modified dataframe as `obs_dwc`.
+
+```{r}
+obs_dwc <- obs |>
+  set_scientific_name(scientificName = species) |>
+  set_coordinates(decimalLatitude = lat,
+                  decimalLongitude = lon) |>
+  set_datetime(eventDate = lubridate::ymd(date)) # specify year-month-day format
+```
+
+Running `suggest_workflow()` again will reflect our progress and show us what's left to do. The output tells us that we still need to add several columns to our dataset to meet minimum Darwin Core requirements.
+
+```{r}
+obs_dwc |>
+  suggest_workflow()
+```
+
+Here's a rundown of the columns we need to add:
+
+  *  `occurrenceID`: Unique identifiers of each record. This ensures that we can identify the specific record for any future updates or corrections. We can use `random_id()`, `composite_id()` or `sequential_id()` to add this unique IDs our dataframe.
+  *  `basisOfRecord`: The type of record (e.g. human observation, specimen, machine observation). See a list of acceptable values with `corella::basisOfRecord_values()`.
+  *  `geodeticDatum`: The Coordinate Reference System (CRS) projection of your data (for example, the CRS of Google Maps is "WGS84").
+  *  `coordinateUncertaintyInMeters`: The area of uncertainty around your observation. You may know this value based on your method of data collection, or you can use `with_uncertainty()` to provide a default value based on the method used.
+
+Now let's add these columns using `set_occurrences()` and `set_coordinates()`. We can also add the suggested function `set_individual_traits()` which will automatically identify the matched column name `sex` and check the column's format.
+
+```{r}
+obs_dwc <- obs_dwc |>
+  set_occurrences(
+    occurrenceID = random_id(), # adds random UUID
+    basisOfRecord = "humanObservation"
+    ) |>
+  set_coordinates(
+    geodeticDatum = "WGS84",
+    coordinateUncertaintyInMeters = 30
+    # coordinateUncertaintyInMeters = with_uncertainty(method = "phone")
+    ) |>
+  set_individual_traits()
+```
+
+Running `suggest_workflow()` once more will confirm that our dataset is ready to be used in a Darwin Core Archive!
+
+```{r}
+obs_dwc |>
+  suggest_workflow()
+```
+
+To submit our dataset, let's select columns with valid occurrence term names and save this dataframe to the file `occurrences.csv`. Importantly, we will save our csv in a folder called `data-processed`, which galaxias looks for automatically when building a Darwin Core Archive.
+
+```{r}
+obs_dwc <- obs_dwc |>
+  select(any_of(occurrence_terms())) # select any matching terms
+
+obs_dwc |>
+  gt::gt() |>
+  gt::opt_interactive(page_size_default = 5)
+```
+
+```{r}
+#| eval: false
+# Save in ./data-processed
+write_csv(obs_dwc, file = "./data-processed/occurrences.csv")
+```
+
+All done! See the [Quick start guide vignette](quick_start_guide.html) for how to build a Darwin Core Archive.