Introduction

bomrang provides functions for interacting with Australian Bureau of Meteorology (BoM) Weather Data Services forecasts. BoM serves several types of data data as XML, JSON and SHTML files. This package fetches these files, parses them and return a tidy data frame. Satellite imagery files are also made available to the public via anonymous ftp. bomrang provides functionality to query, fetch and create raster::stack() objects of the GeoTIFF imagery.

Using bomrang

Several functions are provided by bomrang to retrieve Australian Bureau of Meteorology (BoM) data. A family of functions retrieve weather data and return tidy data frames; get_precis_forecast(), which retrieves the précis (short) forecast; get_current_weather(), which fetches the current weather from a given station; get_ag_bulletin(), which retrieves the agriculture bulletin; and get_weather_bulletin() which fetches the 0900 and 1500 weather bulletins. A second family of functions retrieve information pertaining to satellite imagery, get_available_imagery() and the imagery itself, get_satellite_imagery(). The last group functions provides internal functionality for bomrang itself; update_forecast_towns(), which updates an internal database of forecast locations distributed with the package, sweep_for_stations() which returns the nearest weather stations to a point in Australia and, manage_cache() that provides facilities for managing cached satellite imagery.

Using get_current_weather

get_current_weather() takes one of two arguments: station_name and latlon, returning the current weather observations (and the observations of the last 72 hours) for the given location.

If station_name is used, the weather observations for the last 72 hours are returned for that station. If the string provided is ambiguous, the function returns an observation for one of the possible stations and emits a warning to offer unambiguous station names.

If latlon is used, the observations returned are from the station nearest to that latitude-longitude coordinate. latlon values are entered as decimal degrees, e.g. -34, 151 for Sydney. The function also emits a message, to tell the user which station was used.

Results

The table returned will have different fields depending on the station that is selected.

Using get_precis_forecast

This function only takes one argument, state. The state parameter allows the user to select the forecast for just one state or a national forecast. States or territories are specified using the official postal codes or full name with fuzzy matching performed via agrep()

ACT - Australian Capital Territory

NSW - New South Wales

NT - Northern Territory

QLD - Queensland

SA - South Australia

TAS - Tasmania

VIC - Victoria

WA - Western Australia

AUS - Australia, returns national forecast including all states, NT and ACT.

Results

The function, get_precis_forecast(), will return a data frame of the weather forecast for the daily forecast for selected towns. See Appendix 1 for a full description of the fields and values.

Using get_ag_bulletin

get_ag_bulletin() only takes one argument, state. The state parameter allows the user to select the bulletin for just one state or a national forecast. States or territories are specified using the official postal codes or full name with fuzzy matching performed via agrep().

NSW - New South Wales

NT - Northern Territory

QLD - Queensland

SA - South Australia

TAS - Tasmania

VIC - Victoria

WA - Western Australia

AUS - Australia, returns bulletin for all states and NT.

Results

The function, get_ag_bulletin(), will return a data frame of the agriculture bulletin for selected stations. See Appendix 3 for a full list and description of the fields and values.

Using get_weather_bulletin

This function takes two arguments, state for the desired state; and morning if TRUE, return the 9am bulletin for the nominated state; otherwise return the 3pm bulletin. States or territories are specified using the official postal codes.

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

Results

The function get_weather_bulletin() will return a tidy data frame of BoM data for the requested state(s) or territory.

Using the update functions

bomrang uses internal databases of station location data from BoM to provide location and other metadata, e.g. elevation, station names, WMO codes, etc. to make the process of querying for weather data faster. These databases are created and packaged with bomrang for distribution and are updated with new releases. Users have the option of updating these databases after installing bomrang. While this option gives the users the ability to keep the databases up-to-date and gives bomrang’s authors flexibility in maintaining it, this also means that reproducibility may be affected since the same version of bomrang may have different databases on different machines. If reproducibility is necessary, care should be taken to ensure that the version of the databases is the same across different machines.

The databases consist of three files, used by bomrang, AAC_codes.rda, JSONurl_latlon_by_station_name.rda and stations_site_list.rda. These files can be located on your local system by using the following command,

unless you have specified another location for library installations and installed bomrang there, in which case it would still be in bomrang/extdata.

Using update_forecast_towns

update_forecast_towns() downloads the latest précis forecast locations from the BoM server and updates bomrang’s internal database of towns used for forecast locations. This database is distributed with the package to make the process faster when fetching the forecast.

Example

Following is an example updating the précis forecast locations internal database.

Using update_station_locations

update_station_locations() downloads the latest station locations and metadata and updates bomrang’s internal databases that support the use of get_current_weather() and get_ag_bulletin(). There is no need to use this unless you know that a station exists in BoM’s database that is not available in the databases distributed with bomrang

Example

Following is an example updating the précis forecast locations internal database.

Using get_available_imagery

get_available_imagery() only takes one argument, product_id, a BoM identifier for the imagery that you wish to check for available imagery. Using this function will fetch a listing of BoM GeoTIFF satellite imagery from ftp://ftp.bom.gov.au/anon/gen/gms/ to display which files are currently available for download. These files are available at ten minute update frequency with a 24 hour delete time. This function can be used see the most recent files available and then specify in the get_satellite_imagery() function. If no valid Product ID is supplied, defaults to all GeoTIFF images currently available.

Using get_satellite_imagery

get_satellite_imagery() fetches BoM satellite GeoTIFF imagery, returning a raster stack object and takes three arguments. Files are available at ten minute update frequency with a 24 hour delete time. It is suggested to check file availability first by using get_available_imagery(). The arguments are:

product_id, a character value of the BoM product ID to download. Alternatively, a vector of values from get_available_imagery() may be used here. This argument is mandatory.

scans a numeric value for the number of scans to download, starting with the 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. This argument is optional.

cache a logical value that indicates whether or not to store image files locally for later use? If FALSE, the downloaded files are removed when R session is closed. To take advantage of cached files in future sessions, set TRUE. Defaults to FALSE. This argument is optional. Cached files may be managed with the manage_cache() function.

Using caching for satellite imagery

If you elect to use cache = TRUE when downloading imagery, note that the GTiff files can be quite large and will fill disk space. By using the default cache = FALSE the files will be deleted when the current R session is closed.

Should you chose to use caching, bomrang provided functions to interact with the cached files:

List files in the cache, manage_cache$list()

List info for single files,

manage_cache$list()[1])

manage_cache$list()[2])

List info for all files, manage_cache$details()

Delete files by name in cache, manage_cache$delete()

Delete all files in cache, manage_cache$delete_all()

To access the files directly, outside of R, the following command will give you the location of the directory:

Appendix 1 - Output from get_current_weather

The function get_current_weather() will return a data frame that will contain some or all of the following fields.

Fields and descriptions

Field Name

Description

wmo_id

wmo station index number, uniquely identifies station

Name[31]

Observing station name

Abbr[6]

An abbreviated name (normally 4 characters) used for the station

Date

Date, Year (4 digits), month (2 digits), day (2 digits)

Time

Time, Hours (2 digits), minutes (2 digits), UTC

Lat

Latitude, decimal degrees, S -ve, N +ve

Lon

Longitude, decimal degrees, E +ve, W -ve

Stn_typ

Station type

Stn_ht_m

Station height (in metres)

Total_cld

Total cloud cover in oktas, 9=Sky Obscured by smoke, fog, …

Wdir

Wind direction, degrees true

Wspd_mps

Wind speed, metres per second

Vis_m

Visibility, metres

Wx[9]

Present weather, abbreviated

Pw1

Past weather (last 3-6 hours), see below

Pw2

Past weather (Used so more than one variation can be reported)

Msl_P

Mean Sea Level Pressure, hPa

Stn_P

Station level pressure, hPa

P_tend_typ

Type of the pressure tendency, numerical code, see below

P_tend_val

Pressure tendency (change) in last 3 hours, hPa

Cor_P_tend

Pressure tendency in last 3 hours corrected for diurnal variation

T_DB

Temperature (dry bulb), degrees C

DP

Dew point, degrees C

Low_cld_amt

Amount of low cloud, oktas, 9=Sky obscured by fog, smoke, …

Low_cld_typ[4]

Type of low cloud, abbreviation

Cld_base_m

Base of lowest cloud, m

Cld_dir[4]

Direction of motion of low cloud, compass point

Mid_cld_typ[4]

Type of middle level cloud, abbreviation

Hi_cld_typ[4]

Type of high cloud, abbreviation

Rf_int_h6

Interval for which rain is reported in next field, hours

Rainfall6

Rainfall, mm, usually at 9 or 3 AM/PM

Rf_int_h4

Interval for which rain is reported in next field, hours

Rainfall4

Rainfall, mm, usually since last observation

Sea_state[5]

Sea state, abbreviation

Swl_state[9]

Swell state, abbreviation

Swl_dir[4]

Swell direction, abbreviation

Max_T

Maximum temperature, 24h to 9AM or 6h to 3PM local time, degree C

Min_T

Minimum temperature, 24h to 9AM local time, degree C

Min_grnd_T

Minimum ground temperature, 24 h to (AM local time, degree C

Snow_depth_m

Depth of snow on ground, metres

Low_cld_code

Code for low level cloud type, see below

Mid_cld_code

Code for middle level cloud type, see below

Hi_cld_code

Code for high level cloud type, see below

Max_T(Int)

Maximum temperature for international exchange

Min_T(Int)

Minimum temperature for international exchange

Plain_lang[51]

Plain language comments

Codes:

P_tend_typ:

0 Increasing, then decreasing, current pressure same or higher

1 Increasing, then steady or increasing more slowly

2 Increasing

3 Decreasing or steady, then increasing, or

Increasing, then increasing more rapidly, current pressure higher

4 Steady

5 Decreasing, then increasing, current pressure lower

6 Decreasing, then steady or decreasing more slowly

7 Decreasing
-8 Steady or increasing, then then decreasing, current pressure lower, or

Decreasing, then decreasing more rapidly

Wx[9] - Present weather

This consists of a two or 3 digit code figure plus (when relevant) a short, text abbreviation of the weather The abbreviations used (frequently together, e.g., XXRA for heavy rain, FZDZ for freezing drizzle) include

BL Blowing (usually of sand or snow)

DR Drifting (usually of sand or snow)

DZ Drizzle

FC Funnel cloud (tornado, water spout)

FG Fog

FU Smoke (from the French for smoke)

FZ Freezing (usually of rain or fog)

GR Hail (from the French for hail)

HZ Haze

MI Shallow (can be applied to Fog etc)

RE Ice pellets

PO Dust devils

RA Rain

RE Recent (in the last hour, but not at the observation time)

SA Sand

SG Snow grains

SH Showers

SN Snow

SQ Squall

TS Thunderstorm

XX Heavy or intense (usually of rain or snow)

Also, some other abbreviations used include

lightn Lightning

virga Virga

RIA<5k Precipitation in the area, less then 5km distant

Code figures

(This is a subset of a larger table, not all values of which are used) wmo international BUFR code table 0 20 003, CREX code table B 20 003

Pw1 and Pw2 - Past weather

wmo international BUFR code table 0 20 004, CREX code table B 20 004
If only one type of weather has occurred in the last 3-6 hours,

only Pw1 and Pw2 will be the same. If there has been more than one, Pw1 and Pw2 should be different, with Pw1 reflecting the “more important” past weather. Code figures 0-9 normally apply to manned stations, 10-19 to automated weather stations.

Low_cld_code:

(This is a subset of a larger table, not all values of which are used)
wmo international BUFR code table 0 20 012, CREX code table B 20 012
30 No low level cloud
31 Cumulus humilis, or Cumulus fractus (not of bad weather), or both
32 Cumulus mediocris or congestus, with or without Cumulus humilis
or fractus or Stratocumulus, all bases at the same level
33 Cumulonimbus calvus, with or without Cumulus, Stratocumulus
or Stratus
34 Stratocumulus cumulogenitus
35 Stratocumulus other than stratocumulus cumulogenitus
36 Stratus nebulosis or Stratus fractus (not of bad weather), or both
37 Stratus fractus or Cumulus fractus of bad weather or both (pannus)
38 Cumulus and Stratocumulus other than stratocumulus cumulogenitus,
with bases at different levels
39 Cumulonimbus capillatus with or without Cumulonimbus calvus
Cumulus, Stratocumulus, Stratus or pannus

Mid_cld_code:

(This is a subset of a larger table, not all values of which are used)
wmo international BUFR code table 0 20 012, CREX code table B 20 012
20 No middle level cloud
21 Altostratus translucidus
22 Altostratus opacus or Nimbostratus
23 Altocumulus translucidus at a single level
24 Patches (often lenticular) of Altocumulus translucidus, continually
changing and at one or more levels
25 Altocumulus translucidus in bands, or one or more layers of
Altocumulus translucidus or opacus, progressively invading the
sky
26 Altocumulus cumulogenitus or cumulonimbogenitus
27 Altocumulus translucidus or opacus in two or more layers, or
Altocumulus opacus in a single layer, not progressively invading
the sky, or Altocumulus with Altostratus or Nimbostratus
28 Altocumulus castellanus or floccus
29 Altocumulus of a chaotic sky, usually at several levels

Hi_cld_code:

(This is a subset of a larger table, not all values of which are used)
wmo international BUFR code table 0 20 012, CREX code table B 20 012
10 No high level cloud
11 Cirrus fibratus, sometimes unicus, not progressively invading
the sky
12 Cirrus spissatus in patches or entangled sheaves, which usually
do not increase
13 Cirrus spissatus cumulonimbogenitus
14 Cirrus unicus or fibratus or both, progressively invading the sky
15 Cirrus (often in bands) and Cirrostratus or Cirrostratus alone,
progressively invading the sky, but continuous cloud less than
45 degrees above the horizon.
16 Cirrus (often in bands) and Cirrostratus or Cirrostratus alone,
progressively invading the sky, but continuous cloud more than
45 degrees above the horizon without covering the entire sky
17 Cirrostratus covering the entire sky
18 Cirrostratus not covering the entire sky and not progressively
invading it
19 Cirrocumulus alone or Cirrocumulus predominant

Appendix 2 - Output from get_précis_forecast

The function, get_precis_forecast(), will return a tidy data frame of the agriculture bulletin with the following fields:

Field Name

Description

index

Forecast index number, 0 = current day … 7 day

product_id

BoM Product ID from which the data are derived

state

State name (postal code abbreviation)

town

Town name for forecast location

aac

AMOC Area Code, e.g., WA_MW008, a unique identifier for each location

lat

Latitude of named location (decimal degrees)

lon

Longitude of named location (decimal degrees)

elev

Elevation of named location (metres)

start_time_local

Start of forecast date and time in local TZ

end_time_local

End of forecast date and time in local TZ

UTC_offset

Hours offset from difference in hours and minutes from Coordinated Universal Time (UTC) for start_time_local and end_time_local

start_time_utc

Start of forecast date and time in UTC

end_time_utc

End of forecast date and time in UTC

maximum_temperature

Maximum forecast temperature (degrees Celsius)

minimum_temperature

Minimum forecast temperature (degrees Celsius)

lower_precipitation_limit

Lower forecast precipitation limit (millimetres)

upper_precipitation_limit

Upper forecast precipitation limit (millimetres)

precis

Précis forecast (a short summary, less than 30 characters)

probability_of_precipitation

Probability of precipitation (percent)

Appendix 3 - Output from get_ag_bulletin

The function, get_ag_bulletin(), will return a tidy data frame of the agriculture bulletin with the following fields:

Field Name

Description

product_id

BoM Product ID from which the data are derived

state

State name (postal code abbreviation)

dist

BoM rainfall district

wmo

World Meteorological Organization number (unique ID used worldwide)

site

Unique BoM identifier for each station

station

Station name

full_name

Full station name (some stations have been retired so “name” will be same, this is the full designation

obs-time-local

Observation time

obs-time-utc

Observation time (time in UTC)

time-zone

Time zone for observation

lat

Latitude (decimal degrees)

lon

Longitude (decimal degrees)

elev_m

Station elevation (metres)

bar_ht

Bar height (metres)

station

BoM station name

start

Year data collection starts

end

Year data collection ends (will always be current)

r

Rain to 9am (millimetres). Trace will be reported as 0.01

tn

Minimum temperature (degrees Celsius)

tx

Maximum temperature (degrees Celsius)

twd

Wet bulb depression (degrees Celsius)

ev

Evaporation (millimetres)

tg

Terrestrial minimum temperature (degrees Celsius)

sn

Sunshine (hours)

t5

5cm soil temperature (degrees Celsius)

t10

10cm soil temperature (degrees Celsius)

t20

20cm soil temperature (degrees Celsius)

t50

50cm soil temperature (degrees Celsius)

t1m

1m soil temperature (degrees Celsius)

wr

Wind run (kilometres)

Appendix 4 - Output from get_weather_bulletin

The function get_weather_bulletin() returns a tidy data frame of weather observations for 0900 or 1500 for a nominated state. Observations differ between states, but contain some or all of the following fields. All units are metric (temperatures in Celsius; wind speeds in kilometres per hour; rainfall amounts in millimetres; pressure in hectoPascals). “AWS” in a station name denotes observations from an Automatic Weather Station.

Field Name

Description

stations

Name of observing station

cld8ths

Octas (eights) of cloud (0-8); NA indicates sky obscured

wind_dir

Direction from which wind blows (16 compass directions, measured at height of 10m)

Names of rainfall and temperature variables for some states include prefixes or suffixes defining the time period over which observations apply (for example, “temp_c_6hmax” for maximum temperature between 0980 and 1500, or “temp_c_9ammin” for minimum temperature observed at 9am yet included in 1500 bulletin).