1_download.Rmd

---
title: "Download GBIF occurrences"
author:
- Damiano Oldoni
- Peter Desmet
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_depth: 3
    toc_float: true
    number_sections: true
---

In this document we download occurrences for Europe from [GBIF](https://www.gbif.org). We limit the search to the species selected for risk assessment analysis and modelling.

# Setup

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning = FALSE, message = FALSE)
```

Load libraries:

```{r load_libraries_download_eu}
library(tidyverse)      # To do data science
library(lubridate)      # To work with dates
library(here)           # To find files
library(rgbif)          # To use GBIF services
library(trias)          # To use functions developed for TrIAS
library(sf)             # To work with geometries
library(leaflet)        # To make interactive maps
```

# Define download query parameters

## Taxa

The species selected for modelling are saved in file `modelling_species.tsv` on GitHub (link with specific commit for traceability):

```{r load_modelling_species_file_eu}
taxa_input_file <- "https://raw.githubusercontent.com/trias-project/occ-cube-alien/6370a1aacb0defd22ccb30ee461b75c24a0f5c1b/references/modelling_species.tsv"
taxa <- read_tsv(taxa_input_file,
                 na = "")
```

Preview file:

```{r preview_taxa_modelling}
head(taxa)
```
Number of taxa:

```{r n_taxa}
nrow(taxa)
```

Retrieve the `taxonKey`s we want to use to download occurrences:

```{r get_taxonkeys_modelling}
taxon_keys <- taxa$backbone_taxonKey # Column with taxonKeys
```

## Bounding box

We define a bounding box which contains the geographic Europe as defined by European Environment Agency reference grids. See image in `./references/Europe.png`.

```{r define_bounding_box_modelling}
bounding_box_europe <- "POLYGON((-27.33398 67.06055, -11.68945 34.89258, 24.3457 29.0918, 40.86914 33.83789, 45.90088 37.02393, 43.1543 48.7793, 37.79297 57.12891, 34.27734 75.76172, -15.99609 76.46484, -27.33398 67.06055))"
```

Preview of the selected area:

```{r preview_bounding_box_europe}
sf_bounding_box_europe <- 
  st_as_sfc(bounding_box_europe, crs = 4326) %>%
  st_coordinates() %>%
  as.data.frame()
leaflet() %>%
  addTiles() %>%
  addPolygons(lng = sf_bounding_box_europe$X, 

                            lat = sf_bounding_box_europe$Y)
```

## Basis of record

All types of occurrences, except `FOSSIL SPECIMEN` and `LIVING SPECIMEN`, which can have misleading location information (e.g. location of captive animal).

```{r define_basis_of_record_eu}
basis_of_record <- c(
  "OBSERVATION", 
  "HUMAN_OBSERVATION",
  "MATERIAL_SAMPLE", 
  "LITERATURE", 
  "PRESERVED_SPECIMEN", 
  "UNKNOWN", 
  "MACHINE_OBSERVATION"
)
```

## Year

Occurrences with a valid year:

```{r define_year_eu}
year_begin <- 1000
year_end <- year(Sys.Date())
```

## Geographic coordinates

Occurrences with valid geographic coordinates:

```{r define_hasCoordinate_eu}
hasCoordinate <- TRUE
```

# Download GBIF occurrences

## Trigger download

**Note**: GBIF credentials are required in the next step. 

Trigger download:

```{r trigger_gbif_download_eu}
# Reuse existing download (comment to trigger new download)
gbif_download_key <- "0036191-231002084531237"

# Trigger new download (commented by default)
# gbif_download_key <- occ_download(
#   pred_in("taxonKey", taxon_keys),
#   pred_within(bounding_box_europe),
#   pred_in("basisOfRecord", basis_of_record),
#   pred_gte("year", year_begin),
#   pred_lte("year", year_end),
#   pred("hasCoordinate", hasCoordinate),
#   user = rstudioapi::askForPassword("GBIF username"),
#   pwd = rstudioapi::askForPassword("GBIF password"),
#   email = rstudioapi::askForPassword("Email address for notification")
# )
```

## Check status of download

```{r check_metadata_eu}
metadata <- occ_download_meta(key = gbif_download_key)
metadata$key
metadata$status
```

Write download to list of downloads and check pending downloads:

```{r update_download_list_eu}
update_download_list(
  file = here::here("data", "raw", "gbif_downloads.tsv"), 
  download_to_add = gbif_download_key, 
  input_checklist = taxa_input_file
)
```