Add syntax for combining final and provisional data

[boshek]

This PR will close #235 and #230

The intent of this PR is to provide a set of functions that do the following:

• allow the user to call available_flows and promote this as probably the best way to get data
• tidyhydat will check to see if a user has HYDAT downloaded locally use that data if possible.
• It will fall back to using the webservice for historical data
• Then it will take the latest final data and try to backfill with provisional data as much as it can.

You can see usage examples below.

Usage

library(tidyhydat)
# Get all available flow data (final + provisional)
flows <- available_flows("08MF005", start_date = "2024-01-01")
flows
#>   Queried on: 2025-12-09 17:46:38.085654 (UTC)
#>   Historical data source: HYDAT
#>   Final data range: 2024-01-01 to 2024-12-31
#>   Provisional data range: 2025-01-01 to 2025-12-09
#>   Overall date range: 2024-01-01 to 2025-12-09
#>   Records by approval status:
#>     final: 366
#>     provisional: 343
#>   Station(s) returned: 1
#>   All stations successfully retrieved.
#>   Parameter(s): Flow
#> # A tibble: 709 × 6
#>    STATION_NUMBER Date       Parameter Value Symbol Approval
#>    <chr>          <date>     <chr>     <dbl> <chr>  <chr>   
#>  1 08MF005        2024-01-01 Flow        911 E      final   
#>  2 08MF005        2024-01-02 Flow        892 E      final   
#>  3 08MF005        2024-01-03 Flow        869 E      final   
#>  4 08MF005        2024-01-04 Flow        844 E      final   
#>  5 08MF005        2024-01-05 Flow        835 E      final   
#>  6 08MF005        2024-01-06 Flow        857 E      final   
#>  7 08MF005        2024-01-07 Flow        848 E      final   
#>  8 08MF005        2024-01-08 Flow        790 E      final   
#>  9 08MF005        2024-01-09 Flow        757 <NA>   final   
#> 10 08MF005        2024-01-10 Flow        725 <NA>   final   
#> # ℹ 699 more rows
plot(flows)

# Force web service (when HYDAT unavailable)
flows_only_ws <- available_flows(
  "08MF005", 
  start_date = "2024-01-01", 
  hydat_path = FALSE
)
flows_only_ws
#>   Queried on: 2025-12-09 17:46:41.971968 (UTC)
#>   Historical data source: Web Service
#>   Final data range: 2024-01-01 to 2024-12-31
#>   Provisional data range: 2025-01-01 to 2025-12-09
#>   Overall date range: 2024-01-01 to 2025-12-09
#>   Records by approval status:
#>     final: 366
#>     provisional: 343
#>   Station(s) returned: 1
#>   All stations successfully retrieved.
#>   Parameter(s): discharge/débit/Flow
#> # A tibble: 709 × 6
#>    STATION_NUMBER Date       Parameter       Value Symbol Approval
#>    <chr>          <date>     <chr>           <dbl> <chr>  <chr>   
#>  1 08MF005        2024-01-01 discharge/débit   911 E      final   
#>  2 08MF005        2024-01-02 discharge/débit   892 E      final   
#>  3 08MF005        2024-01-03 discharge/débit   869 E      final   
#>  4 08MF005        2024-01-04 discharge/débit   844 E      final   
#>  5 08MF005        2024-01-05 discharge/débit   835 E      final   
#>  6 08MF005        2024-01-06 discharge/débit   857 E      final   
#>  7 08MF005        2024-01-07 discharge/débit   848 E      final   
#>  8 08MF005        2024-01-08 discharge/débit   790 E      final   
#>  9 08MF005        2024-01-09 discharge/débit   757 <NA>   final   
#> 10 08MF005        2024-01-10 discharge/débit   725 <NA>   final   
#> # ℹ 699 more rows

[emilyhaughton]

@boshek Looks great! I like the available_flows name—it’s clear and easy to understand. Using local HYDAT data first, then falling back to the web, and filling in provisional data all makes sense. The examples are helpful too.