Return a data.table of nearest stations with metadata and distance li…

…ke {weatherOz} does (#116)

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: GSODR
 Type: Package
 Title: Global Surface Summary of the Day ('GSOD') Weather Data Client
-Version: 3.1.10
+Version: 4.0.0
 Authors@R: c(
     person("Adam H.", "Sparks", role = c("aut", "cre"),
         email = "[email protected]",
@@ -91,3 +91,5 @@ Roxygen: list(roclets = c("collate", "namespace", "rd",
     "roxyglobals::global_roclet"))
 Config/roxyglobals/filename: globals.R
 Config/roxyglobals/unique: FALSE
+Config/testthat/edition: 3
+Config/testthat/parallel: true

NEWS.md

@@ -1,3 +1,19 @@
+# GSDOR 4.0.0
+
+## Major changes
+
+- **Breaking change** `nearest_stations()` now returns a `data.table` of all station metadata and a value with the distance in kilometres from the user-provided coordinates.
+This function previous returned a single `character` vector.
+To replicate the previous functionality, you can use the following method by calling the `STNID` column name.
+
+```r
+nearest_stations(LAT = 14.16742, LON = 121.255669, distance = 50)$STNID
+```
+
+## Minor changes
+
+- Update internal isd history database.
+
 # GSODR 3.1.10
 
 ## Minor changes

R/nearest_stations.R

@@ -24,12 +24,8 @@
 #' n <- nearest_stations(LAT = -27.5598, LON = 151.9507, distance = 100)
 #' n
 #'
-#' @return By default a class \code{\link[base]{character}}
-#'  \code{\link[base]{vector}} object of station identification numbers.
-#'  in order from nearest to farthest in increasing order.  If
-#'  \code{return_full} is \code{TRUE}, a \code{\link[data.table]{data.table}}
-#'  with full station metadata including the distance from the user specified
-#'  coordinates is returned.
+#' @return A \code{\link[data.table]{data.table}} with full station metadata
+#' including the distance from the user specified coordinates.
 #' @author Adam H. Sparks, \email{adamhsparks@@gmail.com}
 #' @autoglobal
 #' @export nearest_stations
@@ -42,32 +38,37 @@ nearest_stations <- function(LAT, LON, distance) {
   user_LON <- LON
 
   # Distance over a great circle. Reasonable approximation.
-  # From HughParsonage in our bomrang package,
+  # From @HughParsonage in our (now retired) {bomrang} package,
   # https://github.com/ropensci/bomrang/blob/master/R/internal_functions.R
   haversine_distance <- function(lat1, lon1, lat2, lon2) {
     # to radians
-    lat1 <- lat1 * pi / 180
-    lat2 <- lat2 * pi / 180
-    lon1 <- lon1 * pi / 180
-    lon2 <- lon2 * pi / 180
+    lat1 <- lat1 * 0.01745329 # this is `pi / 180` pre calculated for efficiency
+    lat2 <- lat2 * 0.01745329
+    lon1 <- lon1 * 0.01745329
+    lon2 <- lon2 * 0.01745329
 
     delta_lat <- abs(lat1 - lat2)
     delta_lon <- abs(lon1 - lon2)
 
     # radius of earth
     6371 * 2 * asin(sqrt(`+`(
-      (sin(delta_lat / 2))^2,
-      cos(lat1) * cos(lat2) * (sin(delta_lon / 2))^2
+      (sin(delta_lat / 2)) ^ 2,
+      cos(lat1) * cos(lat2) * (sin(delta_lon / 2)) ^ 2
     )))
   }
 
 
-  isd_history[, distance_km := haversine_distance(
+  isd_history[, distance_km := round(haversine_distance(
     lat1 = LAT,
     lon1 = LON,
     lat2 = user_LAT,
     lon2 = user_LON
-  )]
+  ), 1)]
 
-  return(subset(isd_history[order(distance_km)], distance_km < distance)[[1]])
+  subset_stns <-
+    data.table(subset(isd_history[order(distance_km)],
+                      distance_km < distance)[[1]])
+  setnames(subset_stns, "V1", "STNID")
+
+  return(isd_history[subset_stns, on = "STNID"])
 }

codemeta.json

@@ -7,13 +7,13 @@
   "codeRepository": "https://github.com/ropensci/GSODR",
   "issueTracker": "https://github.com/ropensci/GSODR/issues",
   "license": "https://spdx.org/licenses/MIT",
-  "version": "3.1.10",
+  "version": "4.0.0",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",
     "url": "https://r-project.org"
   },
-  "runtimePlatform": "R version 4.3.2 (2023-10-31)",
+  "runtimePlatform": "R version 4.3.3 (2024-02-29)",
   "provider": {
     "@id": "https://cran.r-project.org",
     "@type": "Organization",
@@ -309,7 +309,7 @@
   "applicationCategory": "Tools",
   "isPartOf": "https://ropensci.org",
   "keywords": ["US-NCEI", "meteorological-data", "global-weather", "weather", "weather-data", "meteorology", "station-data", "surface-weather", "data-access", "US-NCDC", "r", "gsod", "ncdc", "weather-stations", "global-data", "ncei", "weather-information", "historical-weather", "historical-data", "daily-data", "daily-weather", "rstats", "r-package"],
-  "fileSize": "4339.89KB",
+  "fileSize": "4343.066KB",
   "citation": [
     {
       "@type": "SoftwareSourceCode",
@@ -333,7 +333,7 @@
       "name": "{GSODR}: Global Summary Daily Weather Data in R",
       "identifier": "10.5281/zenodo.1040727",
       "url": "https://CRAN.R-project.org/package=nasapower",
-      "description": "R package version 3.1.10",
+      "description": "R package version 4.0.0",
       "@id": "https://doi.org/10.5281/zenodo.1040727",
       "sameAs": "https://doi.org/10.5281/zenodo.1040727"
     },
@@ -367,7 +367,7 @@
   "relatedLink": ["https://docs.ropensci.org/GSODR/", "https://CRAN.R-project.org/package=GSODR"],
   "releaseNotes": "https://github.com/ropensci/GSODR/blob/master/NEWS.md",
   "readme": "https://github.com/ropensci/GSODR/blob/main/README.md",
-  "contIntegration": ["https://github.com/ropensci/GSODR/actions", "https://codecov.io/gh/ropensci/GSODR"],
+  "contIntegration": ["https://github.com/ropensci/GSODR/actions", "https://app.codecov.io/gh/ropensci/GSODR"],
   "developmentStatus": "https://www.repostatus.org/#active",
   "review": {
     "@type": "Review",

cran-comments.md

@@ -1,12 +1,12 @@
-# GSODR v3.1.10
+# GSODR v4.0.0
 
 ## Test environments
 
- - local macOS, Platform: aarch64-apple-darwin20 (64-bit), R 4.3.2
+ - local macOS, Platform: aarch64-apple-darwin20 (64-bit), R 4.3.3
  - win-builder, R Under development (unstable)
- - win-builder, Platform: x86_64-w64-mingw32, R 4.3.2
+ - win-builder, Platform: x86_64-w64-mingw32, R 4.3.3
 
-This is a new patch release.
+This is a new major release with breaking changes, however they do not affect the 1 reverse dependency.
 
 ## revdepcheck results