Help for package tidyhydat

Title:

Extract and Tidy Canadian 'Hydrometric' Data

Version:

0.7.1

Description:

Provides functions to access historical and real-time national 'hydrometric' data from Water Survey of Canada data sources (https://dd.weather.gc.ca/hydrometric/csv/ and https://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/) and then applies tidy data principles.

License:

Apache License (== 2.0) | file LICENSE

URL:

https://docs.ropensci.org/tidyhydat/, https://github.com/ropensci/tidyhydat/

BugReports:

https://github.com/ropensci/tidyhydat/issues/

Depends:

R (≥ 4.2.0)

Imports:

cli (≥ 1.0.0), crayon (≥ 1.3.4), DBI (≥ 0.7), dbplyr (≥ 1.1.0), dplyr (≥ 0.7.4), httr2 (≥ 1.0.0), lubridate (≥ 1.6.0), rappdirs (≥ 0.3.1), readr (≥ 1.1.1), rlang (≥ 0.1.2), RSQLite (≥ 2.0), tidyr (≥ 0.7.1)

Suggests:

ggplot2, knitr, rmarkdown, testthat (≥ 3.0.0), covr

Config/testthat/edition:

VignetteBuilder:

knitr

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2025-03-11 20:29:02 UTC; samalbers

Author:

Sam Albers

[aut, cre], David Hutchinson [ctb], Dewey Dunnington [ctb], Ryan Whaley [ctb], Province of British Columbia [cph], Government of Canada [dtc], Luke Winslow [rev] (Reviewed for rOpenSci), Laura DeCicco [rev] (Reviewed for rOpenSci)

Maintainer:

Sam Albers <sam.albers@gmail.com>

Repository:

CRAN

Date/Publication:

2025-03-11 21:00:02 UTC

tidyhydat: Extract and Tidy Canadian 'Hydrometric' Data

Description

Author(s)

Maintainer: Sam Albers sam.albers@gmail.com (ORCID)

Other contributors:

David Hutchinson david.hutchinson@canada.ca [contributor]
Dewey Dunnington dewey@fishandwhistle.net [contributor]
Ryan Whaley rdgwhaley@gmail.com [contributor]
Province of British Columbia [copyright holder]
Government of Canada [data contributor]
Luke Winslow (Reviewed for rOpenSci) [reviewer]
Laura DeCicco (Reviewed for rOpenSci) [reviewer]

References

To download the latest version of hydat please:

use the download_hydat() function.
If that fails you can download directly from this link: https://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/

For more information on tidy data please see

Wickham, Hadley. 2014. Tidy Data. The Journal of Statistical Software. 59. doi:10.18637/jss.v059.i10
tidy data vignette: https://CRAN.R-project.org/package=tidyr/vignettes/tidy-data.html

For more information on HYDAT and ECCC data sources

Please see this description of the database
This page is landing page for technical description of HYDAT
This pdf links to a document that outlines database table definitions
This FAQ provides a helpful list of ECCC data source questions

All Canadian stations

Description

A shorthand to avoid having always call hy_stations or realtime_stations. Populated by both realtime and historical data from HYDAT.

Usage

allstations

Format

A tibble with 5 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
STATION_NAME: Official name for station identification
PROV_TERR_STATE_LOC: The province, territory or state in which the station is located
HYD_STATUS: Current status of discharge or level monitoring in the hydrometric network
REAL_TIME: Logical. Indicates if a station has the capacity to deliver data in real-time or near real-time
LATITUDE: North-South Coordinates of the gauging station in decimal degrees
LONGITUDE: East-West Coordinates of the gauging station in decimal degrees
station_tz: Timezone of station calculated using the lutz package based on LAT/LONG of stations
standard_offset: Offset from UTC of local standard time

Source

HYDAT, Meteorological Service of Canada datamart

Download and set the path to HYDAT

Description

Download the HYDAT sqlite database. This database contains all the historical hydrometric data for Canada's integrated hydrometric network. The function will check for a existing sqlite file and won't download the file if the same version is already present.

Usage

download_hydat(dl_hydat_here = NULL, ask = TRUE)

Arguments

dl_hydat_here

Directory to the HYDAT database. The path is chosen by the rappdirs package and is OS specific and can be view by hy_dir(). This path is also supplied automatically to any function that uses the HYDAT database. A user specified path can be set though this is not the advised approach. It also downloads the database to a directory specified by hy_dir().

ask

Whether to ask (as TRUE/FALSE) if HYDAT should be downloaded. If FALSE the keypress question is skipped.

Examples

## Not run: 
download_hydat()

## End(Not run)

hy_agency_list function

Description

AGENCY look-up Table

Usage

hy_agency_list(hydat_path = NULL)

Arguments

hydat_path

The path to the hydat database or NULL to use the default location used by download_hydat. It is also possible to pass in an existing src_sqlite such that the database only needs to be opened once per user-level call.

Value

A tibble of agencies

Source

HYDAT

Examples

## Not run: 
hy_agency_list()

## End(Not run)

Extract annual max/min instantaneous flows and water levels from HYDAT database

Description

Provides wrapper to turn the ANNUAL_INSTANT_PEAKS table in HYDAT into a tidy data frame of instantaneous flows and water levels. station_number and prov_terr_state_loc can both be supplied.

Usage

hy_annual_instant_peaks(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_year = NULL,
  end_year = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Province, state or territory. If this argument is omitted, the value of station_number is returned. See unique(allstations$prov_terr_state_loc). Will also accept CA to return only Canadian stations.

start_year

First year of the returned record

end_year

Last year of the returned record

Value

A tibble of hy_annual_instant_peaks.

Source

HYDAT

Examples

## Not run: 
## Multiple stations province not specified
hy_annual_instant_peaks(station_number = c("08NM083", "08NE102"))

## Multiple province, station number not specified
hy_annual_instant_peaks(prov_terr_state_loc = c("AB", "YT"))

## End(Not run)

Extract annual statistics information from the HYDAT database

Description

Provides wrapper to turn the ANNUAL_STATISTICS table in HYDAT into a tidy data frame of annual statistics. Statistics provided include MEAN, MAX and MIN on an annual basis.

Usage

hy_annual_stats(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_year = "ALL",
  end_year = "ALL"
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_year

First year of the returned record

end_year

Last year of the returned record

Format

A tibble with 8 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Parameter: Parameter being measured. Only possible values are FLOW and LEVEL
Year: Year of record.
Sum_stat: Summary statistic being used.
Value: Value of the measurement. If Parameter equals FLOW the units are m^3/s. If Parameter equals LEVEL the units are metres.
Date: Observation date. Formatted as a Date class. MEAN is a annual summary and therefore has an NA value for Date.
Symbol: Measurement/river conditions

Value

A tibble of hy_annual_stats.

Source

HYDAT

Examples

## Not run: 
## Multiple stations province not specified
hy_annual_stats(station_number = c("08NM083", "05AE027"))

## Multiple province, station number not specified
hy_annual_stats(prov_terr_state_loc = c("AB", "SK"))

## End(Not run)

Extract all daily water level and flow measurements

Description

A thin wrapper around hy_daily_flows and 'hy_daily_levels“ that returns a data frames that contains both parameters. All arguments are passed directly to these functions.

Usage

hy_daily(
  station_number = NULL,
  prov_terr_state_loc = NULL,
  hydat_path = NULL,
  ...
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

prov_terr_state_loc

hydat_path

...

See hy_daily_flows() arguments

Format

A tibble with 5 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Date: Observation date. Formatted as a Date class.
Parameter: Parameter being measured.
Value: Discharge value. The units are m^3/s.
Symbol: Measurement/river conditions

Value

A tibble of daily flows and levels

Source

HYDAT

Examples

## Not run: 
hy_daily(station_number = c("02JE013", "08MF005"))

## End(Not run)

Extract daily flows information from the HYDAT database

Description

Provides wrapper to turn the DLY_FLOWS table in HYDAT into a tidy data frame of daily flows. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large tibble for hy_daily_flows.

Usage

hy_daily_flows(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL,
  symbol_output = "code"
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

symbol_output

Set whether the raw code, or the english or the french translations are outputted. Default value is code.

Format

A tibble with 5 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Date: Observation date. Formatted as a Date class.
Parameter: Parameter being measured. Only possible value is Flow
Value: Discharge value. The units are m^3/s.
Symbol: Measurement/river conditions

Value

A tibble of daily flows

Source

HYDAT

Examples

## Not run: 
# download_hydat()
hy_daily_flows(
  station_number = c("08MF005"),
  start_date = "1996-01-01", end_date = "2000-01-01"
)

hy_daily_flows(prov_terr_state_loc = "PE")

## End(Not run)

Extract daily levels information from the HYDAT database

Description

Provides wrapper to turn the DLY_LEVELS table in HYDAT into a tidy data frame. The primary value returned by this function is discharge. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large vector for hy_daily_levels.

Usage

hy_daily_levels(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL,
  symbol_output = "code"
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

symbol_output

Set whether the raw code, or the english or the french translations are outputted. Default value is code.

Format

A tibble with 5 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Date: Observation date. Formatted as a Date class.
Parameter: Parameter being measured. Only possible value is Level
Value: Level value. The units are metres.
Symbol: Measurement/river conditions

Value

A tibble of daily levels

Source

HYDAT

Examples

## Not run: 
hy_daily_levels(
  station_number = c("02JE013", "08MF005"),
  start_date = "1996-01-01", end_date = "2000-01-01"
)

hy_daily_levels(prov_terr_state_loc = "PE")

## End(Not run)

DATA SYMBOLS look-up table

Description

A look table for data symbols

Usage

hy_data_symbols

Format

A tibble with 5 rows and 3 variables:

SYMBOL_ID: Symbol code
SYMBOL_EN: Description of Symbol (English)
SYMBOL_FR: Description of Symbol (French)

Source

HYDAT

DATA TYPES look-up table

Description

A look table for data types

Usage

hy_data_types

Format

A tibble with 5 rows and 3 variables:

DATA_TYPE: Data type code
DATA_TYPE_EN: Descriptive data type (English)
DATA_TYPE_FR: Descriptive data type (French)

Source

HYDAT

Extract datum list from HYDAT database

Description

DATUM look-up Table

Usage

hy_datum_list(hydat_path = NULL)

Arguments

hydat_path

Value

A tibble of DATUMS

Source

HYDAT

Examples

## Not run: 
hy_datum_list()

## End(Not run)

Output OS-independent path to the HYDAT sqlite database

Description

Provides the download location for download_hydat in an OS independent manner.

Usage

hy_dir(...)

Arguments

...

arguments potentially passed to rappdirs::user_data_dir

Examples

## Not run: 
hy_dir()

## End(Not run)

Extract monthly flows information from the HYDAT database

Description

Tidy data of monthly flows information from the monthly_flows HYDAT table. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large vector for hy_monthly_flows.

Usage

hy_monthly_flows(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

Format

A tibble with 8 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Year: Year of record.
Month: Numeric month value
Full_Month: Logical value is there is full record from Month
No_days: Number of days in that month
Sum_stat: Summary statistic being used.
Value: Value of the measurement in m^3/s.
Date_occurred: Observation date. Formatted as a Date class. MEAN is a annual summary and therefore has an NA value for Date.

Value

A tibble of monthly flows.

Source

HYDAT

Examples

## Not run: 
hy_monthly_flows(
  station_number = c("02JE013", "08MF005"),
  start_date = "1996-01-01", end_date = "2000-01-01"
)

hy_monthly_flows(prov_terr_state_loc = "PE")

## End(Not run)

Extract monthly levels information from the HYDAT database

Description

Tidy data of monthly river or lake levels information from the DLY_LEVELS HYDAT table. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large vector for hy_monthly_levels.

Usage

hy_monthly_levels(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

Format

A tibble with 8 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Year: Year of record.
Month: Numeric month value
Full_month: Logical value is there is full record from Month
No_days: Number of days in that month
Sum_stat: Summary statistic being used.
Value: Value of the measurement in metres.
Date_occurred: Observation date. Formatted as a Date class. MEAN is a annual summary and therefore has an NA value for Date.

Value

A tibble of monthly levels.

Source

HYDAT

Examples

## Not run: 
hy_monthly_levels(
  station_number = c("02JE013", "08MF005"),
  start_date = "1996-01-01", end_date = "2000-01-01"
)

hy_monthly_levels(prov_terr_state_loc = "PE")

## End(Not run)

This function is deprecated in favour of generic plot methods

Description

This is an easy way to visualize a single station using base R graphics. More complicated plotting needs should consider using ggplot2. Inputting more 5 stations will result in very busy plots and longer load time. Legend position will sometimes overlap plotted points.

Usage

hy_plot(
  station_number = NULL,
  Parameter = c("Flow", "Level", "Suscon", "Load")
)

Arguments

station_number

A (or several) seven digit Water Survey of Canada station number.

Parameter

Parameter of interest. Either "Flow" or "Level".

Extract regional office list from HYDAT database

Description

OFFICE look-up Table

Usage

hy_reg_office_list(hydat_path = NULL)

Arguments

hydat_path

Value

A tibble of offices

Source

HYDAT

Examples

## Not run: 
hy_reg_office_list()

## End(Not run)

Get the version date of HYDAT that is current on the ECCC website

Description

Retrieve the date of the HYDAT version available for download.

Usage

hy_remote()

Extract daily sediment load information from the HYDAT database

Description

Provides wrapper to turn the SED_DLY_LOADS table in HYDAT into a tidy data frame of daily sediment load information. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large vector for hy_sed_daily_loads.

Usage

hy_sed_daily_loads(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

Format

A tibble with 4 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Date: Observation date. Formatted as a Date class.
Parameter: Parameter being measured. Only possible value is Load
Value: Discharge value. The units are tonnes.

Value

A tibble of daily suspended sediment loads

Source

HYDAT

Examples

## Not run: 
hy_sed_daily_loads(prov_terr_state_loc = "PE")

## End(Not run)

Extract daily suspended sediment concentration information from the HYDAT database

Description

Provides wrapper to turn the SED_DLY_SUSCON table in HYDAT into a tidy data frame of daily suspended sediment concentration information. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large vector for hy_sed_daily_suscon.

Usage

hy_sed_daily_suscon(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL,
  symbol_output = "code"
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

symbol_output

Set whether the raw code, or the english or the french translations are outputted. Default value is code.

Format

A tibble with 5 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Date: Observation date. Formatted as a Date class.
Parameter: Parameter being measured. Only possible value is Suscon
Value: Discharge value. The units are mg/l.
Symbol: Measurement/river conditions

Value

A tibble of daily suspended sediment concentration

Source

HYDAT

Examples

## Not run: 
hy_sed_daily_suscon(station_number = "01CE003")

## End(Not run)

Extract monthly flows information from the HYDAT database

Description

Tidy data of monthly loads information from the SED_DLY_LOADS HYDAT table. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large vector for hy_sed_monthly_loads.

Usage

hy_sed_monthly_loads(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

Format

A tibble with 8 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Year: Year of record.
Month: Numeric month value
Full_Month: Logical value is there is full record from Month
No_days: Number of days in that month
Sum_stat: Summary statistic being used.
Value: Value of the measurement in tonnes.
Date_occurred: Observation date. Formatted as a Date class. MEAN is a annual summary and therefore has an NA value for Date.

Value

A tibble of monthly sediment loads.

Source

HYDAT

Examples

## Not run: 
hy_sed_monthly_loads(station_number = "01CE003")

## End(Not run)

Extract monthly flows information from the HYDAT database

Description

Tidy data of monthly suspended sediment concentration information from the SED_DLY_SUSCON HYDAT table. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large vector for hy_sed_monthly_suscon.

Usage

hy_sed_monthly_suscon(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

Format

A tibble with 8 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Year: Year of record.
Month: Numeric month value
Full_Month: Logical value is there is full record from Month
No_days: Number of days in that month
Sum_stat: Summary statistic being used.
Value: Value of the measurement in mg/l.
Date_occurred: Observation date. Formatted as a Date class. MEAN is a annual summary and therefore has an NA value for Date.

Value

A tibble of monthly suspended sediment concentrations.

Source

HYDAT

Examples

## Not run: 
hy_sed_monthly_suscon(station_number = "08MF005")

## End(Not run)

Extract instantaneous sediment sample information from the HYDAT database

Description

Provides wrapper to turn the hy_sed_samples table in HYDAT into a tidy data frame of instantaneous sediment sample information. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. That is a large vector for hy_sed_samples.

Usage

hy_sed_samples(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

Format

A tibble with 19 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
SED_DATA_TYPE: Contains the type of sampling method used in collecting sediment for a station
Date: Contains the time to the nearest minute of when the sample was taken
SAMPLE_REMARK_CODE: Descriptive Sediment Sample Remark in English
TIME_SYMBOL: An "E" symbol means the time is an estimate only
FLOW: Contains the instantaneous discharge in cubic metres per second at the time the sample was taken
SYMBOL_EN: Indicates a condition where the daily mean has a larger than expected error
SAMPLER_TYPE: Contains the type of measurement device used to take the sample
SAMPLING_VERTICAL_LOCATION: The location on the cross-section of the river at which the single sediment samples are collected. If one of the standard locations is not used the distance in meters will be shown
SAMPLING_VERTICAL_EN: Indicates sample location relative to the regular measurement cross-section or the regular sampling site
TEMPERATURE: Contains the instantaneous water temperature in Celsius at the time the sample was taken
CONCENTRATION_EN: Contains the instantaneous concentration sampled in milligrams per litre
SV_DEPTH2: Depth 2 for split vertical depth integrating (m)

Value

A tibble of instantaneous sediment samples data

Source

HYDAT

Examples

## Not run: 
hy_sed_samples(station_number = "01CA004")

## End(Not run)

Extract instantaneous sediment sample particle size distribution information from the HYDAT database

Description

Provides wrapper to turn the hy_sed_samples_psd table in HYDAT into a tidy data frame of instantaneous sediment sample particle size distribution. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations() table are returned. That is a large vector for hy_sed_samples_psd.

Usage

hy_sed_samples_psd(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL,
  start_date = NULL,
  end_date = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

start_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

end_date

Leave blank if all dates are required. Date format needs to be in YYYY-MM-DD. Date is inclusive.

Format

A tibble with 5 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
SED_DATA_TYPE: Contains the type of sampling method used in collecting sediment for a station
Date: Contains the time to the nearest minute of when the sample was taken
PARTICLE_SIZE: Particle size (mm)
PERCENT: Contains the percentage values for indicated particle sizes for samples collected

Value

A tibble of sediment sample particle size data

Source

HYDAT

Examples

## Not run: 
hy_sed_samples_psd(station_number = "01CA004")

## End(Not run)

Set the default database path

Description

For many reasons, it may be convenient to set the default database location to somewhere other than the global default. Users may wish to use a previously downloaded version of the database for reproducibility purposes, store hydat somewhere other than hy_dir().

Usage

hy_set_default_db(hydat_path = NULL)

Arguments

hydat_path

The path to the a HYDAT sqlite3 database file (e.g., hy_test_db)

Value

returns the previous value of hy_default_db.

Examples

## Not run: 
# set default to the test database
hy_set_default_db(hy_test_db())

# get the default value
hy_default_db()

# set back to the default db location
hy_set_default_db(NULL)

## End(Not run)

Open a connection to the HYDAT database

Description

This function gives low-level access to the underlying HYDAT database used by other functions. Many of these tables are too large to load into memory, so it is best to use dplyr to dplyr::filter() them before using dplyr::collect() to read them into memory.

Usage

hy_src(hydat_path = NULL)

hy_src_disconnect(src)

Arguments

hydat_path

src

A as returned by hy_src().

Value

A SQLite DBIConnection

Examples

## Not run: 
library(dplyr)

# src is a src_sqlite
src <- hy_src(hydat_path = hy_test_db())
src_tbls(src)

# to get a table, use dplyr::tbl()
tbl(src, "STATIONS")

# one you're sure the results are what you want
# get a data.frame using collect()
tbl(src, "STATIONS") |>
  filter(PROV_TERR_STATE_LOC == "BC") |>
  collect()

# close the connection to the database
hy_src_disconnect(src)

## End(Not run)

Extract station information from the HYDAT database

Description

Provides wrapper to turn the hy_stations table in HYDAT into a tidy data frame of station information. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned. This is the entry point for most analyses is tidyhydat as establish the stations for consideration is likely the first step in many instances.

Usage

hy_stations(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Format

A tibble with 15 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
STATION_NAME: Official name for station identification
PROV_TERR_STATE_LOC: The province, territory or state in which the station is located
REGIONAL_OFFICE_ID: The identifier of the regional office responsible for the station. Links to hy_reg_office_list
HYD_STATUS: Current status of discharge or level monitoring in the hydrometric network
SED_STATUS: Current status of sediment monitoring in the hydrometric network
LATITUDE: North-South Coordinates of the gauging station in decimal degrees
LONGITUDE: East-West Coordinates of the gauging station in decimal degrees
DRAINAGE_AREA_GROSS: The total surface area that drains to the gauge site (km^2)
DRAINAGE_AREA_EFFECT: The portion of the drainage basin that contributes runoff to the gauge site, calculated by subtracting any noncontributing portion from the gross drainage area (km^2)
RHBN: Logical. Reference Hydrometric Basin Network station. The Reference Hydrometric Basin Network (RHBN) is a sub-set of the national network that has been identified for use in the detection, monitoring, and assessment of climate change.
REAL_TIME: Logical. Indicates if a station has the capacity to deliver data in real-time or near real-time
CONTRIBUTOR_ID: Unique ID of an agency that contributes data to the HYDAT database. The agency is non-WSC and non WSC funded
OPERATOR_ID: Unique ID of an agency that operates a hydrometric station
DATUM_ID: Unique ID for a datum

Value

A tibble of stations and associated metadata

Source

HYDAT

Examples

## Not run: 
## Multiple stations province not specified
hy_stations(station_number = c("08NM083", "08NE102"))

## Multiple province, station number not specified
hy_stations(prov_terr_state_loc = c("AB", "YT"))

## End(Not run)

Extract station data collection from HYDAT database

Description

hy_stn_data_coll look-up Table

Usage

hy_stn_data_coll(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Format

A tibble with 6 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
DATA_TYPE: The type of data
Year_from: First year of use
Year_to: Last year of use
MEASUREMENT: The sampling method used in the collection of sediment data or the type of the gauge used in the collection of the hydrometric data
OPERATION: The schedule of station operation for the collection of sediment or hydrometric data

Value

A tibble of hy_stn_data_coll

Source

HYDAT

Examples

## Not run: 
hy_stn_data_coll(station_number = c("02JE013", "08MF005"))

## End(Not run)

Extract station data range from HYDAT database

Description

hy_stn_data_range look-up Table

Usage

hy_stn_data_range(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Format

A tibble with 6 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
DATA_TYPE: Code for the type of data
SED_DATA_TYPE: Code for the type of instantaneous sediment data
Year_from: First year of use
Year_to: Last year of use
RECORD_LENGTH: Number of years of data available in the HYDAT database

Value

A tibble of hy_stn_data_range

Source

HYDAT

Examples

## Not run: 
hy_stn_data_range(station_number = c("02JE013", "08MF005"))

## End(Not run)

Extract station datum conversions from HYDAT database

Description

hy_stn_datum_conv look-up Table

Usage

hy_stn_datum_conv(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Format

A tibble with 4 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
DATUM_FROM: Identifying a datum from which water level is being converted
DATUM_TO: Identifying a datum to which water level is being converted
CONVERSTION_FACTOR: The conversion factor applied to water levels referred to one datum to obtain water levels referred to another datum

Value

A tibble of hy_stn_datum_conv

Examples

## Not run: 
hy_stn_datum_conv(station_number = c("02JE013", "08MF005"))

## End(Not run)

Extract station datum unrelated from HYDAT database

Description

hy_stn_datum_unrelated look-up Table

Usage

hy_stn_datum_unrelated(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Format

A tibble with 4 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
DATUM_ID: Unique code identifying a datum
Year_from: First year of use
Year_to: Last year of use

Value

A tibble of hy_stn_datum_unrelated

Examples

## Not run: 
hy_stn_datum_unrelated()

## End(Not run)

Extract station operation schedule from HYDAT database

Description

hy_stn_op_schedule look-up Table

Usage

hy_stn_op_schedule(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Format

A tibble with 6 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
DATA_TYPE: The type of data
Year: Year of operation schedule
Month_from: First month of use
Month_to: Last month of use

Value

A tibble of hy_stn_op_schedule

Source

HYDAT

Examples

## Not run: 
hy_stn_op_schedule(station_number = c("02JE013"))

## End(Not run)

Extract station regulation from the HYDAT database

Description

Provides wrapper to turn the hy_stn_regulation table in HYDAT into a tidy data frame of station regulation. station_number and prov_terr_state_loc can both be supplied. If both are omitted all values from the hy_stations table are returned.

Usage

hy_stn_regulation(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Format

A tibble with 4 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Year_from: First year of use
Year_to: Last year of use
REGULATED: logical

Value

A tibble of stations, years of regulation and the regulation status

Source

HYDAT

Examples

## Not run: 
## Multiple stations province not specified
hy_stn_regulation(station_number = c("08NM083", "08NE102"))

## Multiple province, station number not specified
hy_stn_regulation(prov_terr_state_loc = c("AB", "YT"))

## End(Not run)

Extract station remarks from HYDAT database

Description

hy_stn_remarks look-up Table

Usage

hy_stn_remarks(
  station_number = NULL,
  hydat_path = NULL,
  prov_terr_state_loc = NULL
)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

hydat_path

prov_terr_state_loc

Format

A tibble with 4 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
REMARK_TYPE: Type of Remark
Year: Year of the remark
REMARK: Remark

Value

A tibble of hy_stn_remarks

Examples

## Not run: 
hy_stn_remarks(station_number = c("02JE013", "08MF005"))

## End(Not run)

Get the location of the HYDAT database

Description

The full HYDAT database needs to be downloaded from download_hydat, but for testing purposes, a small test database is included in this package. Use hydat_path = hy_test_db() in hy_* functions to explicitly use the test database; use hydat_path = hy_downloaded_db() to explicitly use the full, most recent downloaded database (this is also the path returned by hy_default_db()).

Usage

hy_test_db()

hy_downloaded_db()

hy_default_db()

Value

The file location of a HYDAT database.

Examples

## Not run: 
hy_test_db()
hy_downloaded_db()
hy_default_db()

## End(Not run)

Extract version number from HYDAT database

Description

A function to get version number of hydat

Usage

hy_version(hydat_path = NULL)

Arguments

hydat_path

Value

version number and release date

Source

HYDAT

Examples

## Not run: 
hy_version()

## End(Not run)

Parameter ID

Description

A tibble of parameter id codes and their corresponding explanation/description specific to the ECCC webservice

Usage

param_id

Format

A tibble with 8 rows and 7 variables:

Parameter: Numeric parameter code
Code: Letter parameter code
Name_En: Code name in English
Name_En: Code name in French
Unit: Parameter units

Plot historical and realtime data

Description

This method plots either daily time series data from HYDAT or realtime data from the datamart. These plots are intended to be convenient and quick methods to visualize hydrometric data.

Usage

## S3 method for class 'hy'
plot(x = NULL, ...)

## S3 method for class 'realtime'
plot(x = NULL, Parameter = c("Flow", "Level"), ...)

Arguments

x

Object created by either a hy_daily_* or realtime_dd data retrieval function

...

passed to plot()

Parameter

Parameter of interest. Either "Flow" or "Level". Defaults to "Flow".

Methods (by class)

plot(realtime): plot.realtime

Examples

## Not run: 
# One station
fraser <- hy_daily_flows("08MF005")
plot(fraser)

## End(Not run)

## Not run: 
# One station
fraser_realtime <- realtime_dd("08MF005")
plot(fraser_realtime)

## End(Not run)

Convenience function to pull station number from tidyhydat functions

Description

This function mimics dplyr::pull to avoid having to always type dplyr::pull(STATION_NUMBER). Instead we can now take advantage of autocomplete. This can be used with realtime_ and hy_ functions.

Usage

pull_station_number(.data)

Arguments

.data

A table of data

Value

A vector of station_numbers

Examples

## Not run: 

hy_stations(prov_terr_state_loc = "PE") |>
  pull_station_number() |>
  hy_annual_instant_peaks()

## End(Not run)

Add local datetime column to realtime tibble

Description

Adds local_datetime and tz_used columns based on either the most common timezone in the original data or a user supplied timezone. This function is meant to used in a pipe with the realtime_dd() function.

Usage

realtime_add_local_datetime(.data, set_tz = NULL)

Arguments

.data

Tibble created by realtime_dd

set_tz

A timezone string in the format of OlsonNames()

Details

Date from realtime_dd is supplied in UTC which is the easiest format to work with across timezones. This function does not change Date from UTC. Rather station_tz specifies the local timezone name and is useful in instances where realtime_add_local_datetime adjusts local_datetime to a common timezone that is not the station_tz. This function is most useful when all stations exist within the same timezone.

Examples

## Not run: 

realtime_dd(c("08MF005", "02LA004")) |>
  realtime_add_local_datetime()

## End(Not run)

Calculate daily means from higher resolution realtime data

Description

This function is meant to be used within a pipe as a means of easily moving from higher resolution data to daily means.

Usage

realtime_daily_mean(.data, na.rm = FALSE)

Arguments

.data

A data argument that is designed to take only the output of realtime_dd

na.rm

a logical value indicating whether NA values should be stripped before the computation proceeds.

Examples

## Not run: 
realtime_dd("08MF005") |> realtime_daily_mean()

## End(Not run)

Download a tibble of realtime river data from the last 30 days from the Meteorological Service of Canada datamart

Description

Download realtime river data from the last 30 days from the Meteorological Service of Canada (MSC) datamart. The function will prioritize downloading data collected at the highest resolution. In instances where data is not available at high (hourly or higher) resolution daily averages are used. Currently, if a station does not exist or is not found, no data is returned.

Usage

realtime_dd(station_number = NULL, prov_terr_state_loc = NULL)

Arguments

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

prov_terr_state_loc

Format

A tibble with 8 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
PROV_TERR_STATE_LOC: The province, territory or state in which the station is located
Date: Observation date and time for last thirty days. Formatted as a POSIXct class in UTC for consistency.
Parameter: Parameter being measured. Only possible values are Flow and Level
Value: Value of the measurement. If Parameter equals Flow the units are m^3/s. If Parameter equals Level the units are metres.
Grade: reserved for future use
Symbol: reserved for future use
Code: quality assurance/quality control flag for the discharge
station_tz: Station timezone based on tidyhydat::allstations$station_tz

Value

A tibble of water flow and level values. The date and time of the query (in UTC) is also stored as an attribute.

Examples

## Not run: 
## Download from multiple provinces
realtime_dd(station_number = c("01CD005", "08MF005"))

## To download all stations in Prince Edward Island:
pei <- realtime_dd(prov_terr_state_loc = "PE")

## Access the time of query
attributes(pei)$query_time

## End(Not run)

Convenience function to plot realtime data

Description

Usage

realtime_plot(station_number = NULL, Parameter = c("Flow", "Level"))

Arguments

station_number

A seven digit Water Survey of Canada station number. Can only be one value.

Parameter

Parameter of interest. Either "Flow" or "Level". Defaults to "Flow".

Value

A plot of recent realtime values

Examples

## Not run: 
## One station
realtime_plot("08MF005")

## Multiple stations
realtime_plot(c("07EC002", "01AD003"))

## End(Not run)

Download a tibble of active realtime stations

Description

An up to date dataframe of all stations in the Realtime Water Survey of Canada hydrometric network operated by Environment and Climate Change Canada

Usage

realtime_stations(prov_terr_state_loc = NULL)

Arguments

prov_terr_state_loc

Format

A tibble with 6 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
STATION_NAME: Official name for station identification
LATITUDE: North-South Coordinates of the gauging station in decimal degrees
LONGITUDE: East-West Coordinates of the gauging station in decimal degrees
PROV_TERR_STATE_LOC: The province, territory or state in which the station is located
TIMEZONE: Timezone of the station

Examples

## Not run: 
## Available inputs for prov_terr_state_loc argument:
unique(realtime_stations()$prov_terr_state_loc)

realtime_stations(prov_terr_state_loc = "BC")
realtime_stations(prov_terr_state_loc = c("QC", "PE"))

## End(Not run)

Download realtime data from the ECCC web service

Description

Function to actually retrieve data from ECCC web service. The maximum number of days that can be queried depends on other parameters being requested. If one station is requested, 18 months of data can be requested. If you continually receiving errors when invoking this function, reduce the number of observations (via station_number, parameters or dates) being requested.

Usage

realtime_ws(
  station_number,
  parameters = NULL,
  start_date = Sys.Date() - 30,
  end_date = Sys.Date()
)

Arguments

station_number

Water Survey of Canada station number.

parameters

parameter ID. Can take multiple entries. Parameter is a numeric code. See param_id for some options though undocumented parameters may be implemented. Defaults to Water level provisional, Secondary water level, Tertiary water level, Discharge Provisional, Discharge, sensor, Water temperature, Secondary water temperature, Accumulated precipitation

start_date

Accepts either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. If only start date is supplied (i.e. YYYY-MM-DD) values are returned from the start of that day. Defaults to 30 days before current date. Time is supplied in UTC.

end_date

Accepts either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. If only a date is supplied (i.e. YYYY-MM-DD) values are returned from the end of that day. Defaults to current date. Time is supplied in UTC.

Format

A tibble with 6 variables:

STATION_NUMBER: Unique 7 digit Water Survey of Canada station number
Date: Observation date and time. Formatted as a POSIXct class as UTC for consistency.
Name_En: Code name in English
Value: Value of the measurement.
Unit: Value units
Grade: future use
Symbol: future use
Approval: future use
Parameter: Numeric parameter code
Code: Letter parameter code

Examples

## Not run: 

ws_08 <- realtime_ws(
  station_number = c("08NL071", "08NM174"),
  parameters = c(47, 5)
)

fivedays <- realtime_ws(
  station_number = c("08NL071", "08NM174"),
  parameters = c(47, 5),
  end_date = Sys.Date(), # today
  start_date = Sys.Date() - 5 # five days ago
)

## End(Not run)

A search function for hydrometric station name or number

Description

Use this search function when you only know the partial station name or want to search.

Usage

search_stn_name(search_term, hydat_path = NULL)

search_stn_number(search_term, hydat_path = NULL)

Arguments

search_term

Only accepts one word.

hydat_path

Value

A tibble of stations that match the search_term

Examples

## Not run: 
search_stn_name("Cowichan")

search_stn_number("08HF")

## End(Not run)

Function to chose a station based on consistent arguments for hydat functions.

Description

A function to avoid duplication in HYDAT functions. This function is not intended for external use.

Usage

station_choice(hydat_con, station_number, prov_terr_state_loc)

Arguments

hydat_con

A database connection

station_number

A seven digit Water Survey of Canada station number. If this argument is omitted, the value of prov_terr_state_loc is returned.

prov_terr_state_loc

Tidy eval helpers

Description

These functions provide tidy eval-compatible ways to capture symbols (sym(), syms(), ensym()), expressions (expr(), exprs(), enexpr()), and quosures (quo(), quos(), enquo()).

tidyhydat: Extract and Tidy Canadian 'Hydrometric' Data

Description

Author(s)

References

See Also

All Canadian stations

Description

Usage

Format

Source

Download and set the path to HYDAT

Description

Usage

Arguments

Examples

hy_agency_list function

Description

Usage

Arguments

Value

Source

See Also

Examples

Extract annual max/min instantaneous flows and water levels from HYDAT database

Description

Usage

Arguments

Value

Source

See Also

Examples

Extract annual statistics information from the HYDAT database

Description

Usage

Arguments

Format

Value

Source

See Also

Examples

Extract all daily water level and flow measurements

Description

Usage

Arguments

Format

Value

Source

See Also

Examples

Extract daily flows information from the HYDAT database

Description

Usage

Arguments

Format

Value

Source

See Also

Examples

Extract daily levels information from the HYDAT database

Description

Usage

Arguments

Format

Value

Source

See Also

Examples

DATA SYMBOLS look-up table

Description

Usage

Format

Source

See Also

DATA TYPES look-up table

Description

Usage

Format

Source

See Also

Extract datum list from HYDAT database