---
title: "TerraClimate Example"
author: "Khaled Al-Shamaa"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{TerraClimate Example}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## QBMS
This R package assists breeders in linking data systems with their analytic pipelines, a crucial step in digitizing breeding processes. It supports querying and retrieving phenotypic and genotypic data from systems like [EBS](https://ebs.excellenceinbreeding.org/), [BMS](https://bmspro.io/), [BreedBase](https://breedbase.org), and [GIGWA](https://github.com/SouthGreenPlatform/Gigwa2) (using [BrAPI](https://brapi.org/) calls). Extra helper functions support environmental data sources, including [TerraClimate](https://www.climatologylab.org/terraclimate.html) and FAO [HWSDv2](https://gaez.fao.org/pages/hwsd) soil database.

## TerraClimate
[TerraClimate](https://www.climatologylab.org/terraclimate.html) is a dataset of monthly climate and climatic water balance for global terrestrial surfaces from 1958-2019. These data provide important inputs for ecological and hydrological studies at global scales that require high spatial resolution and time-varying data. All data have monthly temporal resolution and a ~4-km (1/24th degree) spatial resolution. The data cover the period from 1958-2020. We plan to update these data periodically (annually).

[TerraClimate](https://www.climatologylab.org/terraclimate.html) is a climate and climatic water balance dataset of [14 variables](https://www.climatologylab.org/terraclimate-variables.html) for global terrestrial surfaces from 1958 to 2022 (updated annually) comparing to 7 climate variables for 1970-2000 in [WorldClim dataset](https://www.worldclim.org/data/worldclim21.html). All data have monthly temporal resolution and a ~4-km (1/24th degree) spatial resolution.

You can retrieve TerraClimate data using the QBMS R package in two modes, Online using API calls (minimizing download size), or Offline by downloading required NetCDF rasters first (minimizing query time). QBMS also calculate the 19 derivatives [bioclimatic variables](https://www.worldclim.org/data/bioclim.html) on-fly.

> ### Reference:
> Abatzoglou, J., Dobrowski, S., Parks, S. et al. TerraClimate, a high-resolution global dataset of monthly climate and climatic water balance from 1958–2015. Sci Data 5, 170191 (2018). [https://doi.org/10.1038/sdata.2017.191](https://doi.org/10.1038/sdata.2017.191)

## _Example_
```r
# load the QBMS library
library(QBMS)

# ICARDA Tal-Hadya station, Syria
data <- get_terraclimate(36.016, 36.943, '1979-09-01', '2012-06-30')

View(data$climate[[1]])

View(data$biovars[[1]])

# 1. ICARDA Merchouch station, Morocco
# 2. ICARDA Terbol station, Lebanon
# 3. ICARDA Amlaha station, India

x <- c(-6.716, 35.917, 76.884)
y <- c(33.616, 33.833, 23.111)

# ICARDA stations (WorldClim temporal range)
worldclim_range <- get_terraclimate(y, x, '1970-01-01', '2000-12-31', c('ppt', 'tmin', 'tmax'))

# ?calc_biovars
worldclim_norm  <- apply(worldclim_range$biovars[[2]][,1:19], 2, function(x) round(mean(x), 1))

# biovars       bio1   bio2   bio3   bio4   bio5   bio6   bio7   bio8   bio9  bio10  bio11
# terraclimate  16.2   13.5   41.4   713.5  33.8   1.0    32.8   8.0    24.3  24.5   7.4
# worldclim/10  15.5   13.6   43.0   631.0  33.0   1.6    31.4   7.3    23.2  23.2   7.3
#
# NOTE: all worldcim biovars derivative from temperature (i.e., bio1-bio11) have a scale factor of 10 
#       except bio3 because it is a ratio.
#
# biovars(cont) bio12  bio13  bio14  bio15  bio16  bio17  bio18  bio19
# terraclimate  661.0  182.1  0.0    113.5  419.2  0.3    0.9    398.5
# worldclim     592.0  140.0  0.0    99.0   368.0  1.0    2.0    368.0

```

## _Offline Mode_

Download TerraClimate netCDF data files:

```r
# ?ini_terraclimate
ini_terraclimate('2018-09-01', '2019-06-30', c('ppt', 'tmin', 'tmax'))

# Get TerraClimate data for a given coordinate(s)
data <- get_terraclimate(y, x, '2018-09-01', '2019-06-30', c('ppt', 'tmin', 'tmax'), offline = TRUE)

```

_If you encounter a timeout error during the execution of the `ini_terraclimate()` function, you can extend the timeout duration of your environment with the following command (e.g., to 5 minutes, which is 300 seconds, instead of the default 60 seconds):_

```r
options(timeout = max(300, getOption("timeout")))
```

_The default timeout of 60 seconds is often not sufficient for downloading large files (over 50 MB). Additionally, expecting download times of less than 1MB per second is unrealistic._