README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  warning = FALSE,
  message = FALSE
)

library(ggplot2)
```

# climateR <img src="man/figures/logo.png" width=230 align="right" />

[![Build Status](https://travis-ci.org/mikejohnson51/climateR.svg?branch=master)](https://travis-ci.org/mikejohnson51/climateR)     [![DOI](https://zenodo.org/badge/158620263.svg)](https://zenodo.org/badge/latestdoi/158620263)


`climateR` seeks to simplifiy the steps needed to get climate data into R. It currently provides access to the following gridded climate sources using a single parmaeter


|**Number**|**Dataset**          | **Description**                                            | **Dates**            |
|----------|---------------------| -----------------------------------------------------------|----------------------|
|1         | **GridMET**         | Gridded Meteorological Data.                               | 1979 - Yesterday     |
|2         | **Daymet**          | Daily Surface Weather and Climatological Summaries         | 1980 - 2019          |
|3         | **TopoWX**          | Topoclimatic Daily Air Temperature Dataset                 | 1948 - 2016          |
|4         | **PRISM**           | Parameter-elevation Regressions on Independent Slopes      | 1981 - (Yesterday-1) |
|5         | **MACA**            | Multivariate Adaptive Constructed Analogs                  | 1950 - 2099          |
|6         | **LOCA**            | Localized Constructed Analogs                              | 1950 - 2100          |
|7         | **BCCA**            | Bias Corrected Constructed Analogs                         | 1950 - 2100          |
|8         | **BCSD**            | Bias Corrected Spatially Downscaled VIC: Monthly Hydrology | 1950 - 2099          |
|9         | **TerraClimate**    | TerraClimate Monthly Gridded Data                          | 1958 - 2019          |
|10        | **TerraClimate Normals**    | TerraClimate Normals Gridded Data                  | Monthly for 1961-1990, 1981-2010, 2C & 4C |
|11        | **CHIRPS**          | Climate Hazards Group InfraRed Precipitation with Station  | 1980 - Current month |
|12        | **EDDI**            | Evaporative Demand Drought Index                           | 1980 - Current year  |


# Installation

```{r, eval = FALSE }
remotes::install_github("mikejohnson51/AOI") # suggested!
remotes::install_github("mikejohnson51/climateR")
```

# Usful Packages for climate data
```{r}
library(AOI)
library(climateR)
library(sf)
library(raster)
library(rasterVis)
```

# Examples

The climateR package is supplemented by the [AOI](https://github.com/mikejohnson51/AOI) framework established in the AOI R package. 

To get a climate product, an area of interest must be defined:

```{r}
AOI = aoi_get(state = "NC")
plot(AOI$geometry)
```

Here we are loading a polygon for the state of North Carolina More examples of constructing AOI calls can be found [here](https://mikejohnson51.github.io/AOI/).

With an AOI, we can construct a call to a dataset for a parameter(s) and date(s) of choice. Here we are querying the PRISM dataset for maximum and minimum temperature on October 29, 2018:

```{r}
system.time({
 p = getPRISM(AOI, param = c('tmax','tmin'), startDate = "2018-10-29")
})
```

```{r}
r = raster::stack(p)

rasterVis::levelplot(r, par.settings = BuRdTheme, names.attr = names(p)) +
  layer(sp.lines(as_Spatial(AOI), col="gray30", lwd=3))
```

# Data from known bounding coordinates

`climateR` offers support for `sf`, `sfc`, and `bbox` objects. Here we are requesting wind velocity data for the four corners region of the USA by bounding coordinates.

```{r}
AOI = st_bbox(c(xmin = -112, xmax = -105, ymax = 39, ymin = 34), crs = 4326) %>% 
  getGridMET(param = "wind_vel", startDate = "2018-09-01")

rasterVis::levelplot(AOI$gridmet_wind_vel, margin = FALSE, main = "Four corners Wind Velocity")
```

# Data through time ...

In addition to multiple variables we can request variables through time, here let's look at the gridMET rainfall for the Gulf Coast during Hurricane Harvey:

```{r, fig.width= 15}
harvey = getGridMET(aoi_get(state = c("TX", "FL")), 
                  param = "prcp", 
                  startDate = "2017-08-20", endDate = "2017-08-31")

levelplot(harvey$gridmet_prcp, par.settings = BTCTheme, main = "Hurricane Harvey")
```

# Climate Projections 

Some sources are downscaled Global Climate Models (GCMs). These allow you to query forecasted ensemble members from different models and/or climate scenarios. One example is from the MACA dataset:

```{r}
system.time({
m = getMACA(AOI = aoi_get(state = "FL"), 
            model = "CCSM4", 
            param = 'prcp', 
            scenario = c('rcp45', 'rcp85'), 
            startDate = "2080-06-29", endDate = "2080-06-30")
})
```

```{r, fig.width = 15}
r = raster::stack(m)
names(r) = paste(rep(names(m), each = 2), names(m[[1]]))
levelplot(r, par.settings = BTCTheme)
```

Getting multiple models results is also quite simple:

```{r}
models = c("bnu-esm","canesm2", "ccsm4", "cnrm-cm5", "csiro-mk3-6-0")

temp =  getMACA(AOI = aoi_get(state = "conus"),
                  param = 'tmin', 
                  model = models, 
                  startDate = "2080-11-29")

s = stack(temp)
s = addLayer(s, mean(s))
names(s) = c(models, "Ensemble Mean")

# Plot
rasterVis::levelplot(s, par.settings = rasterVis::BuRdTheme)
```
If you don't know your models, you can always grab a random set by specifying a number:

```{r, fig.width= 15}
random = getMACA(aoi_get(state = "MI"), model = 3, param = "prcp", startDate = "2050-10-29")
random = stack(random) %>% setNames(names(random))
levelplot(stack(random), par.settings = BTCTheme)
```

# Global Datasets

Not all datasets are USA focused either. TerraClimate offers global, monthly data up to the current year for many variables, and CHIRPS provides daily rainfall data:

```{r, fig.width = 15}

kenya = aoi_get(country = "Kenya")
tc = getTerraClim(kenya, param = "prcp", startDate = "2018-01-01")
chirps = getCHIRPS(kenya, startDate = "2018-01-01", endDate = "2018-01-04" )

p1 = levelplot(tc$terraclim_prcp, par.settings = BTCTheme, main = "January 2018; TerraClim", margin = FALSE) +
  layer(sp.lines(as_Spatial(kenya), col="white", lwd=3))

p2 = levelplot(chirps,  par.settings = BTCTheme, main = "Janaury 1-4, 2018; CHIRPS", layout=c(2, 2)) +
  layer(sp.lines(as_Spatial(kenya), col="white", lwd=3))

gridExtra::grid.arrange(p1,p2, nrow = 1)
```

This raises the question "_what is available for each resource?_". This can be checked in the appropriate `meta_data` objects. For example let's see what parameter data is offered for gridMET, and what models and scenarios are offered for MACA.

```{r}
head(param_meta$gridmet)

head(model_meta$maca)
```

# Point Based Data

Finally, data gathering is not limited to areal extents and can be retrieved as a time series at locations. 

```{r}
AOI = AOI::geocode('Colorado Springs', pt = TRUE)
ts  = getGridMET(AOI, param = 'srad', startDate = "2019-01-01", endDate = "2019-12-31")

ggplot(data = ts) + 
  aes(x = date, y = srad) + 
  geom_line() +
  stat_smooth(col = "red") + 
  theme_linedraw() + 
  labs(title = "Solar Radiation: Colorado Springs 2019", x = "Date", y = "Solar Radiation")

```

# Point Based Ensemble

```{r}
future = getMACA(geocode("UCSB", pt = TRUE), 
                 model = 5, param = "tmax", 
                 startDate = "2050-01-01", endDate = "2050-01-31")

future_long = future %>% 
  dplyr::select(-source, -lat, -lon) %>% 
  tidyr::pivot_longer(-date) 

ggplot(data = future_long, aes(x = date, y = value, col = name)) + 
  geom_line() + 
  theme_linedraw() + 
  scale_color_brewer(palette = "Dark2") + 
  labs(title = "UCSB Temperture: January, 2050",
       x = "Date",
       y = "Degree K",
       color = "Model")
```


# Multi site extraction

Extracting data for a set of points is an interesting challenge. It turns it is much more efficient to grab the underlying raster stack and then extract time series as opposed to iterating over the locations:

1. Starting with a set of locations in Brazil:

```{r}
(sites = read.csv('./inst/extdata/example.csv') %>% 
  st_as_sf(coords = c("long", "lat"), crs = 4326))
```

2. `climateR` will grab the RasterStack underlying the bounding area of the points

```{r}
sites_stack = getTerraClim(AOI   = sites, 
                           param = "tmax", 
                           startDate = "2018-01-01", 
                           endDate   = "2018-12-31")

plot(sites_stack$terraclim_tmax$X2018.01)
plot(sites$geometry, add = TRUE, pch = 16, cex = .5)
```

3. Use `extract_sites` to extract the times series from these locations. The `id` parameter is the unique identifier from the site data with which to names the resulting columns.

````{r}
sites_wide = extract_sites(sites_stack, sites, "ID")
sites_wide$terraclim_tmax[1:5, 1:5]
```

To make the data 'tidy' simply pivot on the `date` column:

```{r}
tmax = tidyr::pivot_longer(sites_wide$terraclim_tmax, -date)
head(tmax)

ggplot(data = tmax, aes(x = date, y = value, color = name, group = name)) + 
  scale_color_viridis_d() +
  geom_line() + 
  theme_linedraw() + 
  theme(legend.position = "none") 
```

# Fast Reprojection

This is a relatively new function (01-18-2020) that has not been extensively tested for how it scales with large requests. The aim is to provide fast projection of climateR gridded output. For point data use `sf::st_transform`. Starting with 2 days of precipitation data in 2080 from MACA:

```{r}
cr = climateR::getMACA(
  AOI::aoi_get(state = "conus"), 
  model = "CCSM4", 
  param = 'prcp', 
  startDate = "2080-06-29", endDate = "2080-06-30")

levelplot(cr$maca_ccsm4_prcp_rcp45_mm, par.settings = BTCTheme)
```

Lets transform the projection system from the native WGS84 to the projected CONUS Albers Equal Area (EPSG:5070).

```{r}
system.time({ cr2 = fast_reproject(cr, target_prj = 5070) })
levelplot(cr2$maca_ccsm4_prcp_rcp45_mm, par.settings = BTCTheme)
```

### Support:

`climateR` is written by [Mike Johnson](https://mikejohnson51.github.io), a graduate Student at the [University of California, Santa Barbara](https://geog.ucsb.edu) in [Keith C. Clarke's](http://www.geog.ucsb.edu/~kclarke/) Lab.