Author: Ezequiel Toum and Kevin Shook
Date: 2023-04-12

# Using hydrotoolbox with Canadian data - Part 2

#### Ezequiel Toum and Kevin Shook

#### 2023-04-12

    library(weathercan)
    library(hydrotoolbox)

The 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). In the next code lines we show an example.

    # 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

Note that you can save a lot of time by recycling the following function:

    # 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

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