diff --git a/DESCRIPTION b/DESCRIPTION index 7edf34da..10cad4f0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -68,10 +68,11 @@ Suggests: maps, mapproj, rappdirs -RoxygenNote: 6.0.1 +RoxygenNote: 5.0.1 NeedsCompilation: no ByteCompile: TRUE VignetteBuilder: knitr X-schema.org-applicationCategory: Tools -X-schema.org-keywords: bom, meteorological-data, weather-forecast, australia, weather, weather-data, meteorology, australia-bureau-of-meteorology +X-schema.org-keywords: bom, meteorological-data, weather-forecast, australia, + weather, weather-data, meteorology, australia-bureau-of-meteorology X-schema.org-isPartOf: https://ropensci.org diff --git a/NAMESPACE b/NAMESPACE index 9cabbfa7..3ea28d4a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -2,6 +2,7 @@ export(get_ag_bulletin) export(get_available_imagery) +export(get_coastal_forecast) export(get_current_weather) export(get_historical) export(get_precis_forecast) diff --git a/R/get_coastal_forecast.R b/R/get_coastal_forecast.R index bf8a78d7..737ac85a 100644 --- a/R/get_coastal_forecast.R +++ b/R/get_coastal_forecast.R @@ -1,11 +1,11 @@ #' Get BOM Coastal Waters Forecast #' -#' Fetch the BOM daily Coastal Waters Forecast and retun a tidy data frame of +#' Fetch the BOM daily Coastal Waters Forecast and return a tidy data frame of #' the forecast regions for a specified state or region. #' #' @param state Australian state or territory as full name or postal code. #' Fuzzy string matching via \code{\link[base]{agrep}} is done. Defaults to -#' "AUS" returning all state bulletins, see details for further information. +#' "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 \code{AUS}. @@ -34,14 +34,13 @@ #' Services \cr #' \url{http://www.bom.gov.au/catalogue/data-feeds.shtml} #' -#' Location data and other metadata for towns come from +#' Location data and other metadata come from #' the BOM anonymous FTP server with spatial data \cr #' \url{ftp://ftp.bom.gov.au/anon/home/adfd/spatial/}, specifically the DBF #' file portion of a shapefile, \cr -#' \url{ftp://ftp.bom.gov.au/anon/home/adfd/spatial/IDM00013.dbf} +#' \url{ftp://ftp.bom.gov.au/anon/home/adfd/spatial/IDM00003.dbf} #' -#' @author Adam H Sparks, \email{adamhsparks@@gmail.com} and Keith Pembleton, -#' \email{keith.pembleton@@usq.edu.au} +#' @author Dean Marchiori, \email{deanmarchiori@@gmail.com} #' @importFrom magrittr %>% #' @export get_coastal_forecast <- function(state = "AUS") { @@ -81,24 +80,21 @@ get_coastal_forecast <- function(state = "AUS") { the_state == "WA" | the_state == "WESTERN AUSTRALIA" ~ paste0(ftp_base, AUS_XML[7]) ) - out <- .parse_forecast(xmlforecast_url) + out <- .parse_coastal_forecast(xmlforecast_url) } else { file_list <- paste0(ftp_base, AUS_XML) - out <- lapply(X = file_list, FUN = .parse_forecast) + out <- lapply(X = file_list, FUN = .parse_coastal_forecast) out <- as.data.frame(data.table::rbindlist(out, fill = TRUE)) } - return(out) - } - -.parse_forecast <- function(xmlforecast_url) { +.parse_coastal_forecast <- function(xmlforecast_url) { # CRAN note avoidance - AAC_codes <- attrs <- end_time_local <- precipitation_range <- # nocov start + AAC_codes <- marine_AAC_codes <- attrs <- end_time_local <- precipitation_range <- # nocov start start_time_local <- values <- NULL # nocov end - # download the XML forecast -------------------------------------------------- + # download the XML forecast tryCatch({ xmlforecast <- xml2::read_xml(xmlforecast_url) }, @@ -109,39 +105,28 @@ get_coastal_forecast <- function(state = "AUS") { )) areas <- xml2::xml_find_all(xmlforecast, ".//*[@type='coast']") - out <- lapply(X = areas, FUN = .parse_areas) out <- as.data.frame(do.call("rbind", out)) - # This is the actual returned value for the main function. The functions - # below chunk the xml into locations and then days, this assembles into - # the final data frame - out <- tidyr::spread(out, key = attrs, value = values) - # tidy up names - names(out) <- gsub("c\\(", "", names(out)) - names(out) <- gsub("\\)", "", names(out)) - out <- out %>% - janitor::clean_names() %>% + janitor::clean_names(., case = "snake") %>% janitor::remove_empty("cols") - out <- - out %>% - tidyr::separate(end_time_local, - into = c("end_time_local", "UTC_offset"), - sep = "\\+") %>% + out <- out %>% + tidyr::separate( + end_time_local, + into = c("end_time_local", "UTC_offset"), + sep = "\\+") %>% tidyr::separate( start_time_local, into = c("start_time_local", "UTC_offset_drop"), - sep = "\\+" - ) - + sep = "\\+") + # drop the "UTC_offset_drop" column out <- out[!names(out) %in% "UTC_offset_drop"] - # remove the "T" from the date/time columns out[, c("start_time_local", "end_time_local", @@ -160,7 +145,6 @@ get_coastal_forecast <- function(state = "AUS") { "end_time_utc")], 2, function(x) chartr("Z", " ", x)) - # convert factors to character for left merge, otherwise funny stuff happens out[, seq_len(ncol(out))] <- lapply(out[, seq_len(ncol(out))], as.character) @@ -178,6 +162,7 @@ get_coastal_forecast <- function(state = "AUS") { load(system.file("extdata", "marine_AAC_codes.rda", package = "bomrang")) # nocov # return final forecast object ----------------------------------------------- + # merge with aac codes for location information tidy_df <- dplyr::left_join(out, @@ -205,12 +190,15 @@ get_coastal_forecast <- function(state = "AUS") { "start_time_utc", "end_time_utc", "forecast_seas", - "forecast_swell1", "forecast_weather", - "forecast_winds" + "forecast_winds", + "forecast_swell1" ) + + # create factors + tidy_df$index <- as.factor(tidy_df$index) + tidy_df <- tidy_df[c(refcols, setdiff(names(tidy_df), refcols))] - return(tidy_df) } diff --git a/README.md b/README.md index 71a5bd2b..3160be90 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ devtools::install_github("ropensci/bomrang", build_vignettes = TRUE) 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; `get_weather_bulletin()`, which retrieves the BOM 0900 or 1500 bulletins; and `get_historical()`, which retrieves historical daily observations for a given station. A second group of functions retrieve information pertaining to satellite imagery, `get_available_imagery()` and the imagery itself, `get_satellite_imagery()`. Vignettes are provided illustrating examples of all functions and a use case. +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; `get_weather_bulletin()`, which retrieves the BOM 0900 or 1500 bulletins; `get_coastal_forecast()`, which returns coastal waters forecasts and `get_historical()`, which retrieves historical daily observations for a given station. A second group of functions retrieve information pertaining to satellite imagery, `get_available_imagery()` and the imagery itself, `get_satellite_imagery()`. Vignettes are provided illustrating examples of all functions and a use case. Meta ---- diff --git a/bomrang.Rproj b/bomrang.Rproj index 21a4da08..eaa6b818 100644 --- a/bomrang.Rproj +++ b/bomrang.Rproj @@ -15,3 +15,4 @@ LaTeX: pdfLaTeX BuildType: Package PackageUseDevtools: Yes PackageInstallArgs: --no-multiarch --with-keep.source +PackageRoxygenize: rd,collate,namespace diff --git a/data-raw/README.md b/data-raw/README.md index 3761e4ce..9e517c7a 100644 --- a/data-raw/README.md +++ b/data-raw/README.md @@ -6,7 +6,8 @@ Australian Bureau of Meteorology (BOM). See BOM's details. Data sources are acknowledged in the -[create_BOM_forecast_locations.md](create_BOM_forecast_locations.md) and +[create_BOM_forecast_locations.md](create_BOM_forecast_locations.md) and +[create_BOM_marine_locations.md](create_BOM_marine_locations.md) and [create_BOM_station_list.md](create_BOM_station_list.md) files respectively. Also data sources are acknowledged in the references section for each applicable diff --git a/data-raw/create_BOM_marine_locations.Rmd b/data-raw/create_BOM_marine_locations.Rmd index f80dd767..2b04e5ac 100644 --- a/data-raw/create_BOM_marine_locations.Rmd +++ b/data-raw/create_BOM_marine_locations.Rmd @@ -11,7 +11,7 @@ knitr::opts_chunk$set(echo = TRUE) BOM maintains a shapefile of forecast marine zone names and their geographic locations. For ease, we'll just use the .dbf file part of the shapefile to extract AAC -codes that can be used to add lat/lon values to the forecast `data.frame` that +codes that can be used to add locations to the forecast `data.frame` that `get_coastal_forecast()` returns. The file is available from BOM's anonymous FTP server with spatial data , specifically the DBF file portion of a shapefile, diff --git a/data-raw/create_BOM_marine_locations.md b/data-raw/create_BOM_marine_locations.md index 2d48289b..76fc5b5c 100644 --- a/data-raw/create_BOM_marine_locations.md +++ b/data-raw/create_BOM_marine_locations.md @@ -4,7 +4,7 @@ Get BOM Marine Zones Get BOM Forecast Marine Zones ----------------------------- -BOM maintains a shapefile of forecast marine zone names and their geographic locations. For ease, we'll just use the .dbf file part of the shapefile to extract AAC codes that can be used to add lat/lon values to the forecast `data.frame` that `get_coastal_forecast()` returns. The file is available from BOM's anonymous FTP server with spatial data , specifically the DBF file portion of a shapefile, +BOM maintains a shapefile of forecast marine zone names and their geographic locations. For ease, we'll just use the .dbf file part of the shapefile to extract AAC codes that can be used to add locations to the forecast `data.frame` that `get_coastal_forecast()` returns. The file is available from BOM's anonymous FTP server with spatial data , specifically the DBF file portion of a shapefile, ``` r utils::download.file( diff --git a/inst/extdata/AAC_codes.rda b/inst/extdata/AAC_codes.rda index 893c4290..501a914d 100644 Binary files a/inst/extdata/AAC_codes.rda and b/inst/extdata/AAC_codes.rda differ diff --git a/inst/extdata/JSONurl_site_list.rda b/inst/extdata/JSONurl_site_list.rda index 4ab35aa9..104a4fd8 100644 Binary files a/inst/extdata/JSONurl_site_list.rda and b/inst/extdata/JSONurl_site_list.rda differ diff --git a/inst/extdata/stations_site_list.rda b/inst/extdata/stations_site_list.rda index f5232aa0..25d1ae6c 100644 Binary files a/inst/extdata/stations_site_list.rda and b/inst/extdata/stations_site_list.rda differ diff --git a/man/bomrang.Rd b/man/bomrang.Rd index 02e07d60..bd2d5478 100644 --- a/man/bomrang.Rd +++ b/man/bomrang.Rd @@ -8,6 +8,10 @@ \description{ Australian Government Bureau of Meteorology (BOM) Data from R } +\author{ +Adam H Sparks and Jonathan Carroll and Mark Padgham and Hugh +Parsonage and Keith Pembleton +} \seealso{ \strong{Useful links:} \itemize{ @@ -16,7 +20,4 @@ Australian Government Bureau of Meteorology (BOM) Data from R \item{Report bugs at \url{https://github.com/ropensci/bomrang/issues}} } } -\author{ -Adam H Sparks and Jonathan Carroll and Mark Padgham and Hugh -Parsonage and Keith Pembleton -} + diff --git a/man/get_ag_bulletin.Rd b/man/get_ag_bulletin.Rd index f2fd44e1..610e9c1a 100644 --- a/man/get_ag_bulletin.Rd +++ b/man/get_ag_bulletin.Rd @@ -40,6 +40,9 @@ or all using \code{AUS}. ag_bulletin <- get_ag_bulletin(state = "QLD") } +} +\author{ +Adam H Sparks, \email{adamhsparks@gmail.com} } \references{ Agricultural observations are retrieved from the Australian Bureau of @@ -56,6 +59,4 @@ Station location and other metadata are sourced from the Australian Bureau of Meteorology (BOM) webpage, Bureau of Meteorology Site Numbers: \cr \url{http://www.bom.gov.au/climate/cdo/about/site-num.shtml} } -\author{ -Adam H Sparks, \email{adamhsparks@gmail.com} -} + diff --git a/man/get_available_imagery.Rd b/man/get_available_imagery.Rd index a1ee93a6..721102c8 100644 --- a/man/get_available_imagery.Rd +++ b/man/get_available_imagery.Rd @@ -53,11 +53,12 @@ Check availability of AHI VIS (true colour) / IR (Ch13 greyscale) composite imagery <- get_available_imagery(product_id = "IDE00425") } +} +\author{ +Adam H Sparks, \email{adamhsparks@gmail.com} } \references{ Australian Bureau of Meteorology (BOM) High-definition satellite images \url{http://www.bom.gov.au/australia/satellite/index.shtml} } -\author{ -Adam H Sparks, \email{adamhsparks@gmail.com} -} + diff --git a/man/get_coastal_forecast.Rd b/man/get_coastal_forecast.Rd new file mode 100644 index 00000000..3131639b --- /dev/null +++ b/man/get_coastal_forecast.Rd @@ -0,0 +1,56 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/get_coastal_forecast.R +\name{get_coastal_forecast} +\alias{get_coastal_forecast} +\title{Get BOM Coastal Waters Forecast} +\usage{ +get_coastal_forecast(state = "AUS") +} +\arguments{ +\item{state}{Australian state or territory as full name or postal code. +Fuzzy string matching via \code{\link[base]{agrep}} is done. Defaults to +"AUS" returning all state forecasts, see details for further information.} +} +\value{ +Tidy \code{\link[base]{data.frame}} of a Australia BOM Coastal Waters +Forecast. +} +\description{ +Fetch the BOM daily Coastal Waters Forecast and return a tidy data frame of +the forecast regions for a specified state or region. +} +\details{ +Allowed state and territory postal codes, only one state per request +or all using \code{AUS}. + \describe{ + \item{ACT}{Australian Capital Territory (will return NSW)} + \item{NSW}{New South Wales} + \item{NT}{Northern Territory} + \item{QLD}{Queensland} + \item{SA}{South Australia} + \item{TAS}{Tasmania} + \item{VIC}{Victoria} + \item{WA}{Western Australia} + \item{AUS}{Australia, returns forecast for all states, NT and ACT} + } +} +\examples{ +\dontrun{ +coastal_forecast <- get_coastal_forecast(state = "NSW") +} +} +\author{ +Dean Marchiori, \email{deanmarchiori@gmail.com} +} +\references{ +Forecast data come from Australian Bureau of Meteorology (BOM) Weather Data +Services \cr +\url{http://www.bom.gov.au/catalogue/data-feeds.shtml} + +Location data and other metadata come from +the BOM anonymous FTP server with spatial data \cr +\url{ftp://ftp.bom.gov.au/anon/home/adfd/spatial/}, specifically the DBF +file portion of a shapefile, \cr +\url{ftp://ftp.bom.gov.au/anon/home/adfd/spatial/IDM00003.dbf} +} + diff --git a/man/get_current_weather.Rd b/man/get_current_weather.Rd index 94361a0d..19d4773a 100644 --- a/man/get_current_weather.Rd +++ b/man/get_current_weather.Rd @@ -67,6 +67,9 @@ for a complete list of fields and units. get_current_weather(latlon = c(-34, 151)) } } +\author{ +Hugh Parsonage, \email{hugh.parsonage@gmail.com} +} \references{ Weather data observations are retrieved from: Australian Bureau of Meteorology (BOM) Weather Data Services, @@ -77,6 +80,4 @@ Station location and other metadata are sourced from the Australian Bureau of Meteorology (BOM) webpage, Bureau of Meteorology Site Numbers: \cr \url{http://www.bom.gov.au/climate/cdo/about/site-num.shtml} } -\author{ -Hugh Parsonage, \email{hugh.parsonage@gmail.com} -} + diff --git a/man/get_historical.Rd b/man/get_historical.Rd index b77d9084..fc345219 100644 --- a/man/get_historical.Rd +++ b/man/get_historical.Rd @@ -19,39 +19,39 @@ get_historical(stationid = NULL, latlon = NULL, type = c("rain", "min", A complete \code{\link[base]{data.frame}} of historical observations for the chosen station, with some subset of the following columns -\tabular{rl}{ -\strong{Product_code}:\tab BOM internal code.\cr -\strong{Station_number}:\tab BOM station ID.\cr -\strong{Year}:\tab Year of observation (YYYY).\cr -\strong{Month}:\tab Month of observation (1-12).\cr -\strong{Day}:\tab Day of observation (1-31).\cr -\strong{Min_temperature}:\tab Minimum daily recorded temperature (degrees C).\cr -\strong{Max_temperature}:\tab Maximum daily recorded temperature (degrees C).\cr -\strong{Accum_days_min}:\tab Accumulated number of days of minimum temperature.\cr -\strong{Accum_days_max}:\tab Accumulated number of days of maximum temperature.\cr -\strong{Rainfall}:\tab Daily recorded rainfall in mm.\cr -\strong{Period}:\tab Period over which rainfall was measured.\cr -\strong{Solar_exposure}:\tab Daily global solar exposure in MJ/m^2.\cr -\strong{Quality}:\tab Y, N, or missing. Data which have not yet completed the\cr -\tab routine quality control process are marked accordingly. -} + \tabular{rl}{ + **Product_code**:\tab BOM internal code.\cr + **Station_number**:\tab BOM station ID.\cr + **Year**:\tab Year of observation (YYYY).\cr + **Month**:\tab Month of observation (1-12).\cr + **Day**:\tab Day of observation (1-31).\cr + **Min_temperature**:\tab Minimum daily recorded temperature (degrees C).\cr + **Max_temperature**:\tab Maximum daily recorded temperature (degrees C).\cr + **Accum_days_min**:\tab Accumulated number of days of minimum temperature.\cr + **Accum_days_max**:\tab Accumulated number of days of maximum temperature.\cr + **Rainfall**:\tab Daily recorded rainfall in mm.\cr + **Period**:\tab Period over which rainfall was measured.\cr + **Solar_exposure**:\tab Daily global solar exposure in MJ/m^2.\cr + **Quality**:\tab Y, N, or missing. Data which have not yet completed the\cr + \tab routine quality control process are marked accordingly. + } -Temperature data prior to 1910 should be used with extreme caution as many -stations, prior to that date, were exposed in non-standard shelters, some -of which give readings which are several degrees warmer or cooler than -those measured according to post-1910 standards. + Temperature data prior to 1910 should be used with extreme caution as many + stations, prior to that date, were exposed in non-standard shelters, some + of which give readings which are several degrees warmer or cooler than + those measured according to post-1910 standards. -Daily maximum temperatures usually occur in the afternoon and daily minimum -temperatures overnight or near dawn. Occasionally, however, the lowest -temperature in the 24 hours to prior to 9 am can occur around 9 am the -previous day if the night was particularly warm. + Daily maximum temperatures usually occur in the afternoon and daily minimum + temperatures overnight or near dawn. Occasionally, however, the lowest + temperature in the 24 hours to prior to 9 am can occur around 9 am the + previous day if the night was particularly warm. -Either \var{stationid} or \var{latlon} must be provided, but if both are, -then \var{stationid} will be used as it is more reliable. + Either \var{stationid} or \var{latlon} must be provided, but if both are, + then \var{stationid} will be used as it is more reliable. -In some cases data is available back to the 1800s, so tens of thousands of -daily records will be returned. Other stations will be newer and will -return fewer observations. + In some cases data is available back to the 1800s, so tens of thousands of + daily records will be returned. Other stations will be newer and will + return fewer observations. } \description{ Retrieves daily observations for a given station. @@ -66,3 +66,4 @@ get_historical(latlon = c(-35.2809, 149.1300), \author{ Jonathan Carroll, \email{rpkg@jcarroll.com.au} } + diff --git a/man/get_precis_forecast.Rd b/man/get_precis_forecast.Rd index 4476b890..c952272b 100644 --- a/man/get_precis_forecast.Rd +++ b/man/get_precis_forecast.Rd @@ -41,6 +41,10 @@ or all using \code{AUS}. BOM_forecast <- get_precis_forecast(state = "QLD") } } +\author{ +Adam H Sparks, \email{adamhsparks@gmail.com} and Keith Pembleton, +\email{keith.pembleton@usq.edu.au} +} \references{ Forecast data come from Australian Bureau of Meteorology (BOM) Weather Data Services \cr @@ -52,7 +56,4 @@ the BOM anonymous FTP server with spatial data \cr file portion of a shapefile, \cr \url{ftp://ftp.bom.gov.au/anon/home/adfd/spatial/IDM00013.dbf} } -\author{ -Adam H Sparks, \email{adamhsparks@gmail.com} and Keith Pembleton, -\email{keith.pembleton@usq.edu.au} -} + diff --git a/man/get_satellite_imagery.Rd b/man/get_satellite_imagery.Rd index 50bfd7c5..57f87bab 100644 --- a/man/get_satellite_imagery.Rd +++ b/man/get_satellite_imagery.Rd @@ -75,6 +75,9 @@ imagery <- get_satellite_imagery(product_id = avail, scans = 2) } } +\author{ +Adam H Sparks, \email{adamhsparks@gmail.com} +} \references{ Australian Bureau of Meteorology (BOM) high-definition satellite images \cr \url{http://www.bom.gov.au/australia/satellite/index.shtml} @@ -83,6 +86,4 @@ Australian Bureau of Meteorology (BOM) high-definition satellite images \cr \code{\link{get_available_imagery}} \code{\link{manage_cache}} } -\author{ -Adam H Sparks, \email{adamhsparks@gmail.com} -} + diff --git a/man/get_weather_bulletin.Rd b/man/get_weather_bulletin.Rd index 1dc6f84d..5304d968 100644 --- a/man/get_weather_bulletin.Rd +++ b/man/get_weather_bulletin.Rd @@ -48,11 +48,12 @@ sometimes contain typographical errors which may lead to warnings about qld_weather <- get_weather_bulletin (state = "QLD", morning = FALSE) } } +\author{ +Mark Padgham, \email{mark.padgham@email.com} +} \references{ Daily observation data come from Australian Bureau of Meteorology (BOM) website. The 3pm bulletin for Queensland is, for example, \cr \url{http://www.bom.gov.au/qld/observations/3pm_bulletin.shtml} } -\author{ -Mark Padgham, \email{mark.padgham@email.com} -} + diff --git a/man/manage_cache.Rd b/man/manage_cache.Rd index c865f65e..c39e950c 100644 --- a/man/manage_cache.Rd +++ b/man/manage_cache.Rd @@ -31,7 +31,6 @@ all files. For deleting many specific files, use\cr nothing } } - \examples{ \dontrun{ @@ -50,3 +49,4 @@ manage_cache$list() manage_cache$cache_path_set("~/tmp") } } + diff --git a/man/sweep_for_stations.Rd b/man/sweep_for_stations.Rd index 34757329..1b5cdf09 100644 --- a/man/sweep_for_stations.Rd +++ b/man/sweep_for_stations.Rd @@ -20,3 +20,4 @@ Find Nearest BOM Weather Stations \author{ Hugh Parsonage, \email{hugh.parsonage@gmail.com} } + diff --git a/man/update_forecast_towns.Rd b/man/update_forecast_towns.Rd index e4bac36f..d42bd911 100644 --- a/man/update_forecast_towns.Rd +++ b/man/update_forecast_towns.Rd @@ -22,11 +22,12 @@ not available in the database distributed with [bomrang]. update_forecast_towns() } } +\author{ +Adam H Sparks, \email{adamhsparks@gmail.com} +} \references{ Data are sourced from: Australian Bureau of Meteorology (BOM) webpage, "Weather Data Services", \url{http://www.bom.gov.au/catalogue/data-feeds.shtml} } -\author{ -Adam H Sparks, \email{adamhsparks@gmail.com} -} + diff --git a/man/update_station_locations.Rd b/man/update_station_locations.Rd index c3de22b9..3dab16f1 100644 --- a/man/update_station_locations.Rd +++ b/man/update_station_locations.Rd @@ -28,11 +28,12 @@ location. update_station_locations() } } +\author{ +Adam H Sparks, \email{adamhsparks@gmail.com} +} \references{ Station location and other metadata are sourced from the Australian Bureau of Meteorology (BOM) webpage, Bureau of Meteorology Site Numbers:\cr \url{http://www.bom.gov.au/climate/cdo/about/site-num.shtml} } -\author{ -Adam H Sparks, \email{adamhsparks@gmail.com} -} + diff --git a/tests/testthat/test-get_coastal_forecast.R b/tests/testthat/test-get_coastal_forecast.R new file mode 100644 index 00000000..3a723cc1 --- /dev/null +++ b/tests/testthat/test-get_coastal_forecast.R @@ -0,0 +1,84 @@ +context("get_coastal_forecast") + +# Test that get_coastal_forecast returns a data frame with 19 colums ------------------- +test_that("get_coastal_forecast returns at most 19 columns", { + skip_on_cran() + bom_forecast <- get_coastal_forecast(state = "NSW") + expect_lte(ncol(bom_forecast), 19) + expect_equal(bom_forecast[["state_code"]][1], "NSW") + + expect_is(bom_forecast$index, "factor") + expect_is(bom_forecast$product_id, "character") + expect_is(bom_forecast$type, "character") + expect_is(bom_forecast$state_code, "character") + expect_is(bom_forecast$dist_name, "character") + expect_is(bom_forecast$pt_1_name, "character") + expect_is(bom_forecast$pt_2_name, "character") + expect_is(bom_forecast$aac, "character") + expect_is(bom_forecast$start_time_local, "POSIXct") + expect_is(bom_forecast$end_time_local, "POSIXct") + expect_is(bom_forecast$utc_offset, "character") + expect_is(bom_forecast$start_time_utc, "POSIXct") + expect_is(bom_forecast$end_time_utc, "POSIXct") + expect_is(bom_forecast$forecast_seas, "character") + expect_is(bom_forecast$forecast_weather, "character") + expect_is(bom_forecast$forecast_winds, "character") + expect_is(bom_forecast$forecast_swell1, "character") +}) + +# Test that get_coastal_forecast returns the requested state forecast ------------------ +test_that("get_coastal_forecast returns the forecast for ACT/NSW", { + skip_on_cran() + bom_forecast <- as.data.frame(get_coastal_forecast(state = "ACT")) + expect_equal(bom_forecast[["state_code"]][1], "NSW") +}) + +test_that("get_coastal_forecast returns the forecast for ACT/NSW", { + skip_on_cran() + bom_forecast <- as.data.frame(get_coastal_forecast(state = "NSW")) + expect_equal(bom_forecast[["state_code"]][1], "NSW") +}) + +test_that("get_coastal_forecast returns the forecast for NT", { + skip_on_cran() + bom_forecast <- as.data.frame(get_coastal_forecast(state = "NT")) + expect_equal(bom_forecast[["state_code"]][1], "NT") +}) + +test_that("get_coastal_forecast returns the forecast for SA", { + skip_on_cran() + bom_forecast <- as.data.frame(get_coastal_forecast(state = "SA")) + expect_equal(bom_forecast[["state_code"]][1], "SA") +}) + +test_that("get_coastal_forecast returns the forecast for TAS", { + skip_on_cran() + bom_forecast <- as.data.frame(get_coastal_forecast(state = "TAS")) + expect_equal(bom_forecast[["state_code"]][1], "TAS") +}) + +test_that("get_coastal_forecast returns the forecast for VIC", { + skip_on_cran() + bom_forecast <- as.data.frame(get_coastal_forecast(state = "VIC")) + expect_equal(bom_forecast[["state_code"]][1], "VIC") +}) + +test_that("get_coastal_forecast returns the forecast for WA", { + skip_on_cran() + bom_forecast <- as.data.frame(get_coastal_forecast(state = "WA")) + expect_equal(bom_forecast[["state_code"]][1], "WA") +}) + +test_that("get_coastal_forecast returns the forecast for AUS", { + skip_on_cran() + bom_forecast <- as.data.frame(get_coastal_forecast(state = "AUS")) + expect_equal(unique(bom_forecast[["state_code"]]), + c("NSW", "NT", "QLD", "SA", "TAS", "VIC", "WA")) +}) + +# Test that .validate_state stops if the state recognised ---------------------- +test_that("get_coastal_forecast() stops if the state is recognised", { + skip_on_cran() + state <- "Kansas" + expect_error(get_coastal_forecast(state)) +}) diff --git a/vignettes/bomrang.Rmd b/vignettes/bomrang.Rmd index 82e6e91c..5769ce1b 100644 --- a/vignettes/bomrang.Rmd +++ b/vignettes/bomrang.Rmd @@ -32,7 +32,7 @@ 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; `get_weather_bulletin()` which fetches the 0900 and 1500 weather -bulletins; and `get_historical()` which fetches historical daily temperature min/max, +bulletins; `get_coastal_forecast()` which fetches coastal waters forecasts for each state and `get_historical()` which fetches historical daily temperature min/max, rainfall, or solar exposure data. A second family of functions retrieve information pertaining to satellite imagery, `get_available_imagery()` and the imagery itself, @@ -173,12 +173,12 @@ codes. - **WA** - Western Australia -#### Results +### Results The function `get_weather_bulletin()` will return a tidy data frame of BOM data for the requested state(s) or territory. -#### Example +### Example Following is an example fetching the 9AM bulletin for Queensland. @@ -192,6 +192,48 @@ Following is an example fetching the 3PM bulletin for Queensland. qld_weather <- get_weather_bulletin(state = "QLD") ``` + +## Using `get_coastal_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_coastal_forecast()`, will return a data frame of the coastal waters +forecast for marine zones in each state. See Appendix 6 for a full +description of the fields and values. + +### Example + +Following is an example fetching the forecast for Queensland. + +```{r coastal_forecast, eval=FALSE} +QLD_coastal_forecast <- get_coastal_forecast(state = "QLD") +``` + + ## Using `get_historical` `get_historical()` takes either of two arguments: `stationid` and `latlon`, as @@ -1033,3 +1075,31 @@ if (requireNamespace("ggplot2", quietly = TRUE) && fill = NA)) } ``` + + +## Appendix 6 - Output from `get_coastal_forecast` + +The output of `get_coastal_forecast` will return a data frame with coastal waters forecast values of each area within the given state with the following fields: + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescription
indexForecast index number. 0 = current day
product_idBOM Product ID from which the data are derived
typeForecast Region type e.g. Coastal
state_codeState name (postal code abbreviation)
dist_nameName of forecast district
pt_1_nameStart of forecast district
pt_2_nameEnd of forecast district
aacAMOC Area Code, _e.g._, WA_MW008, a unique identifier for each location
start_time_localStart of forecast date and time in local TZ
end_time_localEnd of forecast date and time in local TZ
UTC_offsetHours offset from difference in hours and minutes from Coordinated Universal Time (UTC) for `start_time_local` and `end_time_local`
start_time_utcStart of forecast date and time in UTC
end_time_utcEnd of forecast date and time in UTC
forecast_seasForecast sea conditions
forecast_weatherForecast weather summary
forecast_windsForecast winds summary
forecast_swell1Forecast primary swell summary
forecast_swell2Forecast seondary swell summary (not always provided)
marine_forecastAdditional marine forecast warning information (not always provided)