---
title: "Using hydrotoolbox with Canadian data - Part 2"
author: "Ezequiel Toum and Kevin Shook"
date: "`r Sys.Date()`"
output: 
 rmarkdown::html_vignette:
   toc: true
vignette: >
  %\VignetteIndexEntry{Using hydrotoolbox with Canadian data - Part 2}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r libraries, eval = FALSE}
library(weathercan)
library(hydrotoolbox)
```

The package [**weathercan**](https://CRAN.R-project.org/package=weathercan)
provides a very easy way to access Canadian historical weather data from 
**Environment and Climate Change Canada (ECCC) website**.
In this vignette we show how to combine the `weathercan`
and `hydrotoolbox` functionality.

## Installing weathercan

You can install `weathercan` directly from CRAN:
`install.packages("weathercan")`. Since this package makes
it easier to search for and download multiple months/years of
historical weather data, these downloads can be fairly large
and performing multiple downloads may use up ECCC’s bandwidth
unnecessarily. Try to stick to what you need.

## Combining weathercan with hydrotoolbox

Once you know your station ID, you can download it (see [this link](https://github.com/ropensci/weathercan)). In the next
code lines we show an example.

```{r station, eval = FALSE}
# get station ID's
head(stations)

# search by name
stations_search("Kamloops", interval = "day")

# Kamloops A - BC province
station_id <- 1274    

kam <- 
  weather_dl(station_ids = station_id,
             start = "1900-01-01",
             end = "1950-12-31", 
             interval = "day") %>%
  as.data.frame()

# now we create the station object and we set the data 
kamloops_hm <- 
  hm_create() %>%
  hm_set(id = station_id, 
         station = kam$station_name[1], 
         province = kam$prov[1], 
         country = "Canada", 
         lat = kam$lat[1], 
         long = kam$lon[1], 
         alt = kam$elev[1], 
         tmean = kam[ , c("date", "mean_temp")], 
         tmax = kam[ , c("date", "max_temp")],
         tmin = kam[ , c("date", "min_temp")], 
         precip = kam[ , c("date", "total_precip")], 
         rainfall = kam[ , c("date", "total_rain")]
         )

kamloops_hm %>% hm_show()

# we plot air temperatures 
kamloops_hm %>%
  hm_plot(slot_name = c('tmean', 'tmax', 'tmin'), 
          col_name = list('mean_temp', 'max_temp', 'min_temp'), 
          interactive = TRUE, 
          line_color = c('forestgreen', 'red', 'dodgerblue'), 
          x_lab = 'Date', y_lab = 'T(ºC)', 
          legend_lab = c('mean', 'max', 'min') )
```

## Using an own made function to build the object

<!-- Although this version of the `hydrotoolbox` package -->
<!-- does not offer the ability to build -->
<!-- automatically a hydro-meteorological station from ECCC database, -->
Note that you can save a lot of time by recycling the
following function:

```{r my_fun, eval = FALSE}
# before running this function, the packages
# weathercan and hydrotoolbox should be attached

# station_number: character with station ID
build_weathercan <- function(station_id, 
                             from, to,
                             time_step){
  
  # download station data
  station <-
    weather_dl(station_ids = station_id,
             start = from,
             end = to, 
             interval = time_step) %>%
    as.data.frame()

  # now we create the station object and we set the (meta)data 
  station_hm <- 
    hm_create() %>%
    hm_set(id = station_id, 
         station = station$station_name[1], 
         province = station$prov[1], 
         country = "Canada", 
         lat = station$lat[1], 
         long = station$lon[1], 
         alt = station$elev[1], 
         tmean = station[ , c("date", "mean_temp")], 
         tmax = station[ , c("date", "max_temp")],
         tmin = station[ , c("date", "min_temp")], 
         precip = station[ , c("date", "total_precip")], 
         rainfall = station[ , c("date", "total_rain")]
         )
  
  return(station_hm)
}
```

once the function is loaded in the *Global Environment*, we set up the station

```{r fun_applied, eval = FALSE}
# we construct the Kamloops station
# but in a single code line

kamloops_station <- 
  build_weathercan(station_id = 1274, 
                   from = "1900-01-01", 
                   to = "1950-12-31",
                   time_step = "day")

kamloops_station %>%
  hm_show()
```

Since the builder function is the only one that differs
from what was developed for SNIH data, we recommend
(re)visiting this vignette 
(`vignette ('snih_arg', package = 'hydrotoolbox')`) to
explore some of the available methods.