Author: Khaled Al-Shamaa
Date: 2025-07-31

# TerraClimate Example

#### Khaled Al-Shamaa

#### 2025-07-31

## 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, BMS, BreedBase, and GIGWA (using BrAPI calls). Extra helper functions support environmental data sources, including TerraClimate and FAO HWSDv2 soil database.

## TerraClimate

TerraClimate 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 is a climate and climatic water balance dataset of 14 variables for global terrestrial surfaces from 1958 to 2022 (updated annually) comparing to 7 climate variables for 1970-2000 in WorldClim dataset. 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 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

## Example

    # 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:

    # ?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):

    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.