Environmental readings and detections • temploapiclient

Initial Setup and Api Credentials

Please see station_and_receptors for further details about how to make available the showcased package temploapiclient to this vignette.

project_folder <- dirname(getwd())
path_to_env <- file.path(project_folder, ".env")
readRenviron(path_to_env)
api_base_url <- Sys.getenv("API_BASE_URL")
api_headers <- list("Accept" = "application/json", "Content-type" = "application/json")
api_auth_token <- Sys.getenv("AUTH_TOKEN")
if (!length(api_auth_token)) {
  api_auth_token <- NULL
}

templo_client <- temploapiclient::TemploApiClient$new(api_base_url, api_headers, api_auth_token)
library("magrittr") # Make '%>%' available throughout the vignette

Fetching environmental readings

Deployed receptors are equipped with sensors that measure oceanographic variables such as temperature, pressure, etc… Such readings can be obtained from the API too. Readings are generate with a very fine time resolution, so it is advised to fetch two o three days worth of data at the time. Otherwise, the API call may time out and result in an error.

In the example below we are fetching three days worth of data for 10th, 11th and 12th October 2024. We are just selecting and renaming a few fields for showcasing purposes.

api_data <- templo_client$get_environmental_readings(from_date = "2024-10-10", to_date = "2024-10-12")
#> INFO [2024-11-14 17:08:07] Fetching environmental readings from  2024-10-10 to 2024-10-12 ... This may take a few seconds
#> INFO [2024-11-14 17:08:10] --->Finished
head(api_data) %>%
  dplyr::rename(c(
    variable = environmental_variable_name,
    receptor = receptor_name,
    station = station_name,
    lat = latitude,
    lon = longitude
  )) %>%
  dplyr::select(
    station,
    receptor,
    lat,
    lon,
    variable,
    reading_time,
    value
  )
#>   station receptor     lat       lon  variable        reading_time value
#> 1    Cíes     Cíes 42.2107 -8.898333 FREQUENCY 2024-10-10 00:09:42    69
#> 2    Cíes     Cíes 42.2107 -8.898333 FREQUENCY 2024-10-10 00:19:42    69
#> 3    Cíes     Cíes 42.2107 -8.898333 FREQUENCY 2024-10-10 00:29:42    69
#> 4    Cíes     Cíes 42.2107 -8.898333 FREQUENCY 2024-10-10 00:39:42    69
#> 5    Cíes     Cíes 42.2107 -8.898333 FREQUENCY 2024-10-10 00:49:42    69
#> 6    Cíes     Cíes 42.2107 -8.898333 FREQUENCY 2024-10-10 00:59:42    69

We could hit an interval of time when no data was produced so an empty dataset will be returned instead.

api_data <- templo_client$get_environmental_readings(from_date = "2024-01-01", to_date = "2024-02-02")
#> INFO [2024-11-14 17:08:10] Fetching environmental readings from  2024-01-01 to 2024-02-02 ... This may take a few seconds
#> INFO [2024-11-14 17:08:10] --->Finished
api_data %>%
  assertr::verify(!nrow(.))
#> # A tibble: 0 × 0

Fetching detections

Detections emitted by the sensors fitted in the tags that are surgically inserted into individuals read oceanographic variables too. Similar to environmental readings, detections should be downloaded in small chunks to avoid the API timing out and producing no results. In the results below we have massaged the data to provide contextual column names and trimmed those detections that produced no value.

api_data <- templo_client$get_dataframe_end_point(end_point = "detections/data_exports/", parameters = list(
  format = "json", # this parameters, for our purposes needs no change.
  from_date = "2024-10-02",
  to_date = "2024-10-03"
))
#> INFO [2024-11-14 17:08:10] Fetching data from api... This may take a few seconds
#> INFO [2024-11-14 17:08:12] --->Finished
api_data %>%
  dplyr::mutate(detection_value = as.numeric(detection_value)) %>%
  dplyr::filter(assertr::not_na(detection_value)) %>%
  dplyr::select(
    sensor_id,
    sensor_name,
    individual_tag,
    tag_model,
    scientific_name,
    station_name,
    receptor_name,
    detection_time,
    detection_value
  ) %>%
  dplyr::rename(c(
    id = sensor_id,
    sensor = sensor_name,
    individiual_id = individual_tag,
    station = station_name,
    receptor = receptor_name,
    time = detection_time,
    value = detection_value
  )) %>%
  head()
#>     id      sensor individiual_id tag_model scientific_name station receptor
#> 1 1155    PRESSURE MOVE-RUN-23-32  03EX1155   Raja undulata    Cíes     Cíes
#> 2 1156 TEMPERATURE MOVE-RUN-23-32  03EX1156   Raja undulata    Cíes     Cíes
#> 3 1100 TEMPERATURE MOVE-RUN-23-11  03E51100   Raja undulata    Cíes     Cíes
#> 4 1151    PRESSURE MOVE-RUN-23-30  03EV1151   Raja undulata    Cíes     Cíes
#> 5 1152 TEMPERATURE MOVE-RUN-23-30  03EV1152   Raja undulata    Cíes     Cíes
#> 6 1196 TEMPERATURE MOVE-RUN-23-02  03FH1196   Raja undulata    Cíes     Cíes
#>                  time value
#> 1 2024-10-03 22:48:46    23
#> 2 2024-10-03 22:02:21   157
#> 3 2024-10-03 21:38:23   160
#> 4 2024-10-03 21:18:49  4095
#> 5 2024-10-03 20:59:59   159
#> 6 2024-10-03 20:40:53   159