Package {hydrocan}

hydrocan: Unified Access to Canadian Hydrometric Data

Description

Provides a unified interface for accessing diverse web-published hydrometric data sources across Canada, presenting users with consistent tabular output regardless of the underlying data source.

Author(s)

Maintainer: Sam Albers sam.albers@hakai.org

Authors:

• Sam Albers sam.albers@hakai.org

Other contributors:

• Tula Foundation [funder, copyright holder]

• Canada Water Agency [funder]

See Also

Useful links:

• https://github.com/HakaiInstitute/hydrocan

• https://hakaiinstitute.github.io/hydrocan/

• Report bugs at https://github.com/HakaiInstitute/hydrocan/issues

Cite a hydrocan data source

Description

Returns a citation for a registered data source, formatted as a bibentry() object. The output behaves like citation(): it prints a human-readable reference and a BibTeX entry, and can be passed to toBibtex().

Usage

hc_citation(source)

Arguments

Value

A bibentry() object.

Examples

hc_citation("cehq")
toBibtex(hc_citation("hydroquebec"))

List registered data sources

Description

Returns a summary of all data sources currently available via hydrocan, including their description and which data types they support. No network calls are made.

Usage

hc_list_sources()

Value

A tibble with columns name (chr), description (chr), has_flows (lgl), has_daily_flows (lgl), has_levels (lgl), has_daily_levels (lgl), has_stations (lgl), license (chr), license_url (chr), terms_url (chr), and docs_url (chr).

Examples

hc_list_sources()

Retrieve daily flow summaries

Description

Returns one value per station per calendar day as published by the data source. Not all data sources publish daily data; those that do not will produce a warning and return no rows for the affected stations.

Usage

hc_read_daily_flows(
  station_id,
  start_date,
  end_date = Sys.Date(),
  source = NULL
)

Arguments

Value

A tibble with columns station_id (chr), date (Date), value (dbl), parameter (chr), unit (chr), provider_name (chr), quality_code (chr), and qf_desc (chr).

Examples

try(hc_read_daily_flows("030101", start_date = "2020-01-01", end_date = "2020-01-31"))

Retrieve daily water level summaries

Description

Returns one water level value per station per calendar day as published by the data source. Not all data sources publish daily level data; those that do not will produce a warning and return no rows for the affected stations.

Usage

hc_read_daily_levels(
  station_id,
  start_date,
  end_date = Sys.Date(),
  source = NULL
)

Arguments

Value

A tibble with columns station_id (chr), date (Date), value (dbl), parameter (chr: "water_level"), unit (chr), provider_name (chr), quality_code (chr), and qf_desc (chr).

Examples

try(hc_read_daily_levels("030101", start_date = "2020-01-01", end_date = "2020-01-31"))

Retrieve sub-daily flow observations

Description

Fetches sub-daily observations for one or more stations across the requested date range. The data source is determined automatically from the station ID, or fixed explicitly via source.

Usage

hc_read_flows(station_id, start_date, end_date = Sys.Date(), source = NULL)

Arguments

Value

A tibble with columns station_id (chr), timestamp (POSIXct UTC), value (dbl), parameter (chr), unit (chr), provider_name (chr), quality_code (chr), and qf_desc (chr).

Examples

try(hc_read_flows("703", start_date = Sys.Date() - 7))

Retrieve sub-daily water level observations

Description

Fetches sub-daily water level observations for one or more stations across the requested date range. The data source is determined automatically from the station ID, or fixed explicitly via source.

Usage

hc_read_levels(station_id, start_date, end_date = Sys.Date(), source = NULL)

Arguments

Value

A tibble with columns station_id (chr), timestamp (POSIXct UTC), value (dbl), parameter (chr: "water_level"), unit (chr), provider_name (chr), quality_code (chr), and qf_desc (chr).

Examples

try(hc_read_levels("703", start_date = Sys.Date() - 7))

Retrieve station metadata

Description

Returns location and period-of-record information for all stations available across registered data sources. Data sources that do not publish station metadata are skipped with a warning.

Usage

hc_read_stations(source = NULL)

Arguments

Value

A tibble with columns station_id (chr), station_name (chr), provider_name (chr), longitude (dbl), latitude (dbl), elevation_m (dbl), period_start (Date), period_end (Date), and notes (list).

Examples

try(hc_read_stations())
try(hc_read_stations(source = "cehq"))

Create a hydrocan adapter

Description

Constructs a validated adapter object for a data source. At least one fetch function must be supplied.

Usage

new_hydrocan_adapter(
  name,
  description,
  list_stations_fn,
  fetch_flows_fn = NULL,
  fetch_daily_flows_fn = NULL,
  fetch_levels_fn = NULL,
  fetch_daily_levels_fn = NULL,
  list_stations_meta_fn = NULL,
  title = NULL,
  publisher = NULL,
  license = NULL,
  license_url = NULL,
  terms_url = NULL,
  docs_url = NULL
)

Arguments

Value

A list with class "hydrocan_adapter".

Register a hydrocan adapter

Description

Adds an adapter to the package registry. Registering under an existing name overwrites it.

Usage

register_hydrocan_adapter(adapter)

Arguments

Value

adapter, invisibly.