Skip to contents

Wrapper for Hydstra/hydllp to find and return desired timeseries

Source: R/fetch_hydstra_timeseries.R
fetch_hydstra_timeseries.Rd

This wraps get_variable_list() and get_ts_traces(), allowing a bit more automation and a bit more flexibility than get_ts_traces(), but is currently slower due to more API network overhead. It loops over each distinct site and variable we're asking for, which allows us to tailor the requests a bit more. This approach allows us to do some useful things, though not always at the same time. We can ask for "all" in var_type, start_time, and end_time, and it will query the available data and get what's there. We can also ask for different data_type (statistic in this function for clarity) for different variables in var_type, which is very important, though this cannot happen along with var_type = "all". There are likely speedups we can do to combine some requests, and there is the possibility of future development allowing feeding this a pre-prepared table of arguments.

Usage

fetch_hydstra_timeseries(
  portal,
  gauge,
  datasource = "A",
  var_list = NULL,
  variable = NULL,
  units = NULL,
  timeunit = "day",
  statistic = "mean",
  start_time,
  end_time,
  multiplier = 1,
  ignore_fromderived = TRUE,
  returnformat = "df",
  request_timezone = "db_default",
  return_timezone = "UTC",
  .errorhandling = "pass"
)

Arguments

portal

character for the data portal (case insensitive). Default 'victoria'

gauge

character vector of gauge numbers, as site_list for Hydstra functions (station_no for Kiwis functions)

datasource

character for datasource code. To my knowledge, options are "A", "TELEM", "TELEMCOPY". Passing multiple not currently supported.

var_list

as in get_ts_traces(), but can also take "all" to get all available variables at each site in site_list. If 'all', overrides variable and units, though using var_list with those is always dangerous.

variable

allows searching by variable name, e.g. 'discharge' with grepl as in fetch_kiwis_timeseries()

units

allows searching by the units of the variable, e.g. 'ML/d' with grepl as in fetch_kiwis_timeseries()

timeunit

same as interval in get_ts_traces(). Name changed for consistency and interpretation.

statistic

same as data_type in get_ts_traces(). Name changed for consistency and interpretation. Can be a single character or a vector the same length as var_list. If single value, behaves as in get_ts_traces(), applying that function to all variables. If a vector, it applies the given function to the variable in the matching position of var_list. This allows us to ask for many variables that might need different statistics. Note- if var_list = "all", there is no way to match since the variables are unknown and may change between sits, and so statistic should be a single function.

start_time

as in get_ts_traces(), but can also take "all" to start at the first timepoint for each variable in var_list at each site in site_list

end_time

as in get_ts_traces(), but can also take "all" to end at the last timepoint for each variable in var_list at each site in site_list

multiplier

character, interval multiplier. I think this allows intervals like 5 days, by passing interval = 'day' and multiplier = 5. Not tested other than 1 at present.

ignore_fromderived

logical, default TRUE. Sometimes a derived variable (140, 141) is also available as a var_from, seemingly usually with a longer historical record. TRUE (the default) ignores that, and uses just the e.g. var_from = 100, var_to = 140. FALSE returns both sets, e.g. all records with the derived variable as var_to. If FALSE, look at the output carefully, it's often very strange

returnformat

character, one of

  • "df" returns a tibble

  • "varlist" returns a list with an separate tibble for each variable (may have multiple sites per tibble)

  • "sitelist" returns a list with an separate tibble for each site (may have multiple variables per tibble)

request_timezone

ignored if start_time and end_time are time objects, otherwise a timezone from OlsonNames() or 'db_default'

return_timezone

character in OlsonNames() or one of three special cases: 'db_default', 'char' or 'raw'. Default 'UTC'. If 'db_default', uses the API default. If 'char', returns a string in the format 'YYYY-MM-DDTHH:MM:SS+TZ', having all needed info (and matching Kiwis returns). If 'raw', returns the time column as-is from the API (a 14-digit string of numbers 'YYYMMDDHHMMSS')

  • "sxvlist" returns a list with an separate tibble for each site x variable combination

.errorhandling

as in foreach::foreach() (but handled in api_error_catch()) Default 'stop'. Made available here primarily to use 'pass' so big requests don't die due to API errors. Be careful- those errors then just get passed and so the data will be missing.

Value

a tibble of the requested timeseries