bomWater
Alexander Buzacott
2020-09-16
Introduction
bomWater provides an interface to the Australian Bureau of Meteorology Water Data online (http://www.bom.gov.au/waterdata/) web service. As part of the Water Act 2007, the BoM is required to collect Australian water information and make it available to the public. This provides a single and convenient source of water data for all states and territories. Several hydrological and meteorological quality checked timeseries are available through Water Data online and bomWater provides several functions to access these timeseries.
Using bomWater
A typical workflow begins by querying station information using get_station_list() with a specific parameter type. The function parameters() returns all the parameters that can be retrieved using bomWater. By default get_station_list() returns all stations for Water Course Discharge and other parameters can be specified with the argument parameter_type. Once the station number of interest is known, it can be used to retrieve quality-checked timeseries using the functions:
get_hourly(): retrieves hourly dataget_daily(): retrieves daily dataget_monthly(): retrieves monthly dataget_yearly(): retrieves annual dataget_as_stored(): retrieves data as stored by BoM
Timeseries that are based on aggregated data return the mean by default, however other variables such as min and max are often available. The functions will return a tibble with three columns: Timestamp, Value and Quality Code.
Parameters
The following Water Data Online variables can be accessed using these functions:
| Water Course Discharge |
m3/s |
| Water Course Level |
m |
| Electrical conductivity at 25C |
µS/cm |
| Turbidity |
NTU |
| pH |
pH |
| Water Temperature |
ºC |
| Storage Volume |
ML |
| Storage Level |
m |
| Ground Water Level |
m |
| Rainfall |
mm |
| Evaporation |
mm |
| Dry Air Temperature |
ºC |
| Relative Humidity |
% |
| Wind Speed |
m/s |
Quality codes
The following table is from the (BoM SOS2 manual) (6.3.3, pg 41) and summarises the quality codes.
| 10 |
A |
The record set is the best available given the technologies, techniques and monitoring objectives at the time of classification. |
| 90 |
B |
The record set is compromised in its ability to truly represent the parameter. |
| 110 |
C |
The record set is an estimate. |
| 140 |
E |
The record set’s ability to truly represent the monitored parameter is not known. |
| 210 |
F |
The record set is not of release quality or contains missing data. |
Load packages
Load bomWater as well as ggplot to make some plots.
library(bomWater)
library(ggplot2)
Using parameters()
The parameter names can be retrieved from bomWater using parameters(). parameters() takes no argument. Make sure the formatting of the parameter types is as returned by this function otherwise an error may be raised.
Results
Returns a vector of parameter types.
Example
parameters()
#> [1] "Rainfall" "Evaporation"
#> [3] "Dry Air Temperature" "Relative Humidity"
#> [5] "Wind Speed" "Electrical Conductivity At 25C"
#> [7] "Turbidity" "pH"
#> [9] "Water Temperature" "Ground Water Level"
#> [11] "Water Course Level" "Water Course Discharge"
#> [13] "Storage Level" "Storage Volume"
Using get_station_list()
‘get_station_list’ queries Water Data Online and returns station details. Queries can be input with the desired ‘parameter_type’ to find all the stations on record. If you already have a vector of station numbers, you can pass the vector to ‘station_number’ and return the details of those stations. ‘return_fields’ can be customised to return various data about the stations.
Results
With the default return fields, a tibble with columns station_name, station_no, station_id, station_latitude, station_longitude.
Example
# Get a list of groundwater bores available from water data online
get_station_list(parameter_type = "Ground Water Level")
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 4,440 x 5
#> station_name station_no station_id station_latitude station_longitude
#> <chr> <chr> <int> <dbl> <dbl>
#> 1 01/DD01 D 60930131 387998 -33.2 118.
#> 2 01/DD01 OB 60930132 388003 -33.2 118.
#> 3 01/DD04 S 60930135 388008 -33.2 118.
#> 4 02/DD25 OB 60930141 388013 -33.2 118.
#> 5 02/DD26 OB 60930142 388018 -33.2 118.
#> 6 02/DD27 OB 60930143 388023 -33.2 118.
#> 7 02/DD28 OB 60930144 388028 -33.2 118.
#> 8 02/DD29 OB 60930145 388033 -33.2 118.
#> 9 02/DD30 OB 60930146 388038 -33.2 118.
#> 10 02/DD31 OB 60930147 388043 -33.2 118.
#> # … with 4,430 more rows
# Return information for a single station and customise return fields
get_station_list(station_number = "410730")
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 1 x 5
#> station_name station_no station_id station_latitude station_longitude
#> <chr> <int> <int> <dbl> <dbl>
#> 1 Cotter R. at Gingera 410730 13360 -35.6 149.
Using get_hourly()
get_hourly returns hourly data. Only Water Course Discharge, Water Course Level, Storage Level and Storage Volume can be requested using get_hourly.
Result
Returns a tibble with Timestamp, Value and Quality Code.
Example
# Cotter River at Gingera
get_hourly(
parameter_type = "Water Course Discharge",
station_number = "410730",
start_date = "2020-01-01",
end_date = "2020-01-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 744 x 3
#> Timestamp Value `Quality Code`
#> <dttm> <dbl> <int>
#> 1 2020-01-01 00:00:00 0.013 10
#> 2 2020-01-01 01:00:00 0.013 10
#> 3 2020-01-01 02:00:00 0.014 10
#> 4 2020-01-01 03:00:00 0.014 10
#> 5 2020-01-01 04:00:00 0.014 10
#> 6 2020-01-01 05:00:00 0.014 10
#> 7 2020-01-01 06:00:00 0.014 10
#> 8 2020-01-01 07:00:00 0.014 10
#> 9 2020-01-01 08:00:00 0.015 10
#> 10 2020-01-01 09:00:00 0.015 10
#> # … with 734 more rows
# Corin Reservoir
get_hourly(
parameter_type = "Storage Volume",
station_number = "410742",
start_date = "2020-01-01",
end_date = "2020-01-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 744 x 3
#> Timestamp Value `Quality Code`
#> <dttm> <dbl> <int>
#> 1 2020-01-01 00:00:00 13109. 10
#> 2 2020-01-01 01:00:00 13108. 10
#> 3 2020-01-01 02:00:00 13108. 10
#> 4 2020-01-01 03:00:00 13107. 10
#> 5 2020-01-01 04:00:00 13107. 10
#> 6 2020-01-01 05:00:00 13106. 10
#> 7 2020-01-01 06:00:00 13105. 10
#> 8 2020-01-01 07:00:00 13104. 10
#> 9 2020-01-01 08:00:00 13103. 10
#> 10 2020-01-01 09:00:00 13102. 10
#> # … with 734 more rows
An example of plotting the data:
corin <- get_hourly(
parameter_type = "Storage Volume",
station_number = "410742",
start_date = "2020-01-01",
end_date = "2020-01-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
ggplot(corin, aes(Timestamp, Value)) +
geom_line() +
labs(x = "Time", y = "Storage Volume (ML)")
Using get_daily()
Retrieves timeseries at a daily timestep. For continuous data, the daily mean (default), max, and min can be returned by specifying the var argument. Daily totals are returned for discrete parameters (e.g. rainfall and evaporation). Timeseries aggregated between 9am to 9am for Rainfall and Water Course Discharge can be retrieved using the aggregation argument to match the standard BoM rainfall reporting.
Result
A tibble with columns Timestamp, Value and Quality Code.
Examples
# Daily mean streamflow from Cotter River at Gingera (in m3/s) between 09-09
get_daily(
parameter_type = "Water Course Discharge",
station_number = "410730",
start_date = "2020-01-01",
end_date = "2020-01-31",
aggregation = "09HR"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 31 x 3
#> Timestamp Value `Quality Code`
#> <dttm> <dbl> <int>
#> 1 2020-01-01 09:00:00 0.014 10
#> 2 2020-01-02 09:00:00 0.013 10
#> 3 2020-01-03 09:00:00 0.013 10
#> 4 2020-01-04 09:00:00 0.01 10
#> 5 2020-01-05 09:00:00 0.008 10
#> 6 2020-01-06 09:00:00 0.012 10
#> 7 2020-01-07 09:00:00 0.019 10
#> 8 2020-01-08 09:00:00 0.021 10
#> 9 2020-01-09 09:00:00 0.018 10
#> 10 2020-01-10 09:00:00 0.016 10
#> # … with 21 more rows
# Daily max, only available over the standard day
get_daily(
parameter_type = "Water Course Discharge",
station_number = "410730",
start_date = "2020-01-01",
end_date = "2020-01-31",
var = "max"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 31 x 3
#> Timestamp Value `Quality Code`
#> <dttm> <dbl> <int>
#> 1 2020-01-01 00:00:00 0.015 10
#> 2 2020-01-02 00:00:00 0.014 10
#> 3 2020-01-03 00:00:00 0.013 10
#> 4 2020-01-04 00:00:00 0.01 10
#> 5 2020-01-05 00:00:00 0.012 10
#> 6 2020-01-06 00:00:00 0.02 10
#> 7 2020-01-07 00:00:00 0.026 10
#> 8 2020-01-08 00:00:00 0.019 10
#> 9 2020-01-09 00:00:00 0.018 10
#> 10 2020-01-10 00:00:00 0.016 10
#> # … with 21 more rows
# Daily mean wind speed at Corin Dam
get_daily(
parameter_type = "Wind Speed",
station_number = "570947",
start_date = "2020-01-01",
end_date = "2020-01-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 31 x 3
#> Timestamp Value `Quality Code`
#> <dttm> <dbl> <int>
#> 1 2020-01-01 00:00:00 4.9 10
#> 2 2020-01-02 00:00:00 4.07 10
#> 3 2020-01-03 00:00:00 4.43 10
#> 4 2020-01-04 00:00:00 7.43 10
#> 5 2020-01-05 00:00:00 5.66 10
#> 6 2020-01-06 00:00:00 2.87 10
#> 7 2020-01-07 00:00:00 5.95 10
#> 8 2020-01-08 00:00:00 5.65 10
#> 9 2020-01-09 00:00:00 5.3 10
#> 10 2020-01-10 00:00:00 5.89 10
#> # … with 21 more rows
Using get_monthly()
Retrieves timeseries at a monthly timestep. Monthly totals are returned for discrete parameters (e.g. rainfall and evaporation), while the mean rate is returned for continuous parameters.
Result
A tibble with columns Timestamp, Value and Quality Code.
Examples
# Monthly total rainfall in mm at Cotter Hut
get_monthly(
parameter_type = "Rainfall",
station_number = "570946",
start_date = "2019-01-01",
end_date = "2019-12-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 12 x 3
#> Timestamp Value `Quality Code`
#> <dttm> <dbl> <int>
#> 1 2019-01-01 00:00:00 57.2 10
#> 2 2019-02-01 00:00:00 23.2 10
#> 3 2019-03-01 00:00:00 89.2 10
#> 4 2019-04-01 00:00:00 11.2 10
#> 5 2019-05-01 00:00:00 111. 10
#> 6 2019-06-01 00:00:00 44.8 10
#> 7 2019-07-01 00:00:00 38 10
#> 8 2019-08-01 00:00:00 50.8 10
#> 9 2019-09-01 00:00:00 50.8 10
#> 10 2019-10-01 00:00:00 53.6 10
#> 11 2019-11-01 00:00:00 41.2 10
#> 12 2019-12-01 00:00:00 8 10
# Monthly mean streamflow rate m3/s at Cotter River at Gingera
get_monthly(
parameter_type = "Water Course Discharge",
station_number = "410730",
start_date = "2019-01-01",
end_date = "2019-12-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 12 x 3
#> Timestamp Value `Quality Code`
#> <dttm> <dbl> <int>
#> 1 2019-01-01 00:00:00 0.188 10
#> 2 2019-02-01 00:00:00 0.08 10
#> 3 2019-03-01 00:00:00 0.094 10
#> 4 2019-04-01 00:00:00 0.086 10
#> 5 2019-05-01 00:00:00 0.18 10
#> 6 2019-06-01 00:00:00 0.237 10
#> 7 2019-07-01 00:00:00 0.283 10
#> 8 2019-08-01 00:00:00 0.378 10
#> 9 2019-09-01 00:00:00 0.409 10
#> 10 2019-10-01 00:00:00 0.285 10
#> 11 2019-11-01 00:00:00 0.18 10
#> 12 2019-12-01 00:00:00 0.054 10
# Monthly evaporation at Blowering Dam
get_monthly(
parameter_type = "Evaporation",
station_number = "410102",
start_date = "2019-01-01",
end_date = "2019-12-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 0 x 3
#> # … with 3 variables: Timestamp <chr>, Value <chr>, `Quality Code` <chr>
# No data
Using get_yearly()
Retrieves timeseries at an annual timestep. Annual totals are returned for discrete parameters (e.g. rainfall and evaporation), while the mean rate is returned for continuous parameters.
Result
A tibble with columns Timestamp, Value and Quality Code.
Examples
# Annual rainfall at Berthong in Cootamundra
berthong <- get_yearly(
parameter_type = "Rainfall",
station_number = "41000207",
start_date = "2010-01-01",
end_date = "2019-12-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
# Example plot
ggplot(berthong, aes(Timestamp, Value)) +
geom_col() +
labs(x = "Time", y = "Rainfall (mm/year)")
Using get_as_stored()
Retrieves timeseries as stored by the BoM. Stored frequency could vary substantially between different parameters and locations.
Result
A tibble with columns Timestamp, Value and Quality Code.
Examples
# Annual rainfall at Berthong in Cootamundra
berthong <- get_as_stored(
parameter_type = "Rainfall",
station_number = "41000207",
start_date = "2019-01-01",
end_date = "2019-12-31"
)
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
#> No encoding supplied: defaulting to UTF-8.
berthong
#> # A tibble: 9,896 x 3
#> Timestamp Value `Quality Code`
#> <dttm> <dbl> <int>
#> 1 2019-01-01 00:00:00 0 140
#> 2 2019-01-01 01:00:00 0 140
#> 3 2019-01-01 02:00:00 0 140
#> 4 2019-01-01 03:00:00 0 140
#> 5 2019-01-01 04:00:00 0 140
#> 6 2019-01-01 05:00:00 0 140
#> 7 2019-01-01 06:00:00 0 140
#> 8 2019-01-01 07:00:00 0 140
#> 9 2019-01-01 08:00:00 0 140
#> 10 2019-01-01 09:00:00 0 140
#> # … with 9,886 more rows