In paleolimbot/hydatr: An R Interface to the Environment Canada HYDAT database

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)

hydatr

The HYDAT database contains over 1 GB of hydrological observation data collected by Environment Canada. The database is freely available from the Environment Canada website, however exctracting data can be difficult. This package provides tools to easily find and extract hydrological data from the HYDAT database.

Installation

You can install hydatr from github with:

# install.packages("devtools")
devtools::install_github("paleolimbot/hydatr")

Getting the HYDAT Database

The HYDAT database is about 1 GB in size, which is compressed into a 200 MB download from http://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/ . The hydat package will happily download and extract this for you.

library(hydatr)
hydat_download() # downloads the database from environment canada (10 min)
hydat_extract() # extracts the downloaded database into readable form
hydat_load() # loads the database (you'll need to call this one each time you load the package)

library(hydatr)
hydat_load_test_db()

Finding Hydro Stations

Find hydro sites:

hydat_find_stations("lower sackville, NS", year = 1999:2012)

Get detailed information about one hydro site:

as.list(hydat_station_info("01EJ004"))

Get detailed information about all the hydro sites:

hydat_station_info()

Extracting Data

The following methods extract data from the database given the correct station number:

hydat_flow_monthly("01AD001")
hydat_flow_daily("01AD001")
hydat_level_monthly("01AD003")
hydat_level_daily("01AD003")
hydat_sed_monthly("01AF006")
hydat_sed_daily("01AF006")

Advanced Functionality

The package is built on top of dplyr and RSQLite, and also provides low-level access to the HYDAT database through these methods.

hydat_get_db() # gets the db that was loaded in hydat_load()

hydat_tbl("ANNUAL_INSTANT_PEAKS") # gets the db that was loaded in hydat_load()

Because the package is built on dplyr, using dplyr functions is a particularly good way to get the most out of the database.

library(dplyr)
peaks <- hydat_tbl("ANNUAL_INSTANT_PEAKS") %>%
  left_join(hydat_tbl("PEAK_CODES")) %>%
  collect() %>%
  mutate(DATE = lubridate::ymd(paste(YEAR, MONTH, DAY))) %>%
  select(STATION_NUMBER, DATE, PEAK_CODE = PEAK_EN, PEAK)
peaks