Returns a single (or multiple) station in get_station_metadata() (#51)

* Clarity in docs * Adds functionality to filter metadata results by station code or name. * Update WORDLIST * Update codemeta.json * Fix cross-ref to data.table * Tidy up references to data.table
ropensci · Dec 6, 2023 · 8166c92 · 8166c92
1 parent 435648d
commit 8166c92
Show file tree

Hide file tree

Showing 44 changed files with 185 additions and 56 deletions.
diff --git a/R/find_forecast_towns.R b/R/find_forecast_towns.R
@@ -16,8 +16,8 @@
 #' # find forecast towns near Esperance, WA
 #' find_forecast_towns(longitude = 121.8913, latitude = -33.8614)
 #'
-#' @return A [data.table::data.table] of all forecast towns (in this package)
-#'   sorted by distance from \var{latitude} and \var{longitude}, ascending.
+#' @return A [data.table] of all forecast towns (in this package) sorted by
+#'   distance from \var{latitude} and \var{longitude}, ascending.
 #' @author Hugh Parsonage, \email{hugh.parsonage@@gmail.com}, and James Goldie,
 #'   \email{me@@jamesgoldie.dev}, and Adam H. Sparks,
 #'   \email{adam.sparks@@dpird.wa.gov.au}

diff --git a/R/find_nearby_stations.R b/R/find_nearby_stations.R
@@ -33,7 +33,7 @@
 #'   stations in the \acronym{DPIRD} network should be included in the results.
 #'   Defaults to `FALSE` with closed stations not included.
 #'
-#' @return A [data.table::data.table] with `station_code`, `station_name`,
+#' @return A [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.

diff --git a/R/get_ag_bulletin.R b/R/get_ag_bulletin.R
@@ -24,8 +24,8 @@
 #'
 #' @return
 #'  A data frame as a `weatherOz_tbl` object (inherits and is fully compatible
-#'    with [data.table::data.table]) of Australia \acronym{BOM} agricultural
-#'    bulletin information.
+#'    with [data.table]) of Australia \acronym{BOM} agricultural bulletin
+#'    information.
 #'
 #' @note Data and Information Use
 #' Please note the copyright notice and disclaimer,

diff --git a/R/get_bom_metadata.R b/R/get_bom_metadata.R
@@ -1,7 +1,10 @@
 #' Fetch and Clean BOM Metadata for SILO Stations
 #'
+#' This function caches the file during a user's session for faster responses.
+#' Starting a new \R session will delete this file.
+#'
 #' @return a \CRANpkg{data.table} of BOM station metadata.
-#' @keywords internal
+#' @keywords Internal
 #' @noRd
 
 .get_bom_metadata <- function() {

diff --git a/R/get_coastal_forecast.R b/R/get_coastal_forecast.R
@@ -23,7 +23,7 @@
 #'  }
 #'
 #' @return
-#' A [data.table::data.table] of an Australia \acronym{BOM} Coastal Waters
+#' A [data.table] of an Australia \acronym{BOM} Coastal Waters
 #'   Forecast.
 #'
 #' @examplesIf interactive()

diff --git a/R/get_data_drill.R b/R/get_data_drill.R
@@ -97,7 +97,7 @@
 #'       observations for that day of year}
 #'   }
 #'
-#' @return a [data.table::data.table] with the weather data queried with the
+#' @return a [data.table] with the weather data queried with the
 #'   weather variables in alphabetical order. The first eight columns will
 #'   always be:
 #'

diff --git a/R/get_dpird_availability.R b/R/get_dpird_availability.R
@@ -41,7 +41,7 @@
 #'   * availabilityYearToDateSince12AM, and
 #'   * availabilityYearToDateTo9AM
 #'
-#' @return a [data.table::data.table]  with `station_code` and the requested
+#' @return a [data.table]  with `station_code` and the requested
 #'   metadata.
 #'
 #' @family DPIRD

diff --git a/R/get_dpird_extremes.R b/R/get_dpird_extremes.R
@@ -79,7 +79,7 @@
 #' * heatConditionYearToDateMinutes, and
 #' * heatConditionYearToDateStartTime
 #'
-#' @return a [data.table::data.table] of one row with `station_code`,
+#' @return a [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.
 #'

diff --git a/R/get_dpird_minute.R b/R/get_dpird_minute.R
@@ -42,7 +42,7 @@
 #'   Universal Time \sQuote{UTC} returned by the \acronym{API} to Australian
 #'   Western Standard Time \sQuote{AWST}.
 #'
-#' @return a [data.table::data.table] with `station_code` and the date interval
+#' @return a [data.table] with `station_code` and the date interval
 #'   queried together with the requested weather variables.
 #'
 #' @examples

diff --git a/R/get_dpird_summaries.R b/R/get_dpird_summaries.R
@@ -128,7 +128,7 @@
 #'   * windAvgSpeed, and
 #'   * windMaxSpeed
 #'
-#' @return a [data.table::data.table] with `station_code` and the date interval
+#' @return a [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:
 #'

diff --git a/R/get_patched_point.R b/R/get_patched_point.R
@@ -105,7 +105,7 @@
 #'       observations for that day of year.}
 #'   }
 #'
-#' @return a [data.table::data.table] with the weather data queried with the
+#' @return a [data.table] with the weather data queried with the
 #'   weather variables in alphabetical order.  The first eight columns will
 #'   always be:
 #'

diff --git a/R/get_precis_forecast.R b/R/get_precis_forecast.R
@@ -24,7 +24,7 @@
 #'  }
 #'
 #' @return
-#' A [data.table::data.table] of an Australia \acronym{BOM} précis seven day
+#' A [data.table] of an Australia \acronym{BOM} précis seven day
 #'   forecasts for \acronym{BOM} selected towns.
 #'
 #' @examplesIf interactive()

diff --git a/R/get_radar_imagery.R b/R/get_radar_imagery.R
@@ -14,7 +14,7 @@
 #' @details Valid \acronym{BOM} \acronym{radar} ID for each location required.
 #'
 #' @return
-#' A [data.table::data.table] of all selected \acronym{radar} locations with
+#' A [data.table] of all selected \acronym{radar} locations with
 #'   location information and \var{product_ids}.
 #'
 #' @references

diff --git a/R/get_station_metadata.R b/R/get_station_metadata.R
@@ -6,7 +6,22 @@
 #'   that exist in \acronym{SILO}, but lack metadata from \acronym{BOM}, the
 #'   rows will exist to indicate that the station is in the \acronym{SILO} data
 #'   set, but there is no corresponding \acronym{BOM} metadata available.
-#'
+#' @param 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.
+#' @param 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, \emph{e.g.}, using
+#'   `c("brisbane", "melbourne")` will return rows for \dQuote{Brisbane},
+#'   \dQuote{Brisbane Aero}, \dQuote{Mt Brisbane},
+#'   \dQuote{City of Melbourne Bay}, \dQuote{Selbourne Kirnbrae},
+#'   \dQuote{Maroondah Weir Melbourne Water}, \dQuote{Melbourne Airport} and
+#'   \dQuote{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.
 #' @param which_api A `string` value that indicates which \acronym{API} to use.
 #'   Valid values are `all`, for both \acronym{SILO} (\acronym{BOM} data) and
 #'   \acronym{DPIRD} \acronym{API}s; `silo` for only stations from the
@@ -49,7 +64,7 @@
 #' get_station_metadata(api_key = "your_api_key")
 #' }
 #'
-#' @return a [data.table::data.table] of \acronym{BOM} weather stations'
+#' @return A [data.table] of \acronym{BOM} weather stations'
 #'   metadata for stations available from \acronym{SILO} and weather stations'
 #'   metadata for stations available from \acronym{DPIRD}'s Weather 2.0
 #'   \acronym{API} with the following columns sorted by `state` and
@@ -93,7 +108,9 @@
 #' @export
 
 get_station_metadata <-
-  function(which_api = "all",
+  function(station_code = NULL,
+           station_name = NULL,
+           which_api = "all",
            api_key,
            include_closed = FALSE,
            rich = FALSE) {
@@ -155,12 +172,30 @@ get_station_metadata <-
       "wmo"
     ))
 
-    # lastly, if user wants all stations return them, else return only open ones
-    if (isTRUE(include_closed)) {
-      return(out[])
-    } else {
-      return(subset(out, status == "open")[])
+    # if user wants all stations return them, else return only open ones
+    if (isFALSE(include_closed)) {
+      out <- out[status == "open", ]
+    }
+
+    # filter for `station_code` and call it good if that's specified, else
+    # search for station names, otherwise just return everything (default)
+    # Here, new vectors are created to allow for subsetting since the data frame
+    # has cols with these respective names already and therefore it will not
+    # subset until you rename the user-provided vector of values.
+    if (!is.null(station_code)) {
+      station_code_user <- station_code
+      return(out[station_code %in% station_code_user, ][])
+    } else if (!is.null(station_name)) {
+      station_name_user <- station_name
+      indices <-
+        unlist(lapply(
+          X = station_name_user,
+          FUN = agrep,
+          x = out$station_name
+        ))
+      return(out[indices, ][])
     }
+    return(out[])
   }
 
 

diff --git a/R/parse_ag_bulletin.R b/R/parse_ag_bulletin.R
@@ -30,7 +30,7 @@
 #'   Australia in the same fashion as [get_precis_forecast()], provided that the
 #'   files are all present in the directory.
 #'
-#' @return A [data.table::data.table] of Australia \acronym{BOM} agricultural
+#' @return A [data.table] of Australia \acronym{BOM} agricultural
 #'   bulletin information.
 #'
 #' @examplesIf interactive()

diff --git a/R/parse_coastal_forecast.R b/R/parse_coastal_forecast.R
@@ -31,7 +31,7 @@
 #'   the files are all present in the directory.
 #'
 #' @return
-#' A [data.table::data.table] of an Australia \acronym{BOM} Coastal Waters
+#' A [data.table] of an Australia \acronym{BOM} Coastal Waters
 #'   Forecast.
 #'
 #' @examplesIf interactive()

diff --git a/R/parse_precis_forecast.R b/R/parse_precis_forecast.R
@@ -32,7 +32,7 @@
 #'   files are all present in the directory.
 #'
 #' @return
-#' A [data.table::data.table] of Australia \acronym{BOM} précis seven-day
+#' A [data.table] of Australia \acronym{BOM} précis seven-day
 #'   forecasts for \acronym{BOM} selected towns.
 #'
 #' @examplesIf interactive()

diff --git a/codemeta.json b/codemeta.json
@@ -14,7 +14,7 @@
     "name": "R",
     "url": "https://r-project.org"
   },
-  "runtimePlatform": "R version 4.3.1 (2023-06-16)",
+  "runtimePlatform": "R version 4.3.2 (2023-10-31)",
   "author": [
     {
       "@type": "Person",
@@ -530,7 +530,7 @@
   "applicationCategory": "Tools",
   "isPartOf": "https://www.agric.wa.gov.au/",
   "keywords": ["dpird", "bom", "meteorological-data", "weather-forecast", "australia", "weather", "weather-data", "meteorology", "western-australia", "australia-bureau-of-meteorology", "western-australia-agriculture", "rstats", "climate", "api-client", "data", "weather-api", "rainfall", "r"],
-  "fileSize": "11300.674KB",
+  "fileSize": "12670.8KB",
   "releaseNotes": "https://github.com/DPIRD-FSI/weatherOz/blob/master/NEWS.md",
   "readme": "https://github.com/DPIRD-FSI/weatherOz/blob/main/README.md",
   "contIntegration": ["https://github.com/DPIRD-FSI/weatherOz/actions", "https://app.codecov.io/gh/DPIRD-FSI/weatherOz?branch=main"],

diff --git a/inst/WORDLIST b/inst/WORDLIST
@@ -6,6 +6,7 @@ ASCE
 ASCE’s
 AUS
 AWST
+Aero
 BOM
 BOM's
 Beswick
@@ -34,8 +35,10 @@ GeoTIFF
 Indooroopilly
 JSON
 Kaushal
+Kirnbrae
 Licence
 Lifecycle
+Maroondah
 Modelling
 Moodie
 NSW
@@ -54,6 +57,7 @@ Rayner
 Renviron
 SHTML
 SILO's
+Selbourne
 Siddique
 Southwood
 SpatRaster

diff --git a/man/find_forecast_towns.Rd b/man/find_forecast_towns.Rd
diff --git a/man/find_nearby_stations.Rd b/man/find_nearby_stations.Rd
diff --git a/man/get_ag_bulletin.Rd b/man/get_ag_bulletin.Rd
diff --git a/man/get_available_radar.Rd b/man/get_available_radar.Rd
diff --git a/man/get_coastal_forecast.Rd b/man/get_coastal_forecast.Rd
diff --git a/man/get_data_drill.Rd b/man/get_data_drill.Rd
diff --git a/man/get_dpird_availability.Rd b/man/get_dpird_availability.Rd
diff --git a/man/get_dpird_extremes.Rd b/man/get_dpird_extremes.Rd
diff --git a/man/get_dpird_minute.Rd b/man/get_dpird_minute.Rd
diff --git a/man/get_dpird_summaries.Rd b/man/get_dpird_summaries.Rd
diff --git a/man/get_patched_point.Rd b/man/get_patched_point.Rd
diff --git a/man/get_precis_forecast.Rd b/man/get_precis_forecast.Rd