ENH: #3 Update noaa ghcnd extract code

DESCRIPTION

@@ -1,11 +1,19 @@
 Package: backburner
-Title: What the Package Does (One Line, Title Case)
+Title: A package to extract US Wildfire data and relevant climate features
 Version: 0.0.0.9000
 Authors@R: 
-    person(given = "Shamindra",
+    c(person(given = "Shamindra",
            family = "Shrotriya",
            role = c("aut", "cre"),
-           email = "shamindra.shrotriya@gmail.com")
+           email = "shamindra.shrotriya@gmail.com"),
+      person(given = "Niccolo",
+           family = "Dalmasso",
+           role = c("aut"),
+           email = "ndalmass@andrew.cmu.edu"),
+      person(given = "Alex",
+           family = "Reinhart",
+           role = c("aut"),
+           email = "areinhar@andrew.cmu.edu"))
 Description: What the package does (one paragraph).
 License: MIT + file LICENSE
 Encoding: UTF-8
@@ -21,6 +29,8 @@ Suggests:
 Language: en-US
 Imports: 
     purrr,
-    magrittr
+    magrittr,
+    rnoaa,
+    janitor
 VignetteBuilder: knitr
 RoxygenNote: 6.1.1.9000

NAMESPACE

@@ -27,6 +27,7 @@ export(get_noaa_stormevents_mtda_paths)
 export(get_noaa_stormevents_new_cnames)
 export(get_transform_geomac)
 export(get_transform_ghcn)
+export(get_transform_ghcnd_stations)
 export(get_transform_mtbs)
 export(ghcn_transform)
 export(ghcn_transform_col_names)
@@ -40,6 +41,7 @@ export(mtbs_transform)
 export(mtbs_transform_col_names)
 export(noaa_ghcn_data_download)
 export(noaa_ghcn_extract)
+export(noaa_ghcn_stations_extract)
 export(noaa_stormevents_data_download)
 export(noaa_stormevents_extract)
 export(noaa_stormevents_identify)

R/ghcn-stations-extract.R

@@ -0,0 +1,37 @@
+#' This is a simply wrapper function to extract \code{noaa ghcn}
+#' station, states, and countries metadata as individual tibbles.
+#' This uses the \code{rnoaa} package directly to do this.
+#'
+#' @return This will be list with 3 separate tibbles named
+#' \code{ghcnd_stations, ghcnd_states, ghcnd_countries}
+#'
+#' @examples
+#' \dontrun{
+#' ghcnd_stations_metadata <- backburner::noaa_ghcn_stations_extract()
+#' }
+#'
+#' @export
+noaa_ghcn_stations_extract <- function(){
+
+    # Download the ghcn stations, states, countries table directly
+    ghcnd_stations  <- rnoaa::ghcnd_stations() %>% tibble::as_tibble(x = .)
+    ghcnd_states    <- rnoaa::ghcnd_states() %>% tibble::as_tibble(x = .)
+    ghcnd_countries <- rnoaa::ghcnd_countries() %>% tibble::as_tibble(x = .)
+
+    # Do renaming of columns for ghcn country table
+    ghcnd_countries <- ghcnd_countries %>%
+                            dplyr::rename(id_fips_code = code,
+                                          country_name = name)
+
+    # Do renaming of columns for ghcn state table
+    ghcnd_states    <- ghcnd_states %>%
+                            dplyr::rename(state_code = code,
+                                      state_name = name)
+
+    # Return output as a list of tibbles
+    out_ghcnd       <- list("ghcnd_stations" = ghcnd_stations,
+                            "ghcnd_states" = ghcnd_states,
+                            "ghcnd_countries" = ghcnd_countries)
+
+    base::return(out_ghcnd)
+}

R/ghcn-stations-transform.R

@@ -0,0 +1,46 @@
+#' Transformed GHCN-Daily Stations file. This is metadata for the GHCN-daily
+#' file. It contains additional info on US/Canada states and country
+#' information for each station
+#'
+#' @examples
+#' \dontrun{
+#' ghcnd_stations_tform <- backburner::get_transform_ghcnd_stations()
+#' }
+#'
+#' @return (tibble) : Transformed tibble of GHCN stations metadata
+#' @export
+get_transform_ghcnd_stations <- function(){
+
+    # First extract the station, states, and countries metadata
+    ghcnd_stations_metadata <- backburner::noaa_ghcn_stations_extract()
+
+    # Download the ghcn stations, states, countries table
+    ghcnd_stations <- ghcnd_stations_metadata[["ghcnd_stations"]]
+    ghcnd_states <- ghcnd_stations_metadata[["ghcnd_states"]]
+    ghcnd_countries <- ghcnd_stations_metadata[["ghcnd_countries"]]
+
+    # Do cleaning of ghcn station table to US/Canada state and country tables
+    ghcnd_stations <- ghcnd_stations %>%
+        dplyr::mutate(id_fips_code =
+                          stringr::str_sub(string = id, start = 1,
+                                           end = 2),
+                      id_network_code =
+                          stringr::str_sub(string = id, start = 3,
+                                           end = 3),
+                      id_station_numsys =
+                          stringr::str_sub(string = id, start = 4,
+                                           end = 12)) %>%
+        dplyr::rename(state_code = state) %>%
+        dplyr::left_join(x = ., y = ghcnd_states,
+                         by = c("state_code")) %>%
+        dplyr::left_join(x = ., y = ghcnd_countries,
+                         by = c("id_fips_code")) %>%
+        dplyr::select(dplyr::starts_with("id"),
+                      latitude, longitude, elevation,
+                      state_code, state_name, country_name,
+                      name,
+                      dplyr::everything()) %>%
+        janitor::clean_names()
+
+    base::return(ghcnd_stations)
+}

README.Rmd

@@ -19,43 +19,17 @@ knitr::opts_chunk$set(
 [![Codecov test coverage](https://codecov.io/gh/shamindras/backburner/branch/master/graph/badge.svg)](https://codecov.io/gh/shamindras/backburner?branch=master)
 <!-- badges: end -->
 
-The goal of backburner is to ...
+The `backburner` package is a collection of utilities for to enable efficient
+extract and transformation of open US Wildfire data and relevant climate 
+features. For more details, please see the [official package documentation](https://shamindras.github.io/backburner/index.html)
 
-## Installation
-
-You can install the released version of backburner from [CRAN](https://CRAN.R-project.org) with:
 
-``` r
-install.packages("backburner")
-```
+## Installation
 
-And the development version from [GitHub](https://github.com/) with:
+You can install the development version of backburner from 
+[GitHub](https://github.com/) with:
 
 ``` r
 # install.packages("devtools")
 devtools::install_github("shamindras/backburner")
 ```
-## Example
-
-This is a basic example which shows you how to solve a common problem:
-
-```{r example, eval=FALSE}
-library(backburner)
-## basic example code
-```
-
-What is special about using `README.Rmd` instead of just `README.md`? You can include R chunks like so:
-
-```{r cars}
-summary(cars)
-```
-
-You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date.
-
-You can also embed plots, for example:
-
-```{r pressure, echo = FALSE}
-plot(pressure)
-```
-
-In that case, don't forget to commit and push the resulting figure files, so they display on GitHub!

README.md

@@ -11,53 +11,18 @@ status](https://travis-ci.org/shamindras/backburner.svg?branch=master)](https://
 coverage](https://codecov.io/gh/shamindras/backburner/branch/master/graph/badge.svg)](https://codecov.io/gh/shamindras/backburner?branch=master)
 <!-- badges: end -->
 
-The goal of backburner is to …
+The `backburner` package is a collection of utilities for to enable
+efficient extract and transformation of open US Wildfire data and
+relevant climate features. For more details, please see the [official
+package
+documentation](https://shamindras.github.io/backburner/index.html)
 
 ## Installation
 
-You can install the released version of backburner from
-[CRAN](https://CRAN.R-project.org) with:
-
-``` r
-install.packages("backburner")
-```
-
-And the development version from [GitHub](https://github.com/) with:
+You can install the development version of backburner from
+[GitHub](https://github.com/) with:
 
 ``` r
 # install.packages("devtools")
 devtools::install_github("shamindras/backburner")
 ```
-
-## Example
-
-This is a basic example which shows you how to solve a common problem:
-
-``` r
-library(backburner)
-## basic example code
-```
-
-What is special about using `README.Rmd` instead of just `README.md`?
-You can include R chunks like so:
-
-``` r
-summary(cars)
-#>      speed           dist       
-#>  Min.   : 4.0   Min.   :  2.00  
-#>  1st Qu.:12.0   1st Qu.: 26.00  
-#>  Median :15.0   Median : 36.00  
-#>  Mean   :15.4   Mean   : 42.98  
-#>  3rd Qu.:19.0   3rd Qu.: 56.00  
-#>  Max.   :25.0   Max.   :120.00
-```
-
-You’ll still need to render `README.Rmd` regularly, to keep `README.md`
-up-to-date.
-
-You can also embed plots, for example:
-
-<img src="man/figures/README-pressure-1.png" width="100%" />
-
-In that case, don’t forget to commit and push the resulting figure
-files, so they display on GitHub\!

vignettes/extract-ghcnd-stations-metadata.Rmd

@@ -0,0 +1,27 @@
+---
+title: "How to Extract NOAA GHCND stations metadata"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{How to Extract NOAA GHCND stations metadata}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+We can easily get nicely transformed [NOAA Global Historical Climatology Network Daily (GHCN-D) station metadata](https://docs.opendata.aws/noaa-ghcn-pds/readme.html). This is 
+particularly useful for US/Canada related weather data.
+
+We can do this by simply running the following code:
+```{r setup, eval=FALSE}
+library(backburner)
+ghcnd_stations <- backburner::get_transform_ghcnd_stations()
+```
+
+You can then use the `ghcnd_stations` tibble as required to get geospatial
+metadata on the `GHCN-D` climate features.