Merge pull request nationalparkservice#64 from RobLBaker/master

Version 1.0.0

Author: RobLBaker

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: NPSutils
 Type: Package
 Title: Collection of Functions to read and manipulate information from the NPS DataStore
-Version: 0.3.2
+Version: 1.0.0
 Authors@R: c(
     person(given = "Robert", family = "Baker", email = "robert_baker@nps.gov",
            role = c("aut", "cre"),

NAMESPACE

@@ -18,7 +18,6 @@ export(get_unit_code_info)
 export(get_unit_info)
 export(load_core_metadata)
 export(load_data_package)
-export(load_data_package_deprecated)
 export(load_data_packages)
 export(load_pkg_metadata)
 export(map_wkt)

NEWS.md

@@ -1,6 +1,9 @@
-# NPSutils 0.3.3 (under development)
+# NPSutils 1.0.0 
+## 2025-12-19
+  * remove `get_data_packages_deprecated()` is a breaking change resulting in release of v.1.0.0.  
+  * update documentation for `get_unit_code()`, `get_park_code()`, and `get_unit_code_info()`
 
-##2024-12-19
+## 2024-12-19
   * remove `validate_data_package()` as this function was listed as "still under construction" is mostly obsolete given other functions and functions in the DPchecker package.
   * remove `load_domains()` as this function was not working properly and was conceived of before the data package specifications were properly set.
 ## 2024-12-19

NPSutils.Rproj

@@ -1,4 +1,5 @@
 Version: 1.0
+ProjectId: 68a3c096-553f-4a8e-8ad4-78954075e8ec
 
 RestoreWorkspace: Default
 SaveWorkspace: Default

R/getParkUnitInfo.R

@@ -1,7 +1,7 @@
 
 #' Dynamically access NPS park unit code data
 #'
-#' @description \code{get_unit_code} accesses info from irmaservices.nps.gov. Search for park or park unit with any string and return all applicable UnitCodes. Handy for use with get.dataPackage if you don't know a Park's UnitCode. allows the user to access information based on park codes
+#' @description Accesses info from irmaservices.nps.gov. Search for park or park unit with any string and return all applicable UnitCodes.
 #'
 #' @details  Contains multiple somewhat redundant functions for searching park units including unit codes, names, states, regions, networks, regions, etc.
 #' These functions can be handy if you need to supply the unit code when downloading data but only know the park name, if you have a unit code but don't know what park, region, etc it refers to, or if you want to know all the parks that are within a given network, region, or state (note: it will actually supply all park units, not just National Parks).
@@ -11,7 +11,7 @@
 #'
 #' @importFrom magrittr %>%
 #'
-#' @return one data frame to the global environment. May contain multiple matches. Sufficient detail should be provided to choose the appropriate UnitCode for use with other NPSutils functions such as get.parkTaxonReferences (in get.referenceInfo.R).
+#' @return one data frame to the global environment. May contain multiple matches. 
 #'
 #' @export
 #' @examples
@@ -22,53 +22,55 @@ get_unit_code <- function(unit) { # input must have quotes to indicate strings
   # To do:
   # Warnings and checks on parameter inputs are not yet implemented.
   # The output dataframe is a little unwieldy and could be cleaned up.
-
-
-  # It is worth figuring out how stable the URL is: when were the data last updated? How frequently are they updated? Are field codes ever changed, or just data added? Do updates entail a new URL?
+ 
   f <- file.path(tempdir(), "irmadownload.xml")
   if (!file.exists(f)) {
-    curl::curl_download("https://irmaservices.nps.gov/v2/rest/unit/", f) # access all park codes from NPS xml file
-    # curl::curl_download(paste0("https://irmaservices.nps.gov/v2/rest/unit/",Unit, f)) #doesn't work
-    # curl::curl_download(paste0("https://irmaservices.nps.gov/v2/rest/unit/", Unit,""), f) #works but requires removing preceding if(!file.exists(f))
-    print("file downloaded") # check for download; remove when dev phase over
+    # access all park codes from NPS xml file
+    curl::curl_download("https://irmaservices.nps.gov/v2/rest/unit/", f) 
   }
   result <- XML::xmlParse(file = f) # parse xml
-  dat <- XML::xmlToDataFrame(result) # xml to dataframe
-  dat <- dat[, c(1, 3, 5, 7, 8, 9, 11, 13)] # pare down the output some
-  alpha <- dat %>% dplyr::filter(grepl(unit, FullName, ignore.case = TRUE)) # filter FullName for input
+  dat <- XML::xmlToDataFrame(result) 
+  # pare down the output some
+  dat <- dat[, c(1, 3, 5, 7, 8, 9, 11, 13)] 
+  # filter FullName for input
+  alpha <- dat %>% dplyr::filter(grepl(unit, FullName, ignore.case = TRUE)) 
   return(alpha) # return unit code
 }
 
 
 #' Restricts get_unit_code to just National Parks
 #'
-#' @description \code{get_park_code} is identical to \code{get_unit_code} except output is restricted to just National Parks (as opposed to including networks, etc.).Accesses info from irmaservices.nps.gov. Search for park or park unit with any string and return all applicable national park unitCodes. Handy for use with get.dataPackage if you don't know a Park's UnitCode.
+#' @description `get_park_code` is identical to `get_unit_code` except the output is restricted to just National Parks (as opposed to including networks, etc.). Accesses info from irmaservices.nps.gov. Search for park or park unit with any string and return all applicable national park unitCodes.
 #'
 #' @param park is a case-insensitive string containing some part of the unit's FullName, e.g "Yellow".
 #'
-#' @return one data frame to the global environment. May contain multiple matches. Sufficient detail should be provided to choose the appropriate UnitCode for use with other NPSutils functions such as get.parkTaxonReferences (in ReferenceInfo.R). Dataframe contains UnitCode, FullName, UnitLifeCycle, Network, Region, and StateCodes.
+#' @return one data frame to the global environment. May contain multiple matches.
 #'
 #' @export
 #' @examples
 #' \dontrun{
 #' get_park_code("Yellow")
 #' }
-get_park_code <- function(park) { # case-insensitive string (in quotes) containing some part of the unit's FullName
+get_park_code <- function(park) { 
   f <- file.path(tempdir(), "irmadownload.xml")
   if (!file.exists(f)) {
-    curl::curl_download("https://irmaservices.nps.gov/v2/rest/unit/", f) # access all park codes from NPS xml file
+    # access all park codes from NPS xml file
+    curl::curl_download("https://irmaservices.nps.gov/v2/rest/unit/", f) 
   }
   result <- XML::xmlParse(file = f)
-  dat <- XML::xmlToDataFrame(result) # xml to dataframe
-  dat <- dat %>% dplyr::filter(grepl("National Park", UnitDesignationName)) # limit search to just National Parks
-  dat <- dat[, c(1, 3, 8, 9, 11, 13)] # cleanup the output some
-  alpha <- dat %>% dplyr::filter(grepl(park, FullName, ignore.case = TRUE)) # filter FullName for input
+  dat <- XML::xmlToDataFrame(result)
+  # limit search to just National Parks
+  dat <- dat %>% dplyr::filter(grepl("National Park", UnitDesignationName)) 
+  # cleanup the output some
+  dat <- dat[, c(1, 3, 8, 9, 11, 13)] 
+  # filter FullName for input
+  alpha <- dat %>% dplyr::filter(grepl(park, FullName, ignore.case = TRUE)) 
   return(alpha) # return park code
 }
 
 #' Gets information about a park Unit Code
 #'
-#' @description \code{get_unit_code_info} accesses info from irmaservices.nps.gov and allows you to search a Park Unit Code and determine which park, network, or other entity it is associated with along with ancillary information.
+#' @description `get_unit_code_info` accesses info from irmaservices.nps.gov and allows you to search a Park Unit Code and determine which park, network, or other entity it is associated with along with ancillary information.
 #'
 #' @param code is a case-insensitive string. It typically is 4 letters long and typically does not include numbers but may be longer, shorter, or include special characters such as "-", e.g. "SFCN".
 #'
@@ -79,22 +81,26 @@ get_park_code <- function(park) { # case-insensitive string (in quotes) containi
 #' \dontrun{
 #' get_unit_code_info("SFCN")
 #' }
-get_unit_code_info <- function(code) { # input must have quotes to indicate strings
+get_unit_code_info <- function(code) {
   f <- file.path(tempdir(), "irmadownload.xml")
   if (!file.exists(f)) {
-    curl::curl_download(paste0("https://irmaservices.nps.gov/v2/rest/unit/", f)) # access all park codes from NPS xml file
+    # access all park codes from NPS xml file
+    curl::curl_download(paste0("https://irmaservices.nps.gov/v2/rest/unit/", f))
   }
   result <- XML::xmlParse(file = f)
-  dat <- XML::xmlToDataFrame(result) # xml to dataframe
-  dat <- dat[, c(1, 3, 8, 9, 11, 13)] # cleanup/reduce the output some
-  alpha <- dat %>% dplyr::filter(grepl(code, UnitCode, ignore.case = TRUE)) # filter FullName for input
-  return(alpha) # return park code
+  dat <- XML::xmlToDataFrame(result)
+  # cleanup/reduce the output some
+  dat <- dat[, c(1, 3, 8, 9, 11, 13)]
+  # filter FullName for input
+  alpha <- dat %>% dplyr::filter(grepl(code, UnitCode, ignore.case = TRUE))
+  # return park code
+  return(alpha) 
 }
 
 
 #' Search irmaservices.nps using any piece of information.
 #'
-#' @description \code{get_unit_info} accesses info from irmaservices.nps.gov and allows you to search a Park Unit based on any number or combination of parameters. Not all parameters need to be specified, but it is probably worth specifying which parameters ARE specified, e.g. get.unitInfo(LifeCycle="Inactive"). If the arguments are not specified, they will default to the order supplied in the function.
+#' @description `get_unit_info` accesses info from irmaservices.nps.gov and allows you to search a Park Unit based on any number or combination of parameters. Not all parameters need to be specified, but it is probably worth specifying which parameters ARE specified, e.g. get.unitInfo(LifeCycle="Inactive"). If the arguments are not specified, they will default to the order supplied in the function.
 #'
 #' @param code defaults to NULL. Is a case-insensitive string. It typically is 4 letters long and typically does not include numbers but may be longer, shorter, or include special characters such as "-".
 #' @param park defaults to NULL. Is a case-insensitive string. It will search for any subset of the FullName or parks or park units
@@ -121,34 +127,21 @@ get_unit_info <- function(code = NULL,
                           net_name = NULL,
                           region_abb = NULL,
                           region = NULL,
-                          state = NULL) { # input must have quotes to indicate strings
+                          state = NULL) { 
   f <- file.path(tempdir(), "irmadownload.xml")
   if (!file.exists(f)) {
     # access all park codes from NPS xml file
     curl::curl_download("https://irmaservices.nps.gov/v2/rest/unit/", f) 
   }
   result <- XML::xmlParse(file = f)
-  dat <- XML::xmlToDataFrame(result) # xml to dataframe
+  dat <- XML::xmlToDataFrame(result)
   # check UnitCode:
   if (!is.null(code)) {
-    # if(grepl("[0-9]", Code)>0){
-    #  stop("Code cannot contain numbers")
-    # if(grepl("all", Code, ignore.case=TRUE)>1){
-    #  dat<-dat
-    #  }
-    # else{
     dat <- dat %>% dplyr::filter(grepl(code, UnitCode, ignore.case = TRUE))
-    #  }
-    # }
   }
 
   # check UnitCycle:
   if (!is.null(life_cycle)) {
-    # LifeCycle<-tolower(LifeCycle)
-    # if( (LifeCycle == "active") + (LifeCycle == "inactive")\
-    #  (LifeCycle=="pending") < 1)
-    #  stop("LifeCycle must be \"Active\", \"Inactive\", or \"Pending\"")
-
     names <- paste0("\\<", life_cycle, "\\>")
     dat <- dat %>% dplyr::filter(grepl(names, UnitLifecycle,
                                       ignore.case = TRUE))