---
title: "TerraClimate"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{TerraClimate}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

Spatial data on several climate variables, extracted from Climatology Lab's [TerraClimate](https://www.climatologylab.org/terraclimate.html). The table below shows all possible variables to be extracted, which are chosen through the "dataset" parameter. Data ranges from 1958 to 2020.

Netcdf files are downloaded from the [THREDDS](http://thredds.northwestknowledge.net:8080/thredds/terraclimate_catalog.html) web server, as recommended for rectangular subsets of the global data.

<details>
<summary>
Click to see all dataset options
</summary>
| Dataset | Code | Description | Units |
|:--------|:----:|:------------|:-----:|
| max_temperature | tmax | Maximum 2-m Temperature | degC |
| min_temperature | tmin | Minimum 2-m Temperature | degC |
| wind_speed | ws   | Wind Speed at 10-m | m/s |
| vapor_pressure_deficit | vpd  | Vapor Pressure Deficit | kPa |
| vapor_pressure | vap | 2-m Vapor Pressure | kPa |
| snow_water_equivalent | swe  | Snow Water Equivalent at End of Month | mm |
| shortwave_radiation_flux | srad | Downward Shortwave Radiation Flux at the Surface | W/m^2 |
| soil_moisture | soil | Soil Moisture at End of Month | mm
| runoff | q    | Runoff | mm |
| precipitation | ppt  | Accumulated Precipitation | mm |
| potential_evaporation | pet  | Reference Evapotranspiration | mm |
| climatic_water_deficit | def  | Climatic Water Deficit | mm |
| water_evaporation | aet  | Actual Evapotranspiration | mm |
| palmer_drought_severity_index | PDSI | Palmer Drought Severity Index | unitless |
</details>

***

**Options:**

  1. **dataset**: picks the variable to be read. Possible options are shown in the table above.

  2. **raw_data**: there are two options:
      * `TRUE`: if you want the data as it is originally.
      * `FALSE`: if you want the treated version of the data. 
  
  3. **time_period**: picks the years for which the data will be downloaded

  4. **language**: you can choose between Portuguese `("pt")` and English `("eng")`
  
  5. **legal_amazon_only**: if set to `TRUE`, only downloads data from the Legal Amazon region
  
  OBS: A good internet connection is needed, because the data is heavy.
  
***

**Examples:**

```{r, eval=FALSE}
# Downloading maximum temperature data from 2000 to 2001
max_temp <- load_climate(dataset = "max_temperature", time_period = 2000:2001)

# Downloading precipitation data only for the legal Amazon in 2010
amz_precipitation <- load_climate(
  dataset = "precipitation",
  time_period = 2010,
  legal_amazon_only = TRUE
)
```