Help for package weatherOz

Title:

An API Client for Australian Weather and Climate Data Resources

Version:

2.0.1

Description:

Provides automated downloading, parsing and formatting of weather data for Australia through API endpoints provided by the Department of Primary Industries and Regional Development ('DPIRD') of Western Australia and by the Science and Technology Division of the Queensland Government's Department of Environment and Science ('DES'). As well as the Bureau of Meteorology ('BOM') of the Australian government precis and coastal forecasts, and downloading and importing radar and satellite imagery files. 'DPIRD' weather data are accessed through public 'APIs' provided by 'DPIRD', https://www.agric.wa.gov.au/weather-api-20, providing access to weather station data from the 'DPIRD' weather station network. Australia-wide weather data are based on data from the Australian Bureau of Meteorology ('BOM') data and accessed through 'SILO' (Scientific Information for Land Owners) Jeffrey et al. (2001) <doi:10.1016/S1364-8152(01)00008-1>. 'DPIRD' data are made available under a Creative Commons Attribution 3.0 Licence (CC BY 3.0 AU) license https://creativecommons.org/licenses/by/3.0/au/deed.en. SILO data are released under a Creative Commons Attribution 4.0 International licence (CC BY 4.0) https://creativecommons.org/licenses/by/4.0/. 'BOM' data are (c) Australian Government Bureau of Meteorology and released under a Creative Commons (CC) Attribution 3.0 licence or Public Access Licence ('PAL') as appropriate, see http://www.bom.gov.au/other/copyright.shtml for further details.

License:

GPL (≥ 3)

URL:

https://github.com/ropensci/weatherOz/, https://docs.ropensci.org/weatherOz/

BugReports:

https://github.com/ropensci/weatherOz/issues

Depends:

R (≥ 4.1.0)

Imports:

apsimx, clock, crayon, crul, curl, data.table (≥ 1.1.5), foreign, grDevices, jsonlite, knitr, lubridate, magick, methods, sf, stars, stats, terra, utils, xml2

Suggests:

covr, dplyr, ggplot2, ggthemes, grid, gridExtra, mailR, mapproj, maps, rmarkdown, roxyglobals, spelling, testthat (≥ 3.0.0), usethis, vcr (≥ 0.6.0), vdiffr, withr

VignetteBuilder:

knitr

Config/roxyglobals/filename:

globals.R

Config/roxyglobals/unique:

FALSE

Config/testthat/edition:

Config/testthat/parallel:

true

Encoding:

UTF-8

Language:

en-US

LazyData:

true

RoxygenNote:

7.3.2

X-schema.org-applicationCategory:

Tools

X-schema.org-isPartOf:

https://ropensci.org

X-schema.org-keywords:

dpird, bom, meteorological-data, weather-forecast, australia, weather, weather-data, meteorology, western-australia, australia-bureau-of-meteorology, western-australia-agriculture, australia-agriculture, australia-climate, australia-weather

NeedsCompilation:

Packaged:

2025-04-16 03:11:12 UTC; dpird-mac

Author:

Rodrigo Pires

[aut, cre], Anna Hepworth

[aut], Rebecca O'Leary [aut], Jonathan Carroll

[aut], James Goldie

[aut], Dean Marchiori

[aut], Paul Melloy

[aut], Mark Padgham

[aut], Hugh Parsonage

[aut], Keith Pembleton

[ctb] (Contributed code and ideas for original 'bomrang' package that was used in the creation of 'weatherOz'.), Maëlle Salmon

[ctb] (Contributed to debugging a nasty little bug with CI where timezones caused tests to fail due to 'vcr' not recognising the URL when run outside of Australia/Perth TZ! Suggested the use of `withr::local_timzeone()`, see <https://github.com/ropensci/weatherOz/commit/b052bf91973b8d7e147a39e8938405a64622634b>.), Max Moldovan

[ctb] (Contributed valuable feedback on package usage leading to improvements in the package structure and functionality.), Jimmy Ng [ctb], Steve Collins [ctb] (Designed the hex logo for 'weatherOz' hex logo.), Adam H. Sparks

[aut], Laurens Geffert [rev], Sam Rogers [rev], Western Australia Agriculture Authority (WAAA) [cph], Curtin University [cph]

Maintainer:

Rodrigo Pires <rodrigo.pires@dpird.wa.gov.au>

Repository:

CRAN

Date/Publication:

2025-04-16 04:50:02 UTC

weatherOz: An API Client for Australian Weather and Climate Data Resources

Description

Provides automated downloading, parsing and formatting of weather data for Australia through API endpoints provided by the Department of Primary Industries and Regional Development ('DPIRD') of Western Australia and by the Science and Technology Division of the Queensland Government's Department of Environment and Science ('DES'). As well as the Bureau of Meteorology ('BOM') of the Australian government precis and coastal forecasts, and downloading and importing radar and satellite imagery files. 'DPIRD' weather data are accessed through public 'APIs' provided by 'DPIRD', https://www.agric.wa.gov.au/weather-api-20, providing access to weather station data from the 'DPIRD' weather station network. Australia-wide weather data are based on data from the Australian Bureau of Meteorology ('BOM') data and accessed through 'SILO' (Scientific Information for Land Owners) Jeffrey et al. (2001) doi:10.1016/S1364-8152(01)00008-1. 'DPIRD' data are made available under a Creative Commons Attribution 3.0 Licence (CC BY 3.0 AU) license https://creativecommons.org/licenses/by/3.0/au/deed.en. SILO data are released under a Creative Commons Attribution 4.0 International licence (CC BY 4.0) https://creativecommons.org/licenses/by/4.0/. 'BOM' data are (c) Australian Government Bureau of Meteorology and released under a Creative Commons (CC) Attribution 3.0 licence or Public Access Licence ('PAL') as appropriate, see http://www.bom.gov.au/other/copyright.shtml for further details.

Author(s)

Maintainer: Rodrigo Pires rodrigo.pires@dpird.wa.gov.au (ORCID)

Authors:

Anna Hepworth anna.hepworth@gmail.com (ORCID)
Rebecca O'Leary bec.oleary@curtin.edu.au
Jonathan Carroll rpkg@jcarroll.com.au (ORCID)
James Goldie me@jamesgoldie.dev (ORCID)
Dean Marchiori deanmarchiori@gmail.com (ORCID)
Paul Melloy paul@melloy.com.au (ORCID)
Mark Padgham mark.padgham@email.com (ORCID)
Hugh Parsonage hugh.parsonage@gmail.com (ORCID)
Adam H. Sparks adamhsparks@gmail.com (ORCID)

Other contributors:

Keith Pembleton keith.pembleton@unisq.edu.au (ORCID) (Contributed code and ideas for original 'bomrang' package that was used in the creation of 'weatherOz'.) [contributor]
Maëlle Salmon maelle.salmon@yahoo.se (ORCID) (Contributed to debugging a nasty little bug with CI where timezones caused tests to fail due to 'vcr' not recognising the URL when run outside of Australia/Perth TZ! Suggested the use of 'withr::local_timzeone()', see <https://github.com/ropensci/weatherOz/commit/b052bf91973b8d7e147a39e8938405a64622634b>.) [contributor]
Max Moldovan max.moldovan@adelaide.edu.au (ORCID) (Contributed valuable feedback on package usage leading to improvements in the package structure and functionality.) [contributor]
Jimmy Ng jimmy.ng@dpird.wa.gov.au [contributor]
Steve Collins steve.collins@dpird.wa.gov.au (Designed the hex logo for 'weatherOz' hex logo.) [contributor]
Laurens Geffert laurensgeffert@gmail.com [reviewer]
Sam Rogers sam.rogers@adelaide.edu.au [reviewer]
Western Australia Agriculture Authority (WAAA) [copyright holder]
Curtin University [copyright holder]

A List of DPIRD Extreme Weather Data Values

Description

A vector object containing 57 items representing valid values to supply to get_dpird_extremes()'s values argument taken from the documentation for the DPIRD Weather 2.0 API.

Usage

dpird_extreme_weather_values

Format

A vector object of 57 items.

Source

https://www.agric.wa.gov.au/weather-api-20

A List of DPIRD Minute Weather Data Values

Description

A vector object containing 12 items representing valid values to supply to get_dpird_minute()'s values argument taken from the documentation for the DPIRD Weather 2.0 API.

Usage

dpird_minute_values

Format

A vector object of 12 items.

Source

https://www.agric.wa.gov.au/weather-api-20

A List of DPIRD Summary Weather Data Values

Description

A vector object containing 75 items representing valid values to supply to get_dpird_summary()'s values argument taken from the documentation for the DPIRD Weather 2.0 API.

Usage

dpird_summary_values

Format

A vector object of 75 items.

Source

https://www.agric.wa.gov.au/weather-api-20

Find the Nearest Town With a BOM Forecast

Description

For a given latitude and longitude, find the nearest town that the BOM provides a forecast for.

Usage

find_forecast_towns(longitude = 149.2, latitude = -35.3, distance_km = 100)

Arguments

longitude

A numeric value of longitude in decimal degree (DD) format. By default, Canberra (approximately).

latitude

A numeric value of latitude in decimal degree (DD) format. By default, Canberra (approximately).

distance_km

A numeric value of the distance in kilometres from the latitude and longitude point beyond which values will not be returned.

Value

A data.table::data.table() of all forecast towns (in this package) sorted by distance from latitude and longitude, ascending.

Author(s)

Hugh Parsonage, hugh.parsonage@gmail.com, and James Goldie, me@jamesgoldie.dev, and Adam H. Sparks, adamhsparks@gmail.com

Examples



# find forecast towns near Esperance, WA
find_forecast_towns(longitude = 121.8913, latitude = -33.8614)

Find the Nearest Weather Stations to a Given Geographic Point or Known Station

Description

Find nearby weather stations given geographic coordinates or a station code for both of the DPIRD and SILO weather station networks. Either a combination of latitude and longitude or station_code must be provided. A DPIRD API key is only necessary to search for stations in the DPIRD network. If you are not interested in DPIRD stations in Western Australia, you may use this function to query only SILO stations for all of Australia without using a key.

Usage

find_nearby_stations(
  longitude = NULL,
  latitude = NULL,
  station_code = NULL,
  distance_km = 100,
  api_key = NULL,
  which_api = "silo",
  include_closed = FALSE
)

Arguments

longitude

A numeric value of longitude in decimal degree (DD) format. Optional and defaults to NULL. Required if station_code is not provided.

latitude

A numeric value of latitude in decimal degree (DD) format. Optional and defaults to NULL. Required if station_code is not provided.

station_code

A string with the station code for the station of interest. Optional and defaults to NULL. Required if longitude and latitude are not provided.

distance_km

A numeric value for distance to limit the search from the station or location of interest. Defaults to 100 km.

api_key

A character string containing your API key from DPIRD, https://www.agric.wa.gov.au/web-apis, for the DPIRD Weather 2.0 API. If left as NULL, defaults to automatically detecting your key from your local .Renviron, .Rprofile or similar. Alternatively, you may directly provide your key as a string here. If nothing is provided, you will be prompted on how to set up your R session so that it is auto-detected. Only used when which_api is DPIRD or all.

which_api

A string value that indicates which API to use. Defaults to silo only. Valid values are all, for both SILO (BOM) and DPIRD weather station networks; silo for only stations in the SILO network; or dpird for stations in the DPIRD network.

include_closed

A Boolean value that indicates whether closed stations in the DPIRD network should be included in the results. Defaults to FALSE with closed stations not included.

Value

A data.table::data.table() with station_code, station_name, latitude, longitude, elev_m, state, owner, and distance. Data are sorted by increasing distance from station or location of interest.

Note

You can request your own API key from DPIRD for free by filling out the form found at https://www.agric.wa.gov.au/web-apis.

Author(s)

Rodrigo Pires, rodrigo.pires@dpird.wa.gov.au, and Adam H. Sparks, adamhsparks@gmail.com

Examples

## Not run: 

# Note that queries to the DPIRD API require you to have your own API key.

# Query WA only stations and return DPIRD's stations nearest to the
# Northam, WA station, "NO", returning stations with 50 km of this station

wa_stn <- find_nearby_stations(
  station_code = "NO",
  distance_km = 50,
  api_key = "your_api_key",
  which_api = "dpird"
)

# Query stations nearest DPIRD's Northam, WA station, "NO" and return both
# DPIRD and SILO/BOM stations within 50 km of this station.

wa_stn <- find_nearby_stations(
  station_code = "NO",
  distance_km = 50,
  api_key = "your_api_key",
  which_api = "all"
)

# Query Wagga Wagga BOM station finding stations within 200 km of it, note
# that it is not necessary to provide an `api_key` for SILO queries of
# nearby stations.

wagga_stn <- find_nearby_stations(
  latitude = -35.1583,
  longitude = 147.4575,
  distance_km = 200,
  which_api = "silo"
)

## End(Not run)

Find Stations Within a Geospatially Defined Geographic Area of Interest

Description

Given an sf polygon or a bounding box as a vector with the minimum and maximum longitude and latitude values, find DPIRD or BOM stations in the SILO network that fall within that defined area or the station nearest the centroid of the area of interest.

Usage

find_stations_in(
  x,
  centroid = FALSE,
  api_key = NULL,
  which_api = "all",
  include_closed = FALSE,
  crs = "EPSG:7844"
)

Arguments

x

One of two types of object:

A Vector A four-digit vector defining a bounding box of the area of interest in this order, ‘xmin’, ‘ymin’, ‘xmax’, ‘ymax’, or
An object of class sf defining the area of interest.

centroid

Boolean A value of TRUE or FALSE indicating whether you want the centroid only to be used to find the nearest station to the centre of the area of interest. If “n” polygons are supplied, “n” stations are returned. Defaults to FALSE with all stations within the area of interest returned.

api_key

which_api

include_closed

A Boolean value that indicates whether closed stations in the DPIRD network should be included in the results. Defaults to FALSE with closed stations not included.

crs

A string value that provides the coordinate reference system, AKA, "projection" to be used for the point extraction. Defaults to GDA 2020, EPSG:7844. NOTE This will override any crs value that your . polygon provides unless you specify it again here, e.g., crs = sf::st_crs(polygon_object_name).

Value

a data.table object of weather station(s) within the defined area of interest in an unprojected format, EPSG:4326, WGS 84 – WGS84 - World Geodetic System 1984, used in GPS format.

Examples



# using a (generous) bounding box for Melbourne, Vic using only the SILO API
# for BOM stations, so no API key is needed.

bbox <- find_stations_in(
  x = c(144.470215, -38.160476, 145.612793, -37.622934),
  which_api = "SILO",
  include_closed = TRUE
)
bbox

# Use the same bounding box but only find a single station nearest
# the centroid using only the SILO API for BOM stations

centroid <- find_stations_in(
  x = c(144.470215, -38.160476, 145.612793, -37.622934),
  which_api = "SILO",
  include_closed = TRUE,
  centroid = TRUE
)
centroid

# Use the `south_west_agricultural_region` data to fetch stations only in the
# south-western portion of WA and plot it with {ggplot2} showing open/closed
# stations just to be sure they're inside the area of interest.

# As this is in WA, we can use the DPIRD network, so we need our API key.
# Using the `south_west_agricultural_region` {sf} object provided.

sw_wa <- find_stations_in(
  x = south_west_agricultural_region,
  api_key = "your_api_key",
  include_closed = TRUE
)

sw_wa

Get a BOM Agriculture Bulletin

Description

Defunct: This function is defunct as of version 2.0.0 because the underlying BOM agricultural forecast bulletin service is no longer available.

Usage

get_ag_bulletin(state = "AUS")

Arguments

state

Australian state or territory as full name or postal code. Fuzzy string matching via base::agrep() is done. Defaults to AUS returning all state bulletins, see Details for more.

Details

Fetch the BOM agricultural bulletin information for a specified station or stations.

Allowed state and territory postal codes, only one state per request or all using 'AUS'.

AUS: Australia, returns forecast for all states, NT and ACT
ACT: Australian Capital Territory (will return NSW)
NSW: New South Wales
NT: Northern Territory
QLD: Queensland
SA: South Australia
TAS: Tasmania
VIC: Victoria
WA: Western Australia

Value

A data frame as a weatherOz_tbl object (inherits and is fully compatible with data.table::data.table()) of Australia BOM agricultural bulletin information.

Note

Data and Information Use Please note the copyright notice and disclaimer, http://www.bom.gov.au/other/copyright.shtml related to the use of this information. Users of this information are deemed to have read and accepted the conditions described therein.

Author(s)

Adam H. Sparks, adamhsparks@gmail.com, and Paul Melloy, paul@melloy.com.au

References

Agricultural observations are retrieved from the Australian Bureau of Meteorology (BOM) Weather Data Services Agriculture Bulletins,
http://www.bom.gov.au/catalogue/observations/about-agricultural.shtml.

And also,

Australian Bureau of Meteorology (BOM)) Weather Data Services Observation of Rainfall,
http://www.bom.gov.au/climate/how/observations/rain-measure.shtml.

Station location and other metadata are sourced from the Australian Bureau of Meteorology (BOM) webpage, Bureau of Meteorology Site Numbers:
http://www.bom.gov.au/climate/cdo/about/site-num.shtml.

Examples



get_ag_bulletin(state = "QLD")

Get a List of Available BOM Satellite Imagery

Description

Fetch a listing of BOM GeoTIFF satellite imagery from ftp://ftp.bom.gov.au/anon/gen/gms/ to determine which files are currently available for download. Files are available at ten minute update frequency with a 24-hour delete time. It is useful to know the most recent files available and then specify in the get_satellite_imagery() function. Ported from bomrang.

Usage

get_available_imagery(product_id = "all")

Arguments

product_id

Character. BOM product ID of interest for which a list of available images will be returned. Defaults to all images currently available.

Details

Valid BOM satellite Product IDs for GeoTIFF files include:

IDE00420: AHI cloud cover only 2km FD GEOS GIS
IDE00421: AHI IR (Ch13) greyscale 2km FD GEOS GIS
IDE00422: AHI VIS (Ch3) greyscale 2km FD GEOS GIS
IDE00423: AHI IR (Ch13) Zehr 2km FD GEOS GIS
IDE00425: AHI VIS (true colour) / IR (Ch13 greyscale) composite 1km FD GEOS GIS
IDE00426: AHI VIS (true colour) / IR (Ch13 greyscale) composite 2km FD GEOS GIS
IDE00427: AHI WV (Ch8) 2km FD GEOS GIS
IDE00430: AHI cloud cover only 2km AUS equirect. GIS
IDE00431: AHI IR (Ch13) greyscale 2km AUS equirect. GIS
IDE00432: AHI VIS (Ch3) greyscale 2km AUS equirect. GIS
IDE00433: AHI IR (Ch13) Zehr 2km AUS equirect. GIS
IDE00435: AHI VIS (true colour) / IR (Ch13 greyscale) composite 1km AUS equirect. GIS
IDE00436: AHI VIS (true colour) / IR (Ch13 greyscale) composite 2km AUS equirect. GIS
IDE00437: AHI WV (Ch8) 2km AUS equirect. GIS
IDE00439: AHI VIS (Ch3) greyscale 0.5km AUS equirect. GIS

Value

A vector of all available files for the requested Product ID(s).

Author(s)

Adam H. Sparks, adamhsparks@gmail.com

References

Australian Bureau of Meteorology (BOM) high-definition satellite images http://www.bom.gov.au/australia/satellite/index.shtml

Examples


# Check availability of AHI VIS (true colour) / IR (Ch13 greyscale) composite
# 1km FD GEOS GIS images
imagery <- get_available_imagery(product_id = "IDE00425")

imagery

Get a List of Available BOM Radar Imagery

Description

Fetch a listing of available BOM radar imagery from ftp://ftp.bom.gov.au/anon/gen/radar/ to determine which files are currently available for download. The files available are the most recent radar imagery for each location, which are updated approximately every 6 to 10 minutes by the BOM. Ported from bomrang.

Usage

get_available_radar(radar_id = "all")

Arguments

radar_id

Numeric. BOM radar of interest for which a list of available images will be returned. Defaults to all images currently available.

Details

Valid BOM radar ID for each location required.

Value

A data.table::data.table() of all selected radar locations with location information and product_ids.

Author(s)

Dean Marchiori, deanmarchiori@gmail.com, and Adam H. Sparks, adamhsparks@gmail.com

References

Australian Bureau of Meteorology (BOM) radar image http://www.bom.gov.au/australia/radar/.

Examples



# Check availability radar imagery for Wollongong (radar_id = 3)
imagery <- get_available_radar(radar_id = 3)

imagery

Get a BOM Coastal Waters Forecast

Description

Fetch the BOM daily Coastal Waters Forecast for a specified state or region.

Usage

get_coastal_forecast(state = "AUS")

Arguments

state

Australian state or territory as full name or postal code. Fuzzy string matching via base::agrep() is done. Defaults to AUS returning all state forecasts, see details for further information.

Details

Allowed state and territory postal codes, only one state per request or all using 'AUS':

AUS: Australia, returns forecast for all states, NT and ACT
ACT: Australian Capital Territory (will return NSW)
NSW: New South Wales
NT: Northern Territory
QLD: Queensland
SA: South Australia
TAS: Tasmania
VIC: Victoria
WA: Western Australia

Value

A data.table::data.table() of an Australia BOM Coastal Waters Forecast.

Author(s)

Dean Marchiori, deanmarchiori@gmail.com, and Paul Melloy, paul@melloy.com.au

References

Forecast data come from Australian Bureau of Meteorology (BOM) Weather Data Services
http://www.bom.gov.au/catalogue/data-feeds.shtml.

And also,

Location data and other metadata come from the BOM anonymous FTP server with spatial data
ftp://ftp.bom.gov.au/anon/home/adfd/spatial/, specifically the DBF file portion of a shapefile,
ftp://ftp.bom.gov.au/anon/home/adfd/spatial/IDM00003.dbf.

Examples



get_coastal_forecast(state = "NSW")

Get DataDrill Weather Data From SILO

Description

Fetch nicely formatted weather data from the SILO API of spatially interpolated weather data (DataDrill). The daily climate surfaces have been derived either by splining or kriging the observational data. The returned values contain “source” columns, which denote how the observations were derived. The grid spans 112° to 154°, -10° to -44° with resolution 0.05° latitude by 0.05° longitude (approximately 5 km × 5 km).

Usage

get_data_drill(
  longitude,
  latitude,
  start_date,
  end_date = Sys.Date(),
  values = "all",
  api_key = get_key(service = "SILO")
)

Arguments

longitude

A single numeric value representing the longitude of the point-of-interest to the hundredths (e.g., 0.05) of a degree.

latitude

A single numeric value representing the latitude of the point-of-interest to the hundredths (e.g.., 0.05) of a degree.

start_date

A character string or Date object representing the beginning of the range to query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date.

end_date

A character string or Date object representing the end of the range query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date. Defaults to the current system date.

values

A character string with the type of weather data to return. See Available Values for a full list of valid values. Defaults to all with all available values being returned.

api_key

A character string containing your API key, an e-mail address, for the request. Defaults to automatically detecting your key from your local .Renviron, .Rprofile or similar. Alternatively, you may directly provide your key as a string here. If nothing is provided, you will be prompted on how to set up your R session so that it is auto-detected.

Value

a data.table::data.table() with the weather data queried with the weather variables in alphabetical order. The first eight columns will always be:

longitude,
latitude,
elev_m (elevation in metres),
date (ISO8601 format, YYYYMMDD),
year,
month,
day,
extracted (the date on which the query was made)

Column Name Details

Available Values

all: Which will return all of the following values
rain (mm): Rainfall
max_temp (degrees C): Maximum temperature
min_temp (degrees C): Minimum temperature
vp (hPa): Vapour pressure
vp_deficit (hPa): Vapour pressure deficit
evap_pan (mm): Class A pan evaporation
evap_syn (mm): Synthetic estimate¹
evap_comb (mm): Combination (synthetic estimate pre-1970, class A pan 1970 onwards)
evap_morton_lake (mm): Morton's shallow lake evaporation
radiation (Mj/m²): Solar exposure, consisting of both direct and diffuse components
rh_tmax (%): Relative humidity at the time of maximum temperature
rh_tmin (%): Relative humidity at the time of minimum temperature
et_short_crop (mm): FAO56⁴
short crop
et_tall_crop (mm): ASCE⁵
tall crop⁶
et_morton_actual (mm): Morton's areal actual evapotranspiration
et_morton_potential (mm): Morton's point potential evapotranspiration
et_morton_wet (mm): Morton's wet-environment areal potential evapotranspiration over land
mslp (hPa): Mean sea level pressure

Value information

Solar radiation: total incoming downward shortwave radiation on a horizontal surface, derived from estimates of cloud oktas and sunshine duration³.

Relative humidity: calculated using the vapour pressure measured at 9am, and the saturation vapour pressure computed using either the maximum or minimum temperature⁶.

Evaporation and evapotranspiration: an overview of the variables provided by SILO is available here, https://data.longpaddock.qld.gov.au/static/publications/Evapotranspiration_overview.pdf.

Data codes

Data codes Where possible (depending on the file format), the data are supplied with codes indicating how each datum was obtained.

0: Official observation as supplied by the Bureau of Meteorology
15: Deaccumulated rainfall (original observation was recorded over a period exceeding the standard 24 hour observation period)
25: Interpolated from daily observations for that date
26: Synthetic Class A pan evaporation, calculated from temperatures, radiation and vapour pressure
35: Interpolated from daily observations using an anomaly interpolation method
75: Interpolated from the long term averages of daily observations for that day of year

Author(s)

Rodrigo Pires, rodrigo.pires@dpird.wa.gov.au, and Adam H. Sparks, adamhsparks@gmail.com

References

Rayner, D. (2005). Australian synthetic daily Class A pan evaporation. Technical Report December 2005, Queensland Department of Natural Resources and Mines, Indooroopilly, Qld., Australia, 40 pp.
Morton, F. I. (1983). Operational estimates of areal evapotranspiration and their significance to the science and practice of hydrology, Journal of Hydrology, Volume 66, 1-76.
Zajaczkowski, J., Wong, K., & Carter, J. (2013). Improved historical solar radiation gridded data for Australia, Environmental Modelling & Software, Volume 49, 64–77. DOI: doi:10.1016/j.envsoft.2013.06.013.
Food and Agriculture Organization of the United Nations, Irrigation and drainage paper 56: Crop evapotranspiration - Guidelines for computing crop water requirements, 1998.
ASCE’s Standardized Reference Evapotranspiration Equation, proceedings of the National Irrigation Symposium, Phoenix, Arizona, 2000.
For further details refer to Jeffrey, S.J., Carter, J.O., Moodie, K.B. and Beswick, A.R. (2001). Using spatial interpolation to construct a comprehensive archive of Australian climate data, Environmental Modelling and Software, Volume 16/4, 309-330. DOI: doi:10.1016/S1364-8152(01)00008-1.

Examples

## Not run: 
# requires an API key as your email address
# Source data from latitude and longitude coordinates (gridded data) for
# max and minimum temperature and rainfall for Southwood, QLD.
wd <- get_data_drill(
  latitude = -27.85,
  longitude = 150.05,
  start_date = "20221001",
  end_date = "20221201",
  values = c("max_temp", "min_temp", "rain"),
  api_key = "your_api_key"
)

## End(Not run)

Get DataDrill Weather Data in the APSIM Format From SILO

Description

Fetch APSIM .met file formatted weather data from the weather data from the SILO API of spatially interpolated weather data (DataDrill). The daily climate surfaces have been derived either by splining or kriging the observational data. The returned values contain “source” columns, which denote how the observations were derived. The grid spans 112° to 154°, -10° to -44° with resolution 0.05° latitude by 0.05° longitude (approximately 5 km × 5 km).

Usage

get_data_drill_apsim(
  longitude,
  latitude,
  start_date,
  end_date = Sys.Date(),
  api_key = get_key(service = "SILO")
)

Arguments

longitude

A single numeric value representing the longitude of the point-of-interest.

latitude

A single numeric value representing the latitude of the point-of-interest.

start_date

A character string or Date object representing the beginning of the range to query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date.

end_date

A character string or Date object representing the end of the range query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date. Defaults to the current system date.

api_key

Details

Note that when saving, comments from SILO will be included, but these will not be printed as a part of the resulting met object in your R session.

Value

An apsimx object of class ‘met’ with attributes.

Included Values

rain (mm): Rainfall
maxt (degrees C): Maximum temperature
mint (degrees C): Minimum temperature
vp (hPa): Vapour pressure
evap_pan (mm): Class A pan evaporation
radiation (Mj/m¹): Solar exposure, consisting of both direct and diffuse components

Value information

Solar radiation: total incoming downward shortwave radiation on a horizontal surface, derived from estimates of cloud oktas and sunshine duration².

Evaporation and evapotranspiration: an overview of the variables provided by SILO is available here, https://data.longpaddock.qld.gov.au/static/publications/Evapotranspiration_overview.pdf.

Data codes

Where the source code is a 6 digit string comprising the source code for the 6 variables. The single digit code for each variable is:

0: an actual observation;
1: an actual observation from a composite station;
2: a value interpolated from daily observations;
3: a value interpolated from daily observations using the anomaly interpolation method for CLIMARC data;
6: a synthetic pan value; or
7: an interpolated long term average.

Saving objects

To save “met” objects the apsimx::write_apsim_met() is reexported. Note that when saving, comments from SILO will be included, but these will not be printed as a part of the resulting met object in your R session.

Author(s)

Rodrigo Pires, rodrigo.pires@dpird.wa.gov.au, and Adam Sparks, adamhsparks@gmail.com

References

Rayner, D. (2005). Australian synthetic daily Class A pan evaporation. Technical Report December 2005, Queensland Department of Natural Resources and Mines, Indooroopilly, Qld., Australia, 40 pp.
Morton, F. I. (1983). Operational estimates of areal evapotranspiration and their significance to the science and practice of hydrology, Journal of Hydrology, Volume 66, 1-76.

Examples

## Not run: 
# requires an API key as your email address
# Source data from latitude and longitude coordinates (gridded data) for
# max and minimum temperature and rainfall for Southwood, QLD.
wd <- get_data_drill_apsim(
  latitude = -27.85,
  longitude = 150.05,
  start_date = "20220101",
  end_date = "20221231",
  api_key = "your_api_key"
)

## End(Not run)

Get DPIRD Summary Weather Data in the APSIM Format From the Weather 2.0 API

Description

Automates the retrieval and conversion of summary data from the DPIRD Weather 2.0 API to an APSIM .met file formatted weather data object.

Usage

get_dpird_apsim(
  station_code,
  start_date,
  end_date = Sys.Date(),
  api_key = get_key(service = "DPIRD")
)

Arguments

station_code

A character string or factor from get_stations_metadata() of the BOM station code for the station of interest.

start_date

A character string or Date object representing the beginning of the range to query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date.

end_date

A character string or Date object representing the end of the range query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date. Defaults to the current system date.

api_key

A character string containing your API key from DPIRD, https://www.agric.wa.gov.au/web-apis, for the DPIRD Weather 2.0 API. Defaults to automatically detecting your key from your local .Renviron, .Rprofile or similar. Alternatively, you may directly provide your key as a string here. If nothing is provided, you will be prompted on how to set up your R session so that it is auto-detected.

Value

An apsimx object of class ‘met’ with attributes.

Saving objects

Author(s)

Adam H. Sparks, adamhsparks@gmail.com

Examples

## Not run: 
# Get an APSIM format object for Binnu
# Note that you need to supply your own API key

wd <- get_dpird_apsim(
  station_code = "BI",
  start_date = "20220101",
  end_date = "20221231",
  api_key = "your_api_key"
)

## End(Not run)

Get the Availability for DPIRD Weather Stations

Description

Fetch the availability metadata of weather stations in the DPIRD weather station network from the Weather 2.0 API.

Usage

get_dpird_availability(
  station_code = NULL,
  start_date = NULL,
  end_date = NULL,
  values = "availability",
  api_key = get_key(service = "DPIRD")
)

Arguments

station_code

A character string of the DPIRD station code for the station of interest. Defaults to NULL, returning metadata for all stations during the requested start_date and end_date interval.

start_date

A character string representing the beginning of the range to query in the format “yyyy-mm-dd” (ISO8601). This function will return data inclusive of this date. Defaults to NULL, returning data for the current year-to-date. Must be sent along with an end_date.

end_date

A character string representing the end of the range query in the format “yyyy-mm-dd” (ISO8601). This function will return data inclusive of this date. Defaults to NULL, returning data for the current year-to-date. Must be sent with a start_date.

values

A character string with the type of availability metadata to return. See Available Values for a full list of valid values. Defaults to availability, returning metadata for all stations.

api_key

Value

a data.table::data.table() with station_code and the requested metadata.

Available Values

availability (which will return all of the following values),
availabilityCurrentHour,
availabilityLast7DaysSince9AM,
availabilityLast7DaysSince12AM,
availabilityLast14DaysSince9AM,
availabilityLast14DaysSince12AM,
availabilityLast24Hours,
availabilityMonthToDateSince12AM,
availabilityMonthToDateTo9AM,
availabilitySince9AM,
availabilitySince12AM,
availabilityTo9AM,
availabilityYearToDateSince12AM, and
availabilityYearToDateTo9AM

Author(s)

Adam H. Sparks, adamhsparks@gmail.com

Examples

## Not run: 
# Note that you need to supply your own API key

# Here we check the up time for the current year for Westonia
WS001 <- get_dpird_availability(station_code = "WS001",
                                api_key = "your_api_key")

# Here we check the up time for 2017 for Binnu
BN <- get_dpird_availability(
  station_code = "BI",
  start_date = "20170101",
  end_date = "20171231",
  api_key = "your_api_key"
)

## End(Not run)

Get DPIRD Extreme Weather Event Summaries

Description

Fetch nicely formatted individual extreme weather summaries from the DPIRD Weather 2.0 API.

Usage

get_dpird_extremes(
  station_code,
  values = "all",
  api_key = get_key(service = "DPIRD")
)

Arguments

station_code

A character string or factor from get_stations_metadata() of the BOM station code for the station of interest.

values

A character string with the type of extreme weather to return. See Available Values for a full list of valid values. Defaults to all, returning the full list of values unless otherwise specified.

api_key

Value

a data.table::data.table() of one row with station_code, station_name, latitude, longitude, date_time of the query and the extreme weather information according to the value(s) selected.

Available Values

all (which will return all of the following values),
erosionCondition,
erosionConditionLast7Days,
erosionConditionLast7DaysDays,
erosionConditionLast7DaysMinutes,
erosionConditionLast14Days,
erosionConditionLast14DaysDays,
erosionConditionLast14DaysMinutes,
erosionConditionMonthToDate,
erosionConditionMonthToDateDays,
erosionConditionMonthToDateMinutes,
erosionConditionMonthToDateStartTime,
erosionConditionSince12AM,
erosionConditionSince12AMMinutes,
erosionConditionSince12AMStartTime,
erosionConditionYearToDate,
erosionConditionYearToDateDays,
erosionConditionYearToDateMinutes,
erosionConditionYearToDateStartTime,
frostCondition,
frostConditionLast7Days,
frostConditionLast7DaysDays,
frostConditionLast7DaysMinutes,
frostConditionLast14Days,
frostConditionLast14DaysDays,
frostConditionLast14DaysMinutes,
frostConditionMonthToDate,
frostConditionMonthToDateDays,
frostConditionMonthToDateMinutes,
frostConditionMonthToDateStartTime,
frostConditionSince9AM,
frostConditionSince9AMMinutes,
frostConditionSince9AMStartTime,
frostConditionTo9AM,
frostConditionTo9AMMinutes,
frostConditionTo9AMStartTime,
frostConditionYearToDate,
frostConditionYearToDate,
frostConditionYearToDateMinutes,
frostConditionYearToDateStartTime,
heatCondition,
heatConditionLast7Days,
heatConditionLast7DaysDays,
heatConditionLast7DaysMinutes,
heatConditionLast14Days,
heatConditionLast14DaysDays,
heatConditionLast14DaysMinutes,
heatConditionMonthToDate,
heatConditionMonthToDateDays,
heatConditionMonthToDateMinutes,
heatConditionMonthToDateStartTime,
heatConditionSince12AM,
heatConditionSince12AMMinutes,
heatConditionSince12AMStartTime,
heatConditionYearToDate,
heatConditionYearToDateDays,
heatConditionYearToDateMinutes, and
heatConditionYearToDateStartTime

Author(s)

Rodrigo Pires, rodrigo.pires@dpird.wa.gov.au, and Adam Sparks, adamhsparks@gmail.com

Examples

## Not run: 
# Query Bonnie Rock station for wind erosion and heat extreme events
# Note that you need to supply your own API key

xtreme <- get_dpird_extremes(
  station_code = "BR",
  values = c("erosionCondition",
           "heatCondition"),
  api_key = "your_api_key"
)

## End(Not run)

Get DPIRD Weather Data by the Minute

Description

Fetch nicely formatted minute weather station data from the DPIRD Weather 2.0 API for a maximum 24-hour period.

Usage

get_dpird_minute(
  station_code,
  start_date_time = lubridate::now() - lubridate::hours(24L),
  minutes = 1440L,
  values = "all",
  api_key = get_key(service = "DPIRD")
)

Arguments

station_code

A character string or factor from get_stations_metadata() of the BOM station code for the station of interest.

start_date_time

A character string representing the start date and time of the query in the format “yyyy-mm-dd-hh-mm” (ISO8601). Defaults to 24 hours before the current local system time, returning the most recent 24 hour observations rounded to the nearest minute. This function does its best to decipher many date and time formats but prefers ISO8601.

minutes

An integer value that provides the number of observations to be returned. Defaults to 1440 minutes for 24 hours of observations.

values

A vector of weather values to query from the API. See Available Values section for valid available codes. Defaults to all available values, all.

api_key

Value

a data.table::data.table() with station_code and the date interval queried together with the requested weather variables.

Available Values

all (which will return all of the following values),
airTemperature,
dateTime,
dewPoint,
rainfall,
relativeHumidity,
soilTemperature,
solarIrradiance,
wetBulb,
wind,
windAvgSpeed,
windMaxSpeed, and
windMinSpeed

Note

Please note this function converts date-time columns from Coordinated Universal Time ‘UTC’ returned by the API to Australian Western Standard Time ‘AWST’.

Author(s)

Adam H. Sparks, adamhsparks@gmail.com

Examples

## Not run: 

# Note that you need to supply your own API key

get_dpird_minute(
  station_code = "SP",
  start_date_time = "2023-02-01 13:00:00",
  minutes = 1440,
  values = c("airTemperature",
             "solarIrradiance",
             "wind"),
  api_key = "your_api_key"
)

## End(Not run)

Get DPIRD Weather Data in Summarised Formats

Description

Fetch nicely formatted individual station weather summaries from the DPIRD Weather 2.0 API.

Usage

get_dpird_summaries(
  station_code,
  start_date,
  end_date = Sys.Date(),
  interval = c("daily", "15min", "30min", "hourly", "monthly", "yearly"),
  values = "all",
  api_key = get_key(service = "DPIRD")
)

Arguments

station_code

A character string or factor from get_stations_metadata() of the BOM station code for the station of interest.

start_date

A character string or Date object representing the beginning of the range to query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date.

end_date

A character string or Date object representing the end of the range query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date. Defaults to the current system date.

interval

A character string that indicates the time interval to monthly or yearly. For intervals shorter than 1 day, the time period covered will be midnight to midnight, with the end_date time interval being before midnight - hour/minute values are for the end of the time period. Data for shorter intervals (⁠15min⁠, ⁠30min⁠) are available from January of the previous year.

values

A character string with the type of summarised weather to return. See Available Values for a full list of valid values. Defaults to all with all available values being returned.

api_key

Value

a data.table::data.table() with station_code and the date interval queried together with the requested weather variables in alphabetical order. The first ten columns will always be:

station_code,
station_name,
longitude,
latitude,
year,
month,
day,
hour,
minute, and if month or finer is present,
date (a combination of year, month, day, hour, minute as appropriate).

Start Dates

The earliest available data start from August of 2000 for Vasse, “VA”.

Column Name Details

Column names are converted from the default returns of the API to be snake_case formatted and where appropriate, the names of the values that are analogous between SILO and DPIRD data are named using the same name for ease of interoperability, e.g., using rbind() to create a data.table that contains data from both APIs. However, use with caution and don't mix datasets of different time-steps, i.e., this function gets many summary values not just “daily” time-step data. The functions that access the SILO API only provide access to daily data, so don't mix (sub)hourly, monthly or yearly data from DPIRD with SILO.

Available Values

all (which will return all of the following values),
airTemperature,
airTemperatureAvg,
airTemperatureMax,
airTemperatureMaxTime,
airTemperatureMin,
airTemperatureMinTime,
apparentAirTemperature,
apparentAirTemperatureAvg,
apparentAirTemperatureMax,
apparentAirTemperatureMaxTime,
apparentAirTemperatureMin,
apparentAirTemperatureMinTime,
barometricPressure,
barometricPressureAvg,
barometricPressureMax,
barometricPressureMaxTime,
barometricPressureMin,
barometricPressureMinTime,
battery,
batteryMinVoltage,
batteryMinVoltageDateTime,
chillHours,
deltaT,
deltaTAvg,
deltaTMax,
deltaTMaxTime,
deltaTMin,
deltaTMinTime,
dewPoint,
dewPointAvg,
dewPointMax,
dewPointMaxTime,
dewPointMin,
dewPointMinTime,
erosionCondition,
erosionConditionMinutes,
erosionConditionStartTime,
errors,
etoShortCrop,
etoTallCrop,
evapotranspiration,
evapotranspirationShortCrop,
evapotranspirationTallCrop,
frostCondition,
frostConditionMinutes,
frostConditionStartTime,
heatCondition,
heatConditionMinutes,
heatConditionStartTime,
observations,
observationsCount,
observationsPercentage,
panEvaporation,
panEvaporation12AM,
rainfall,
relativeHumidity,
relativeHumidityAvg,
relativeHumidityMax,
relativeHumidityMaxTime,
relativeHumidityMin,
relativeHumidityMinTime,
richardsonUnits,
soilTemperature,
soilTemperatureAvg,
soilTemperatureMax,
soilTemperatureMaxTime,
soilTemperatureMin,
soilTemperatureMinTime,
solarExposure,
wetBulb,
wetBulbAvg,
wetBulbMax,
wetBulbMaxTime,
wetBulbMin,
wetBulbMinTime,
wind,
windAvgSpeed, and
windMaxSpeed

Note

Please note this function converts date-time columns from Coordinated Universal Time ‘UTC’ to Australian Western Standard Time ‘AWST’.

Author(s)

Adam H. Sparks, adamhsparks@gmail.com, and Rodrigo Pires, rodrigo.pires@dpird.wa.gov.au

Examples

## Not run: 
# Note that you need to supply your own API key
# Use default for end date (current system date) to get rainfall

wd <- get_dpird_summaries(
   station_code = "CL001",
   start_date = "20171028",
   api_key = "your_api_key",
   interval = "yearly",
   values = "rainfall"
)

# Only for wind and erosion conditions for daily time interval

wd <- get_dpird_summaries(
  station_code = "BI",
  start_date = "20220501",
  end_date = "20220502",
  api_key = "your_api_key",
  interval = "daily",
  values = c(
    "wind",
    "erosionCondition",
    "erosionConditionMinutes",
    "erosionConditionStartTime"
    )
)

## End(Not run)

Get or Set Up API Keys

Description

Checks first to get key from your .Rprofile or .Renviron (or similar) file. If it's not found, then it suggests setting it up. Can be used to check that your key that R is using is the key that you wish to be using or for guidance in setting up the keys.

Usage

get_key(service = c("DPIRD", "SILO"))

Arguments

service

(character) The API host, either “DPIRD” or “SILO”.

Details

The suggestion is to use your .Renviron to set up the API keys. However, if you regularly interact with the APIs outside of R using some other language you may wish to set these up in your .bashrc, .zshrc, or config.fish for cross-language use.

Value

A string value with either a DPIRD Weather 2.0 API or SILO API key value.

Examples

## Not run: 
  get_key(service = "DPIRD")
  get_key(service = "SILO")

## End(Not run)

Get PatchedPoint Weather Data From SILO

Description

Fetch nicely formatted weather data from the SILO API derived from the BOM station observations (PatchedPoint) data.

Usage

get_patched_point(
  station_code,
  start_date,
  end_date = Sys.Date(),
  values = "all",
  api_key = get_key(service = "SILO")
)

Arguments

station_code

A character string of the BOM station code for the station of interest.

start_date

A character string or Date object representing the beginning of the range to query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date.

end_date

A character string or Date object representing the end of the range query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date. Defaults to the current system date.

values

A character string with the type of weather data to return. See Available Values for a full list of valid values. Defaults to all with all available values being returned.

api_key

Value

a data.table::data.table() with the weather data queried with the weather variables in alphabetical order. The first eight columns will always be:

station_code,
station_name,
longitude,
latitude,
elev_m (elevation in metres),
date (ISO8601 format, "YYYYMMDD"),
year,
month,
day,
extracted (the date on which the query was made)

Column Name Details

The SILO documentation provides the following information for the PatchedPoint data.

These data are a continuous daily time series of data at either recording stations or grid points across Australia:

Data at station locations consists of observational records which have been supplemented by interpolated estimates when observed data are missing. Datasets are available at approximately 8,000 Bureau of Meteorology recording stations around Australia.
Data at grid points consists entirely of interpolated estimates. The data are taken from the SILO gridded datasets and are available at any pixel on a 0.05° × 0.05° grid over the land area of Australia (including some islands).

Available Values

all: Which will return all of the following values
rain (mm): Rainfall
max_temp (degrees C): Maximum temperature
min_temp (degrees C): Minimum temperature
vp (hPa): Vapour pressure
vp_deficit (hPa): Vapour pressure deficit
evap_pan (mm): Class A pan evaporation
evap_syn (mm): Synthetic estimate¹
evap_comb (mm): Combination (synthetic estimate pre-1970, class A pan 1970 onwards)
evap_morton_lake (mm): Morton's shallow lake evaporation
radiation (Mj/m²): Solar exposure, consisting of both direct and diffuse components
rh_tmax (%): Relative humidity at the time of maximum temperature
rh_tmin (%): Relative humidity at the time of minimum temperature
et_short_crop (mm): FAO56⁴
short crop
et_tall_crop (mm): ASCE⁵
tall crop⁶
et_morton_actual (mm): Morton's areal actual evapotranspiration
et_morton_potential (mm): Morton's point potential evapotranspiration
et_morton_wet (mm): Morton's wet-environment areal potential evapotranspiration over land
mslp (hPa): Mean sea level pressure

Value information

Solar radiation: total incoming downward shortwave radiation on a horizontal surface, derived from estimates of cloud oktas and sunshine duration³.

Relative humidity: calculated using the vapour pressure measured at 9am, and the saturation vapour pressure computed using either the maximum or minimum temperature⁶.

Evaporation and evapotranspiration: an overview of the variables provided by SILO is available here, https://data.longpaddock.qld.gov.au/static/publications/Evapotranspiration_overview.pdf.

Data codes

The data are supplied with codes indicating how each datum was obtained.

0: Official observation as supplied by the Bureau of Meteorology
15: Deaccumulated rainfall (original observation was recorded over a period exceeding the standard 24 hour observation period).
25: Interpolated from daily observations for that date.
26: Synthetic Class A pan evaporation, calculated from temperatures, radiation and vapour pressure.
35: Interpolated from daily observations using an anomaly interpolation method.
75: Interpolated from the long term averages of daily observations for that day of year.

Author(s)

Rodrigo Pires, rodrigo.pires@dpird.wa.gov.au, and Adam Sparks, adamhsparks@gmail.com

References

Rayner, D. (2005). Australian synthetic daily Class A pan evaporation. Technical Report December 2005, Queensland Department of Natural Resources and Mines, Indooroopilly, Qld., Australia, 40 pp.
Morton, F. I. (1983). Operational estimates of areal evapotranspiration and their significance to the science and practice of hydrology, Journal of Hydrology, Volume 66, 1-76.
Zajaczkowski, J., Wong, K., & Carter, J. (2013). Improved historical solar radiation gridded data for Australia, Environmental Modelling & Software, Volume 49, 64–77. DOI: doi:10.1016/j.envsoft.2013.06.013.
Food and Agriculture Organization of the United Nations, Irrigation and drainage paper 56: Crop evapotranspiration - Guidelines for computing crop water requirements, 1998.
ASCE’s Standardized Reference Evapotranspiration Equation, proceedings of the National Irrigation Symposium, Phoenix, Arizona, 2000.
For further details refer to Jeffrey, S.J., Carter, J.O., Moodie, K.B. and Beswick, A.R. (2001). Using spatial interpolation to construct a comprehensive archive of Australian climate data, Environmental Modelling and Software, Volume 16/4, 309-330. DOI: doi:10.1016/S1364-8152(01)00008-1.

Examples

## Not run: 
# requires an API key as your email address
# Source observation data for station Wongan Hills station, WA (008137)
wd <- get_patched_point(station_code = "008137",
               start_date = "2021-06-01",
               end_date = "2021-07-01",
               values = "all",
               api_key = "your_api_key")

## End(Not run)

Get PatchedPoint Weather Data in the APSIM Format From SILO

Description

Fetch APSIM .met file formatted weather data from the SILO API derived from the BOM station observations (PatchedPoint) data.

Usage

get_patched_point_apsim(
  station_code,
  start_date,
  end_date = Sys.Date(),
  api_key = get_key(service = "SILO")
)

Arguments

station_code

A character string or factor from get_stations_metadata() of the BOM station code for the station of interest.

start_date

A character string or Date object representing the beginning of the range to query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date.

end_date

A character string or Date object representing the end of the range query in the format “yyyy-mm-dd” (ISO8601). Data returned is inclusive of this date. Defaults to the current system date.

api_key

Details

The SILO documentation provides the following information for the PatchedPoint data.

These data are a continuous daily time series of data at either recording stations or grid points across Australia:

Data at station locations consists of observational records which have been supplemented by interpolated estimates when observed data are missing. Datasets are available at approximately 8,000 Bureau of Meteorology recording stations around Australia.
Data at grid points consists entirely of interpolated estimates. The data are taken from the SILO gridded datasets and are available at any pixel on a 0.05° × 0.05° grid over the land area of Australia (including some islands).

Value

An apsimx object of class ‘met’ with attributes.

Included Values

rain (mm): Rainfall
maxt (degrees C): Maximum temperature
mint (degrees C): Minimum temperature
vp (hPa): Vapour pressure
evap_pan (mm): Class A pan evaporation
radiation (Mj/m¹): Solar exposure, consisting of both direct and diffuse components

Value information

Solar radiation: total incoming downward shortwave radiation on a horizontal surface, derived from estimates of cloud oktas and sunshine duration².

Evaporation and evapotranspiration: an overview of the variables provided by SILO is available here, https://data.longpaddock.qld.gov.au/static/publications/Evapotranspiration_overview.pdf.

Data codes

Where the source code is a 6 digit string comprising the source code for the 6 variables. The single digit code for each variable is:

0: an actual observation;
1: an actual observation from a composite station;
2: a value interpolated from daily observations;
3: a value interpolated from daily observations using the anomaly interpolation method for CLIMARC data;
6: a synthetic pan value; or
7: an interpolated long term average.

Saving objects

Author(s)

Rodrigo Pires, rodrigo.pires@dpird.wa.gov.au, and Adam Sparks, adamhsparks@gmail.com

References

Rayner, D. (2005). Australian synthetic daily Class A pan evaporation. Technical Report December 2005, Queensland Department of Natural Resources and Mines, Indooroopilly, Qld., Australia, 40 pp.
Morton, F. I. (1983). Operational estimates of areal evapotranspiration and their significance to the science and practice of hydrology, Journal of Hydrology, Volume 66, 1-76.

Examples

## Not run: 
# requires an API key as your email address
# Source observation data for Wongan Hills station, WA (008137)
wd <- get_patched_point_apsim(
  station_code = "008137",
  start_date = "20220101",
  end_date = "20221231",
  api_key = "your_api_key"
)

## End(Not run)

Get a BOM Daily Précis Forecast

Description

Fetch nicely formatted daily précis forecast from the BOM, which contains seven-day town forecasts for a specified state or territory. Ported from bomrang.

Usage

get_precis_forecast(state = "AUS")

Arguments

state

Australian state or territory as full name or postal code. Fuzzy string matching via base::agrep() is done. Defaults to AUS returning all state bulletins, see Details for more.

Details

Allowed state and territory postal codes, only one state per request or all using 'AUS'.

AUS: Australia, returns forecast for all states, NT and ACT
ACT: Australian Capital Territory (will return NSW)
NSW: New South Wales
NT: Northern Territory
QLD: Queensland
SA: South Australia
TAS: Tasmania
VIC: Victoria
WA: Western Australia

Value

A data.table::data.table() of an Australia BOM précis seven day forecasts for BOM selected towns.

Author(s)

Adam H. Sparks, adamhsparks@gmail.com, Keith Pembleton, keith.pembleton@usq.edu.au, and Paul Melloy, paul@melloy.com.au

References

Forecast data come from Australian Bureau of Meteorology (BOM) Weather Data Services
http://www.bom.gov.au/catalogue/data-feeds.shtml

Location data and other metadata for towns come from the BOM anonymous FTP server with spatial data
ftp://ftp.bom.gov.au/anon/home/adfd/spatial/, specifically the DBF file portion of a shapefile,
ftp://ftp.bom.gov.au/anon/home/adfd/spatial/IDM00013.dbf.

Examples



# get the short forecast for Western Australia
get_precis_forecast(state = "WA")

Get BOM Radar Imagery

Description

Fetch BOM radar imagery from ftp://ftp.bom.gov.au/anon/gen/radar/ and return a magick image object. Files available are the most recent radar snapshot which are updated approximately every 6 to 10 minutes. It is suggested to check file availability first by using get_available_radar().

Usage

get_radar_imagery(product_id, path = NULL, download_only = FALSE)

Arguments

product_id

Character. BOM product ID to download and import. Value is required.

path

Character. A character string with the name where the downloaded file is saved. If not provided, the default value NULL is used which saves the file in an R session temp directory.

download_only

Boolean. Whether the radar image is loaded into the environment as a magick object or just downloaded. Defaults to FALSE

Details

Valid BOM Radar Product IDs for radar imagery can be obtained from get_available_radar().

Value

A magick object of the most recent radar image snapshot published by the BOM. If download_only = TRUE there will be a NULL return value with the download path printed in the console as a message.

Author(s)

Dean Marchiori, deanmarchiori@gmail.com

References

Australian Bureau of Meteorology (BOM) radar images
http://www.bom.gov.au/australia/radar/

Examples



# Fetch most recent radar image for Wollongong 256km radar
imagery <- get_radar_imagery(product_id = "IDR032")
imagery

Get BOM Satellite Imagery

Description

Fetch BOM satellite GeoTIFF imagery from ftp://ftp.bom.gov.au/anon/gen/gms/ and return a terra SpatRaster S4 class (see ⁠[terra::rast()]⁠) or stars S3 stars object of GeoTIFF files. Files are available at ten minutes update frequency with a 24-hour delete time. It is suggested to check file availability first by using get_available_imagery(). Ported from bomrang with modifications.

Usage

get_satellite_imagery(product_id, scans = 1, compat = "terra")

Arguments

product_id

Character. BOM product ID to download and import as a terra SpatRaster S4 class (see ⁠[terra::rast()]⁠) or stars S3 stars class object. A vector of values from get_available_imagery() may be used here. Value is required.

scans

Integer. Number of scans to download, starting with most recent and progressing backwards, e.g., 1 - the most recent single scan available , 6 - the most recent hour available, 12 - the most recent 2 hours available, etc. Negating will return the oldest files first. Defaults to 1. Value is optional.

compat

Character. A string indicating the R package with which the returned imagery should be formatted for use, one of terra or stars. Defaults to terra.

Details

Valid BOM satellite Product IDs for use with product_id include:

IDE00420: AHI cloud cover only 2km FD GEOS GIS
IDE00421: AHI IR (Ch13) greyscale 2km FD GEOS GIS
IDE00422: AHI VIS (Ch3) greyscale 2km FD GEOS GIS
IDE00423: AHI IR (Ch13) Zehr 2km FD GEOS GIS
IDE00425: AHI VIS (true colour) / IR (Ch13 greyscale) composite 1km FD GEOS GIS
IDE00426: AHI VIS (true colour) / IR (Ch13 greyscale) composite 2km FD GEOS GIS
IDE00427: AHI WV (Ch8) 2km FD GEOS GIS
IDE00430: AHI cloud cover only 2km AUS equirect. GIS
IDE00431: AHI IR (Ch13) greyscale 2km AUS equirect. GIS
IDE00432: AHI VIS (Ch3) greyscale 2km AUS equirect. GIS
IDE00433: AHI IR (Ch13) Zehr 2km AUS equirect. GIS
IDE00435: AHI VIS (true colour) / IR (Ch13 greyscale) composite 1km AUS equirect. GIS
IDE00436: AHI VIS (true colour) / IR (Ch13 greyscale) composite 2km AUS equirect. GIS
IDE00437: AHI WV (Ch8) 2km AUS equirect. GIS
IDE00439: AHI VIS (Ch3) greyscale 0.5km AUS equirect. GIS

Value

A terra SpatRaster S4 class (see ⁠[terra::rast()]⁠) or stars S3 stars class object as selected by the user by specifying compat of GeoTIFF images with layers named by BOM product ID, timestamp and band.

Note

The original bomrang version of this function supported local file caching using hoardr. This version does not support this functionality any longer due to issues with CRAN and hoardr.

Author(s)

Adam H. Sparks, adamhsparks@gmail.com

References

Australian Bureau of Meteorology (BOM) high-definition satellite images
http://www.bom.gov.au/australia/satellite/index.shtml.

Examples


# Fetch AHI VIS (true colour) / IR (Ch13 greyscale) composite 1km FD
# GEOS GIS {terra} `SpatRaster`` object for most recent single scan
 available

imagery <- get_satellite_imagery(product_id = "IDE00425", scans = 1)
plot(imagery)

# Get a list of available image files and use that to specify files for
# download, downloading the two most recent files available

avail <- get_available_imagery(product_id = "IDE00425")
imagery <- get_satellite_imagery(product_id = avail, scans = 2)
plot(imagery)

Get Weather Station Metadata for Both DPIRD and SILO Weather Stations

Description

Download the latest station locations and metadata for stations in the SILO and DPIRD networks. For BOM stations that exist in SILO, but lack metadata from BOM, the rows will exist to indicate that the station is in the SILO data set, but there is no corresponding BOM metadata available.

Usage

get_stations_metadata(
  station_code = NULL,
  station_name = NULL,
  which_api = "all",
  api_key = NULL,
  include_closed = FALSE,
  rich = FALSE
)

Arguments

station_code

An optional value that should be provided as a single string value or character vector of station codes for which to return metadata. If this or station_name are not provided, all station metadata is returned by default. If this and station_name are both provided, this takes precedence and values corresponding to this input will be returned.

station_name

An optional value that should be provided as either a single string or character vector of station names for which to return metadata. Fuzzy matching is used, e.g., using c("brisbane", "melbourne") will return rows for “Brisbane”, “Brisbane Aero”, “Mt Brisbane”, “City of Melbourne Bay”, “Selbourne Kirnbrae”, “Maroondah Weir Melbourne Water”, “Melbourne Airport” and “Melbourne Botanical Gardens” station_name values. If this or station_code are not provided, all station metadata is returned by default. Using station_code will always override this argument if both are provided.

which_api

A string value that indicates which API to use. Valid values are all, for both SILO (BOM data) and DPIRD APIs; silo for only stations from the SILO API (BOM data); or dpird for stations from the DPIRD Weather 2.0 API. Defaults to all.

api_key

include_closed

A Boolean string indicating whether to include closed stations' metadata. Use TRUE to include these. Defaults to FALSE.

rich

A Boolean string indicating whether to return rich information about DPIRD's weather station(s), this does not affect the SILO stations' metadata, the variables for these observations will be NA. Defaults to FALSE.

Value

A data.table::data.table() of BOM weather stations' metadata for stations available from SILO and weather stations' metadata for stations available from DPIRD's Weather 2.0 API with the following columns sorted by state and station_name.

station_code:	Unique station code. `factor`
station_name:	Unique station name. `character`
start:	Date observations start. `date`
end:	Date observations end. `date`
latitude:	Latitude in decimal degrees. `numeric`
longitude:	Longitude in decimal degrees. `numeric`
state:	State in which the station is located. `character`
elev_m:	Station elevation in metres. `numeric`
source:	Organisation responsible for the data or station maintenance. `character`
include_closed:	Station include_closed, one of ‘open’ or ‘closed’. `character`
wmo:	World Meteorological Organisation, (WMO), number if applicable. `numeric`
`rich` values
capabilities:	a list of the station's capabilities (data that it records). `character`
probe_height:	temperature probe height in metres. `double`
rain_gauge_height	rain gauge height in metres. `double`
wind_probe_heights:	wind probe heights always 3 metres, although some have 10 metre probes. `integer`

Note

For stations in the SILO API, BOM does not report the exact date on which stations opened or closed, only the year. Therefore the start and end columns will indicate January 1 of the year that a station opened or closed, whereas stations in the DPIRD network have the date to the day. For BOM stations that are closed for the current year, this indicates that the station closed sometime during the current year prior to the request being made. NA in the current year indicates a station is still open.

There are discrepancies between the BOM's official station metadata, e.g. longitude and latitude values and SILO metadata. In these cases, the BOM metadata is used as it is considered to be the authority on the stations' locations.

The station names are returned by both APIs in full caps. For purposes of cleaner graphs and maps where these data may be sued, this function converts them to proper name formats/title case with the first letter of every word capitalised excepting words like “at” or “on” and keeps acronyms like “AWS” or “PIRSA” or state abbreviations in the station names as all caps.

Author(s)

Adam H. Sparks, adamhsparks@gmail.com

References

Station location and other metadata are sourced from the Australian Bureau of Meteorology (BOM) webpage, Bureau of Meteorology Site Numbers:
http://www.bom.gov.au/climate/cdo/about/site-num.shtml and http://www.bom.gov.au/climate/data/lists_by_element/stations.txt and the DPIRD Weather 2.0 API.

Examples

## Not run: 
# fetch metadata for all stations available in {weatherOz}
get_stations_metadata(api_key = "your_api_key")

## End(Not run)

Parse BOM Agriculture Bulletin XML Files

Description

Defunct: This function is defunct as of version 2.0.0 because the underlying BOM agricultural forecast bulletin service is no longer available.

Usage

parse_ag_bulletin(state, filepath)

Arguments

state

Required value of an Australian state or territory as full name or postal code. Fuzzy string matching via base::agrep() is done.

filepath

A string providing the directory location of the précis file(s) to parse. See Details for more.

Details

Parse local BOM agriculture bulletin XML file(s) for a specified state or territory or all Australia. Ported from bomrang.

Allowed state and territory postal codes, only one state per request or all using AUS.

AUS: Australia, returns forecast for all states, NT and ACT
ACT: Australian Capital Territory (will return NSW)
NSW: New South Wales
NT: Northern Territory
QLD: Queensland
SA: South Australia
TAS: Tasmania
VIC: Victoria
WA: Western Australia

The filepath argument will only accept a directory where files are located for parsing. DO NOT supply the full path including the file name. This function will only parse the requested state or all of Australia in the same fashion as get_precis_forecast(), provided that the files are all present in the directory.

Value

A data.table::data.table() of Australia BOM agricultural bulletin information.

Author(s)

Adam H. Sparks, adamhsparks@gmail.com, and Paul Melloy, paul@melloy.com.au

References

and

Australian Bureau of Meteorology (BOM)) Weather Data Services Observation of Rainfall,
http://www.bom.gov.au/climate/how/observations/rain-measure.shtml.

Station location and other metadata are sourced from the Australian Bureau of Meteorology (BOM) webpage, Bureau of Meteorology Site Numbers:
http://www.bom.gov.au/climate/cdo/about/site-num.shtml.

Examples


# parse the ag bulletin for Western Australia

# download to tempfile() using basename() to keep original name
utils::download.file(url = "ftp://ftp.bom.gov.au/anon/gen/fwo/IDQ60604.xml",
              destfile = file.path(tempdir(),
              basename("ftp://ftp.bom.gov.au/anon/gen/fwo/IDQ60604.xml")),
              mode = "wb")

parse_ag_bulletin(state = "QLD", filepath = tempdir())

Parse BOM Coastal Waters Forecast XML Files

Description

Parse local BOM daily coastal waters forecast XML file(s) for a specified state or territory or all of Australia.

Usage

parse_coastal_forecast(state, filepath)

Arguments

state

Required value of an Australian state or territory as full name or postal code. Fuzzy string matching via base::agrep() is done.

filepath

A string providing the directory location of the coastal forecast file(s) to parse. See Details for more.

Details

Allowed state and territory postal codes, only one state per request or all using AUS.

AUS: Australia, returns forecast for all states, NT and ACT
ACT: Australian Capital Territory (will return NSW)
NSW: New South Wales
NT: Northern Territory
QLD: Queensland
SA: South Australia
TAS: Tasmania
VIC: Victoria
WA: Western Australia

The filepath argument will only accept a directory where files are located for parsing. DO NOT supply the full path including the file name. This function will only parse the requested state or all of Australia in the same fashion as get_coastal_forecast(), provided that the files are all present in the directory.

Value

A data.table::data.table() of an Australia BOM Coastal Waters Forecast.

Author(s)

Dean Marchiori, deanmarchiori@gmail.com, and Paul Melloy, paul@melloy.com.au

References

Forecast data come from Australian Bureau of Meteorology (BOM) Weather Data Services
http://www.bom.gov.au/catalogue/data-feeds.shtml.

Examples


# parse the coastal forecast for Queensland

#download to tempfile() using basename() to keep original name
utils::download.file(url = "ftp://ftp.bom.gov.au/anon/gen/fwo/IDQ11290.xml",
              destfile = file.path(tempdir(),
              basename("ftp://ftp.bom.gov.au/anon/gen/fwo/IDQ11290.xml")),
              mode = "wb")

parse_coastal_forecast(state = "QLD", filepath = tempdir())

Parse BOM Précis Forecast XML Files

Description

Parse local BOM daily précis forecast XML file(s) of the seven-day town forecasts for a specified state or territory or all Australia. Ported from bomrang.

Usage

parse_precis_forecast(state, filepath)

Arguments

state

Required value of an Australian state or territory as full name or postal code. Fuzzy string matching via base::agrep() is done.

filepath

A string providing the directory location of the précis file(s) to parse. See Details for more.

Details

Allowed state and territory postal codes, only one state per request or all using 'AUS'.

ACT: Australian Capital Territory (will return NSW)
NSW: New South Wales
NT: Northern Territory
QLD: Queensland
SA: South Australia
TAS: Tasmania
VIC: Victoria
WA: Western Australia
AUS: Australia, returns forecast for all states, NT and ACT

Value

A data.table::data.table() of Australia BOM précis seven-day forecasts for BOM selected towns.

Author(s)

Adam H. Sparks, adamhsparks@gmail.com, and Keith Pembleton, keith.pembleton@usq.edu.au, and Paul Melloy, paul@melloy.com.au

References

Forecast data come from Australian Bureau of Meteorology (BOM) Weather Data Services
http://www.bom.gov.au/catalogue/data-feeds.shtml

Examples



# parse the short forecast for Western Australia

# download to tempfile() using basename() to keep original name
utils::download.file(url = "ftp://ftp.bom.gov.au/anon/gen/fwo/IDQ11295.xml",
              destfile = file.path(tempdir(),
              basename("ftp://ftp.bom.gov.au/anon/gen/fwo/IDQ11295.xml")),
              mode = "wb")

parse_precis_forecast(state = "QLD", filepath = tempdir())

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

apsimx: write_apsim_met
terra: plot

A List of SILO Daily Weather Values

Description

A vector object containing 18 items representing valid values to supply to get_patched_point() and get_data_drill()'s values argument taken from the documentation for the SILO API.

Usage

silo_daily_values

Format

A vector object of 57 items.

Source

https://www.longpaddock.qld.gov.au/silo/about/climate-variables/

Western Australia Southwest Agriculture Region Geospatial Polygon

Description

An sf object of the the WA South West Agricultural Region.

Usage

south_west_agricultural_region

Format

An sf::sf() polygon object

Details

The zone managed for intensive agricultural activities in South-Western Australia. Also known as the South West Agricultural Area or Clearing Line. This zone defines the easternmost extent of land cleared for agricultural purposes.

Base data sets

Western Australian Land Information Authority - Captured from photographic interpretation of best available orthophotography at date of capture, dates range between 2007 and 2010.

Scale of capture

1:20,000

Coordinate Reference System

EPSG:4326 - WGS 84 – WGS84 - World Geodetic System 1984, used in GPS https://epsg.io/4326

Source

Western Australia Department of Primary Industries and Regional Development under a Creative Commons Attribution 4.0 Licence

weatherOz: An API Client for Australian Weather and Climate Data Resources

Description

Author(s)

See Also

A List of DPIRD Extreme Weather Data Values

Description

Usage

Format

Source

See Also

A List of DPIRD Minute Weather Data Values

Description

Usage

Format

Source

See Also

A List of DPIRD Summary Weather Data Values

Description

Usage

Format

Source

See Also

Find the Nearest Town With a BOM Forecast

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Find the Nearest Weather Stations to a Given Geographic Point or Known Station

Description

Usage

Arguments

Value

Note

Author(s)

See Also

Examples

Find Stations Within a Geospatially Defined Geographic Area of Interest

Description

Usage

Arguments

Value

See Also

Examples

Get a BOM Agriculture Bulletin

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

Get a List of Available BOM Satellite Imagery

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Get a List of Available BOM Radar Imagery

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Get a BOM Coastal Waters Forecast

Description

Usage