tidyhydat

https://docs.ropensci.org/tidyhydat/
Admin
tidyhydat is an R package that provides functions to access, extract, and standardize historical and...
Tokens:57,290
Snippets:492
Trust Score:9.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example: Set, get, and reset default database

Source: https://docs.ropensci.org/tidyhydat/reference/hy_set_default_db.html

Example usage wrapped in \dontrun. Sets the default to the test database, retrieves the default value, and resets to the default location.

```r
if (FALSE) { # \dontrun{
# 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)
} # }
```

--------------------------------

### Example: Get HYDAT database locations

Source: https://docs.ropensci.org/tidyhydat/reference/hy_test_db.html

Example usage of the three functions, wrapped in a dontrun block. The functions return the file location of a HYDAT database.

```r
if (FALSE) { # \dontrun{
hy_test_db()
hy_downloaded_db()
hy_default_db()
} # }
```

--------------------------------

### Example: realtime_dd with realtime_add_local_datetime

Source: https://docs.ropensci.org/tidyhydat/reference/realtime_add_local_datetime.html

Example usage in a pipe with realtime_dd. The example is wrapped in if (FALSE) { # \dontrun{ ... } # } to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{

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

--------------------------------

### Example: Using pull_station_number with hy_stations and hy_annual_instant_peaks

Source: https://docs.ropensci.org/tidyhydat/reference/pull_station_number.html

Example usage (not run) showing how to pull station numbers from hy_stations results and pass them to hy_annual_instant_peaks. The example is wrapped in if (FALSE) and # \dontrun{ to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{

hy_stations(prov_terr_state_loc = "PE") |>
  pull_station_number() |>
  hy_annual_instant_peaks()
} # }
```

--------------------------------

### available_flows examples

Source: https://docs.ropensci.org/tidyhydat/reference/available_flows.html

Examples of using available_flows() for basic usage, multiple stations, recent data, and forcing web service. Wrapped in \dontrun{}.

```r
if (FALSE) { # \dontrun{
## Basic usage - get all available data
flows <- available_flows("08MF005")

## Multiple stations
flows <- available_flows(c("08MF005", "08NM116"))

## Get only recent data (last 2 years)
recent_flows <- available_flows(
  "08MF005",
  start_date = Sys.Date() - lubridate::years(2),
  end_date = Sys.Date()
)

## Force use of web service (when HYDAT not available)
flows_ws <- available_flows("08MF005", hydat_path = FALSE)
} # }
```

--------------------------------

### Load tidyhydat and tidyverse packages

Source: https://docs.ropensci.org/tidyhydat/articles/tidyhydat_example_analysis.html

Loads the required packages for the example: tidyhydat, dplyr, ggplot2, and lubridate. This setup is needed before using any tidyhydat functions.

```R
library(tidyhydat)
library(dplyr)
library(ggplot2)
library(lubridate)
```

--------------------------------

### Plot available flows with plot()

Source: https://docs.ropensci.org/tidyhydat/index.html

Plot methods are provided to quickly visualize data. This example retrieves available flows for station 08MF005 starting from 2013-01-01 and then plots the result.

```r
flows_ex <- available_flows(station_number = "08MF005", start_date = "2013-01-01")

plot(flows_ex)
```

--------------------------------

### Example: call hy_version()

Source: https://docs.ropensci.org/tidyhydat/reference/hy_version.html

Example call to hy_version() with no arguments, using the default database location. Wrapped in if (FALSE) and \dontrun{} to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
hy_version()
} # }
```

--------------------------------

### Example: summary of available flows

Source: https://docs.ropensci.org/tidyhydat/reference/summary.available.html

Example usage of summary() on an 'available' object created by available_flows(). Wrapped in \dontrun{} so it is not executed during package checks.

```r
if (FALSE) { # \dontrun{
flows <- available_flows(c("08MF005", "08MF010"))
summary(flows)
} # }
```

--------------------------------

### Download HYDAT database with download_hydat()

Source: https://docs.ropensci.org/tidyhydat/reference/download_hydat.html

Example usage of download_hydat() to download the HYDAT database. The example is wrapped in if (FALSE) to prevent execution during package checks. The function checks for an existing sqlite file and skips download if the same version is already present.

```r
if (FALSE) { # \dontrun{
download_hydat()
} # }
```

--------------------------------

### Example: Download realtime data from multiple provinces and access query time

Source: https://docs.ropensci.org/tidyhydat/reference/realtime_dd.html

Example usage of realtime_dd() to download data from multiple provinces, all stations in Prince Edward Island, and access the query time attribute. The example is wrapped in a dontrun block.

```r
if (FALSE) { # \dontrun{
## 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
} # }
```

--------------------------------

### Example: Extract data for station 01CE003

Source: https://docs.ropensci.org/tidyhydat/reference/hy_sed_daily_suscon.html

Example call to hy_sed_daily_suscon for a single station. Wrapped in \dontrun to avoid execution during package checks.

```r
if (FALSE) { # \dontrun{
hy_sed_daily_suscon(station_number = "01CE003")
} # }
```

--------------------------------

### Example: query HYDAT with dplyr and disconnect

Source: https://docs.ropensci.org/tidyhydat/reference/hy_src.html

Example of using hy_src() to open a connection, list tables, query a table with dplyr, and close the connection. The example is wrapped in \dontrun{} and uses hy_test_db() for the database path.

```r
if (FALSE) { # \dontrun{
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)
} # }
```

--------------------------------

### Plot examples for available_flows, hy_daily_flows, and realtime_dd

Source: https://docs.ropensci.org/tidyhydat/reference/plot.html

Examples for plotting available flows, daily flows, and realtime data for station 08MF005. Wrapped in \dontrun to avoid execution during checks.

```r
if (FALSE) { # \dontrun{
# One station
flows <- available_flows("08MF005")
plot(flows)
} # }
```

```r
if (FALSE) { # \dontrun{
# One station
fraser <- hy_daily_flows("08MF005")
plot(fraser)
} # }
```

```r
if (FALSE) { # \dontrun{
# One station
fraser_realtime <- realtime_dd("08MF005")
plot(fraser_realtime)
} # }
```

--------------------------------

### Example: realtime_stations() with prov_terr_state_loc

Source: https://docs.ropensci.org/tidyhydat/reference/realtime_stations.html

Example usage of realtime_stations(). The code is wrapped in if (FALSE) { # \dontrun{ ... } } to prevent execution during package checks. It shows how to list available inputs and filter by province/territory.

```r
if (FALSE) { # \dontrun{
## 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"))
} # }
```

--------------------------------

### Example: hy_sed_samples_psd with station_number

Source: https://docs.ropensci.org/tidyhydat/reference/hy_sed_samples_psd.html

Example call to hy_sed_samples_psd using station_number "01CA004". Wrapped in if (FALSE) and \dontrun to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
hy_sed_samples_psd(station_number = "01CA004")
} # }
```

--------------------------------

### Example: hy_sed_daily_loads with prov_terr_state_loc

Source: https://docs.ropensci.org/tidyhydat/reference/hy_sed_daily_loads.html

Example call that retrieves daily sediment loads for Prince Edward Island. Wrapped in \dontrun{} so it is not executed during package checks.

```r
if (FALSE) { # \dontrun{
hy_sed_daily_loads(prov_terr_state_loc = "PE")
} # }
```

--------------------------------

### hy_dir example

Source: https://docs.ropensci.org/tidyhydat/reference/hy_dir.html

Example call to hy_dir() wrapped in a dontrun block, so it is not executed during package checks.

```r
if (FALSE) { # \dontrun{
hy_dir()
} # }
```

--------------------------------

### Example: realtime_dd("08MF005") |> realtime_daily_mean()

Source: https://docs.ropensci.org/tidyhydat/reference/realtime_daily_mean.html

Example usage within a pipe, converting realtime data for station 08MF005 to daily means. Wrapped in if (FALSE) and dontrun to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
realtime_dd("08MF005") |> realtime_daily_mean()
} # }
```

--------------------------------

### Install development version of tidyhydat from rOpenSci

Source: https://docs.ropensci.org/tidyhydat/index.html

Installs the development version of tidyhydat from the rOpenSci development server.

```r
install.packages("tidyhydat", repos = "https://dev.ropensci.org")
```

--------------------------------

### hy_annual_stats examples

Source: https://docs.ropensci.org/tidyhydat/reference/hy_annual_stats.html

Example calls for multiple stations or multiple provinces. Wrapped in \dontrun to avoid execution during package checks.

```r
if (FALSE) { # \dontrun{
## 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"))
} # }
```

--------------------------------

### Example: hy_sed_monthly_suscon with station_number

Source: https://docs.ropensci.org/tidyhydat/reference/hy_sed_monthly_suscon.html

Example call that retrieves monthly suspended sediment concentration data for station '08MF005'. Wrapped in \dontrun{} so it is not executed during package checks.

```r
if (FALSE) { # \dontrun{
hy_sed_monthly_suscon(station_number = "08MF005")
} # }
```

--------------------------------

### Example: hy_reg_office_list()

Source: https://docs.ropensci.org/tidyhydat/reference/hy_reg_office_list.html

Example call wrapped in \dontrun to prevent execution during package checks. It retrieves the regional office list from the default HYDAT database.

```r
if (FALSE) { # \dontrun{
hy_reg_office_list()
} # }
```

--------------------------------

### Example: Query by station numbers

Source: https://docs.ropensci.org/tidyhydat/reference/hy_annual_instant_peaks.html

Example usage with multiple station numbers and no province specified. Wrapped in \dontrun{} to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
## 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"))
} # }
```

--------------------------------

### Install tidyhydat from CRAN

Source: https://docs.ropensci.org/tidyhydat/index.html

Installs the stable version of tidyhydat from CRAN.

```r
install.packages("tidyhydat")
```

--------------------------------

### Example: hy_sed_monthly_loads with station_number

Source: https://docs.ropensci.org/tidyhydat/reference/hy_sed_monthly_loads.html

Example call to hy_sed_monthly_loads using station_number "01CE003". Wrapped in if (FALSE) and \dontrun to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
hy_sed_monthly_loads(station_number = "01CE003")
} # }
```

--------------------------------

### hy_daily example with station numbers

Source: https://docs.ropensci.org/tidyhydat/reference/hy_daily.html

Example call to hy_daily with two station numbers. Wrapped in \dontrun to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
hy_daily(station_number = c("02JE013", "08MF005"))
} # }
```

--------------------------------

### Example: hy_daily_flows with station number and date range

Source: https://docs.ropensci.org/tidyhydat/reference/hy_daily_flows.html

Example usage of hy_daily_flows with a station number and date range. The code is wrapped in a dontrun block, indicating it is not run during package checks. It requires a downloaded HYDAT database (download_hydat).

```r
if (FALSE) { # \dontrun{
# 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")
} # }
```

--------------------------------

### Download real-time data for all stations in a province

Source: https://docs.ropensci.org/tidyhydat/articles/tidyhydat_an_introduction.html

Use realtime_dd() with a province argument to download real-time data for all stations in that province. The example uses "PE" for Prince Edward Island.

```R
realtime_dd(prov_terr_state_loc = "PE")
```

--------------------------------

### hy_monthly_levels examples

Source: https://docs.ropensci.org/tidyhydat/reference/hy_monthly_levels.html

Example calls to hy_monthly_levels. The first retrieves data for two station numbers within a date range; the second retrieves data for all stations in Prince Edward Island. These are wrapped in \dontrun{} and are not executed during package checks.

```r
if (FALSE) { # \dontrun{
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")
} # }
```

--------------------------------

### Example usage of search_stn_name and search_stn_number

Source: https://docs.ropensci.org/tidyhydat/reference/search_stn_name.html

Example calls wrapped in \dontrun to prevent execution during package checks. search_stn_name('Cowichan') searches for stations with 'Cowichan' in the name, and search_stn_number('08HF') searches for stations with the station number prefix '08HF'. Both return a tibble of matching stations.

```r
if (FALSE) { # \dontrun{
search_stn_name("Cowichan")

search_stn_number("08HF")
} # }
```

--------------------------------

### Get real-time stations by province

Source: https://docs.ropensci.org/tidyhydat/articles/tidyhydat_an_introduction.html

Use realtime_stations() to get a vector of active real-time stations for a jurisdiction. The example selects stations in Prince Edward Island using the province code "PE".

```R
realtime_stations(prov_terr_state_loc = "PE")
```

--------------------------------

### Get stations from HYDAT by province

Source: https://docs.ropensci.org/tidyhydat/articles/tidyhydat_an_introduction.html

Use hy_stations() to extract station metadata directly from HYDAT. Unlike realtime_stations(), it includes discontinued and non-real-time stations. The example filters by province code "PE".

```R
hy_stations(prov_terr_state_loc = "PE")
```

--------------------------------

### Usage of hy_test_db, hy_downloaded_db, and hy_default_db

Source: https://docs.ropensci.org/tidyhydat/reference/hy_test_db.html

Shows the function signatures for the three database location functions. Use hy_test_db() to explicitly use the test database, and hy_downloaded_db() or hy_default_db() to use the full downloaded database.

```r
hy_test_db()

hy_downloaded_db()

hy_default_db()
```

--------------------------------

### Get daily flows with hy_daily_flows

Source: https://docs.ropensci.org/tidyhydat/index.html

Retrieves final approved daily flow data from the HYDAT database using hy_daily_flows. The example requests data for station 08MF005 for the year 2020 and shows the returned tibble with 366 observations.

```r
hy_daily_flows(
  station_number = "08MF005",
  start_date = "2020-01-01",
  end_date = "2020-12-31"
)
```

```r
#>   Queried from version of HYDAT released on 2025-10-14
#>    Observations:                      366
#>    Measurement flags:                 0
#>    Parameter(s):                      Flow
#>    Date range:                        2020-01-01 to 2020-12-31 
#>    Station(s) returned:               1
#>    Stations requested but not returned: 
#>     All stations returned.
#> # A tibble: 366 × 5
#>    STATION_NUMBER Date       Parameter Value Symbol
#>    <chr>          <date>     <chr>     <dbl> <chr> 
#>  1 08MF005        2020-01-01 Flow       1340 <NA>  
#>  2 08MF005        2020-01-02 Flow       1330 <NA>  
#>  3 08MF005        2020-01-03 Flow       1310 <NA>  
#>  4 08MF005        2020-01-04 Flow       1420 <NA>  
#>  5 08MF005        2020-01-05 Flow       1350 <NA>  
#>  6 08MF005        2020-01-06 Flow       1310 <NA>  
#>  7 08MF005        2020-01-07 Flow       1280 <NA>  
#>  8 08MF005        2020-01-08 Flow       1320 <NA>  
#>  9 08MF005        2020-01-09 Flow       1230 <NA>  
#> 10 08MF005        2020-01-10 Flow       1210 <NA>  
#> # ℹ 356 more rows
```

--------------------------------

### Find longest flow record and get daily flows

Source: https://docs.ropensci.org/tidyhydat/articles/tidyhydat_example_analysis.html

Uses hy_stn_data_range() to find the station with the longest flow record, then feeds that to hy_daily_flows() to retrieve the daily flow data. This is the core data extraction step for the first example.

```R
longest_record_data <- hy_stn_data_range() |>
  filter(DATA_TYPE == "Q", RECORD_LENGTH == max(RECORD_LENGTH)) |>
  pull_station_number() |>
  hy_daily_flows()
```

--------------------------------

### hy_stations usage examples

Source: https://docs.ropensci.org/tidyhydat/reference/hy_stations.html

Example calls to hy_stations() showing how to filter by station number or by province/territory. The examples are wrapped in a dontrun block, indicating they are not run during package checks.

```r
if (FALSE) { # \dontrun{
## 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"))
} # }
```

--------------------------------

### hy_monthly_flows examples

Source: https://docs.ropensci.org/tidyhydat/reference/hy_monthly_flows.html

Example usage of hy_monthly_flows. The first call filters by station numbers and date range; the second filters by province. The code is wrapped in \dontrun{} and is not executed in examples.

```r
if (FALSE) { # \dontrun{
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")
} # }
```

--------------------------------

### download_hydat()

Source: https://docs.ropensci.org/tidyhydat/reference/index.html

Download and set the path to HYDAT.

```APIDOC
## download_hydat()

### Description
Download and set the path to HYDAT.

### Usage
download_hydat()
```

--------------------------------

### Example: hy_sed_samples with station_number

Source: https://docs.ropensci.org/tidyhydat/reference/hy_sed_samples.html

Example usage of hy_sed_samples() with a specific station number. The code is wrapped in an if (FALSE) block with a \dontrun{} comment, indicating it is not run during package checks. The example retrieves sediment samples for station '01CA004'.

```r
if (FALSE) { # \dontrun{
hy_sed_samples(station_number = "01CA004")
} # }
```

--------------------------------

### hy_datum_list example

Source: https://docs.ropensci.org/tidyhydat/reference/hy_datum_list.html

Example call to hy_datum_list() wrapped in \dontrun{} so it is not executed during package checks. It returns a tibble of DATUMS.

```r
if (FALSE) { # \dontrun{
hy_datum_list()
} # }
```

--------------------------------

### hy_stn_regulation examples

Source: https://docs.ropensci.org/tidyhydat/reference/hy_stn_regulation.html

Example calls to hy_stn_regulation. The first retrieves data for multiple stations without specifying a province. The second retrieves data for multiple provinces without specifying a station number. These examples are wrapped in a dontrun block, so they are not executed by default.

```r
if (FALSE) { # \dontrun{
## 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"))
} # }
```

--------------------------------

### Download HYDAT data with available_flows() and summary()

Source: https://docs.ropensci.org/tidyhydat/index.html

Downloads daily flow data for specified stations and prints a summary of date ranges and record counts. Provisional data is aggregated to daily means to match the daily format of HYDAT data.

```r
flows <- available_flows(
  station_number = c("08MF005", "08NM116"),
  start_date = "2020-01-01"
)
summary(flows)
#> # A tibble: 2 × 7
#>   STATION_NUMBER final_start final_end  final_n provisional_start
#>   <chr>          <date>      <date>       <int> <date>           
#> 1 08MF005        2020-01-01  2024-12-31    1827 2025-01-01       
#> 2 08NM116        2020-01-01  2023-12-31    1461 2025-01-01       
#> # ℹ 2 more variables: provisional_end <date>, provisional_n <int>
```

--------------------------------

### Query real-time web service with multiple parameters

Source: https://docs.ropensci.org/tidyhydat/articles/tidyhydat_an_introduction.html

Use realtime_ws() to query multiple parameters simultaneously. The example queries water level (46) and discharge (47) for station "08MF005" over the last 7 days. See data("param_id") for a complete list of parameter codes.

```R
realtime_ws(station_number = "08MF005",
            parameters = c(46, 47), ## Water level and discharge
            start_date = Sys.Date() - lubridate::days(7),
            end_date = Sys.Date())
```

--------------------------------

### Create signed release on GitHub

Source: https://docs.ropensci.org/tidyhydat/release_process.html

Tag the release with a signed tag and push tags to GitHub.

```bash
git tag -s [version] -m "[version]"
git push --tags
```

--------------------------------

### Build and check within R/devtools

Source: https://docs.ropensci.org/tidyhydat/release_process.html

Run devtools checks on Windows (devel and release), macOS, and locally to verify the package before release.

```R
devtools::check_win_devel()
devtools::check_win_release()
devtools::check_mac_release()
devtools::check() ## build locally
```

--------------------------------

### Usage: hy_reg_office_list(hydat_path = NULL)

Source: https://docs.ropensci.org/tidyhydat/reference/hy_reg_office_list.html

Shows the function signature. The hydat_path argument can be a path to the HYDAT database, NULL for the default location, or an existing database connection from hy_src().

```r
hy_reg_office_list(hydat_path = NULL)
```

--------------------------------

### Example: plotting realtime data for one or multiple stations

Source: https://docs.ropensci.org/tidyhydat/reference/realtime_plot.html

Example usage of realtime_plot for a single station and for multiple stations. The code is wrapped in a dontrun block, so it will not run during package checks.

```r
if (FALSE) { # \dontrun{
## One station
realtime_plot("08MF005")

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

--------------------------------

### Download HYDAT database with hydat_download()

Source: https://docs.ropensci.org/tidyhydat/articles/tidyhydat_hydat_db.html

Downloads the latest HYDAT database. This is a lengthy operation (around 1 GB) and may take considerable time.

```R
hydat_download()
```

--------------------------------

### Download HYDAT database with download_hydat()

Source: https://docs.ropensci.org/tidyhydat/articles/tidyhydat_example_analysis.html

Downloads the HYDAT database, which is required before using any tidyhydat functions. The database location can be checked with hy_dir(). This is the only time you need to interact directly with HYDAT.

```R
download_hydat()
```

--------------------------------

### Update allstations data and documentation

Source: https://docs.ropensci.org/tidyhydat/release_process.html

Run the internal data processing script to update the allstations dataset and its documentation.

```R
source("data-raw/HYDAT_internal_data/process_internal_data.R")
```

--------------------------------

### S3 method signature for summary.available

Source: https://docs.ropensci.org/tidyhydat/reference/summary.available.html

Usage signature for the summary method on 'available' objects. The object argument is created by available_flows() or available_levels(); ... is ignored.

```r
# S3 method for class 'available'
summary(object, ...)
```
Tokens:
Raw