version 0.2

cran · Oct 5, 2014 · c57c54c · c57c54c
1 parent 6861883
commit c57c54c
Show file tree

Hide file tree

Showing 18 changed files with 758 additions and 442 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -13,16 +13,16 @@ Description: Estimates of rainfall at desired frequency (e.g., 1% annual
     and analyze the 1-km GIS files provided by NWS' PF Data Server for
     the entire USA. This package also comes with datasets on record point
     rainfall measurements provided by NWS-HDSC.
-Version: 0.1
+Version: 0.2
 Author: Gopi Goteti <my.ration.shop@gmail.com>
 Maintainer: Gopi Goteti <my.ration.shop@gmail.com>
 Depends: R (>= 3.0.2)
 Imports: RCurl, SDMTools
-Suggests: raster, maps
-License: GPL (>= 2)
+VignetteBuilder: knitr
+Suggests: knitr, raster, maps
+License: MIT + file LICENSE
 LazyData: true
-Collate: 'data.r' 'extract_freq.r'
-Packaged: 2014-05-22 21:42:56 UTC; GGoteti
+Packaged: 2014-10-05 04:26:46 UTC; gotetigx
 NeedsCompilation: no
 Repository: CRAN
-Date/Publication: 2014-05-23 07:24:57
+Date/Publication: 2014-10-05 07:43:50
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,2 @@
+YEAR: 2014
+COPYRIGHT HOLDER: Gopi Goteti
diff --git a/MD5 b/MD5
@@ -1,16 +1,17 @@
-ec81b215a14ec3c4f8539bee8bbf3654 *DESCRIPTION
-17868e1952e4c641ca5fd19d020de406 *NAMESPACE
-277186c721610363b1d6125559f8f17d *NEWS
+bf1a28fdc6e6178e9778fe558561c295 *DESCRIPTION
+5faa42f55f737d4922fc24cd063d35d0 *LICENSE
+5fab2599e1c7ceecdbc318494c35cbb9 *NAMESPACE
+52c77ac656c4df52393488dcfe3a6c1c *NEWS
 de6c18eb7478cd2219f350d8a9372b5a *R/data.r
-e9502af2f1e6f0be6a3b696183e30f2d *R/extract_freq.r
-f08437957fb679afade4c264037acc3e *build/vignette.rds
+6edf6f2266ce76a61cdc4802d38909a2 *R/extract_freq.r
+567bdc36550c4642c77f8785f6e8818b *build/vignette.rds
 d19cf4b9fa12006bfac5e1f272ab16f5 *data/rain_max_usa.rda
 c33273ec348fa4e454c9d1fc9616e817 *data/rain_max_world.rda
-81d92579688cb866cc0e3d6efb9458d7 *inst/doc/rainfreq_demo.R
-a30f3de6f18f36e73c755d26e785ca8c *inst/doc/rainfreq_demo.Rnw
-8801d7cca7119f32f2c6ffcec92501b1 *inst/doc/rainfreq_demo.pdf
-58369cc99ef77aa2732ee99cc2eee6d6 *man/extract_freq.Rd
-49bf79cba8993fd03f093096a2fa207a *man/rain_max_usa.Rd
-cf9602e1f290fd9f0e0b1b5851bdde78 *man/rain_max_world.Rd
-73fc852caa2a593e29b17051af26d8df *man/rainfreq.Rd
-a30f3de6f18f36e73c755d26e785ca8c *vignettes/rainfreq_demo.Rnw
+9287b1cfdbe026730fd958c39f372cac *inst/doc/rainfreq_demo.R
+be1c326bfe933d62f690b8a994c33d1c *inst/doc/rainfreq_demo.Rmd
+18c51e575fbd6450fcae24689144d0ed *inst/doc/rainfreq_demo.html
+8ac7ed9fd32611a2a8fbea63c0d57868 *man/extract_freq.Rd
+59b6214b1e84e09bf3a14110d24044ec *man/rain_max_usa.Rd
+5587bdc18285cb17bc42c86c1a17e4a9 *man/rain_max_world.Rd
+1ecc2f030b754d0d609a4d5ae5e42a82 *man/rainfreq.Rd
+be1c326bfe933d62f690b8a994c33d1c *vignettes/rainfreq_demo.Rmd
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,3 +1,5 @@
+# Generated by roxygen2 (4.0.2): do not edit by hand
+
 export(extract_freq)
 import(RCurl)
 import(SDMTools)
diff --git a/NEWS b/NEWS
@@ -1,3 +1,14 @@
+Version 0.2, Oct 2014
+-----------
+
+* NWS' website (ftp site) sometimes has connectivity issues. Website is checked for a response, and function proceeds only if it does.
+
+* Package vignette changed to a Rmarkdown document.
+
+* License changed from GPL to MIT
+
+* The three tasks mentioned in v0.1 NEWS still remain to be addressed.
+
 Version 0.1, May 2014
 -----------
 

diff --git a/R/extract_freq.r b/R/extract_freq.r
@@ -98,7 +98,16 @@ extract_freq <- function(region_name = "se",
 
     # NWS ftp site
     data_source <- "ftp://hdsc.nws.noaa.gov/pub/hdsc/data/"
+
+    # check whether the site exists/responds
+    if (!url.exists(data_source)) {
+      stop(paste("NWS website", data_source, "is not responding, please try later!"))
+    }
     url_name <- paste0(data_source, region_name, "/", file_dump)
+    if (!url.exists(url_name)) {
+      stop(paste("NWS website", url_name, "is not responding or does not exist, 
+                 please check and/or try later!"))
+    }
 
     # download using RCurl
     message("downloading data. might take a few moments ...")

diff --git a/build/vignette.rds b/build/vignette.rds
diff --git a/inst/doc/rainfreq_demo.R b/inst/doc/rainfreq_demo.R
@@ -1,101 +1,59 @@
-### R code from vignette source 'rainfreq_demo.Rnw'
+## ----, echo = FALSE, message = FALSE-------------------------------------
+knitr::opts_chunk$set(
+  comment = "#>",
+  error = FALSE,
+  tidy = FALSE)
 
-###################################################
-### code chunk number 1: rainfreq_demo.Rnw:24-29
-###################################################
+## ----, message = FALSE---------------------------------------------------
 require(rainfreq)
 require(RCurl)
 require(SDMTools)
 require(raster)
 require(maps)
 
-
-###################################################
-### code chunk number 2: rainfreq_demo.Rnw:34-36
-###################################################
+## ------------------------------------------------------------------------
 x_se <- extract_freq()
 print(x_se)
 
-
-###################################################
-### code chunk number 3: rainfreq_demo.Rnw:41-43
-###################################################
+## ------------------------------------------------------------------------
 x_mw <- extract_freq(region_name = "mw", storm_RP = 1000, storm_duration = "48h")
 print(x_mw)
 
-
-###################################################
-### code chunk number 4: rainfreq_demo.Rnw:48-50
-###################################################
+## ------------------------------------------------------------------------
 x_hi <- extract_freq(region_name = "hi", storm_RP = 10, storm_duration = "6h")
 print(x_hi)
 
-
-###################################################
-### code chunk number 5: rainfreq_demo.Rnw:55-59
-###################################################
+## ------------------------------------------------------------------------
 data(rain_max_usa)
 head(rain_max_usa)
 data(rain_max_world)
 head(rain_max_world)
 
-
-###################################################
-### code chunk number 6: rainfreq_demo.Rnw:68-71
-###################################################
+## ------------------------------------------------------------------------
 x_se <- x_se * 0.001
 x_mw <- x_mw * 0.001
 x_hi <- x_hi * 0.001
 
-
-###################################################
-### code chunk number 7: rainfreq_demo.Rnw:76-93 (eval = FALSE)
-###################################################
-## # southeast
-## plot(x_se, breaks = c(6, 9, 12, 15, 18), 
-##      col = c("red", "yellow", "green", "blue"), 
-##      main = "100-year 24-hour Rainfall for Southeast USA (inches)")
-## map('state', region = c('florida', 'arkansas', 'louisiana', 'mississippi', 
-##                         'alabama', 'georgia'), add = TRUE)
-## # midwest
-## plot(x_mw, breaks = c(2, 5, 10, 15, 20), 
-##      col = c("red", "yellow", "green", "blue"),
-##      main = "1000-year 48-hour Rainfall for Midwest USA (inches)")
-## map('state', region = c('colorado', 'north dakota', 'south dakota', 'nebraska', 
-##                         'oklahoma', 'minnesota', 'iowa', 'missouri', 
-##                         'wisconsin', 'michigan'), add = TRUE)
-## # hawaii
-## plot(x_hi, breaks = c(1, 3, 6, 9, 12), 
-##      col = c("red", "yellow", "green", "blue"),
-##      main = "10-year 6-hour Rainfall for Hawaii (inches)")
-
-
-###################################################
-### code chunk number 8: figx
-###################################################
+## ------------------------------------------------------------------------
+# southeast
 plot(x_se, breaks = c(6, 9, 12, 15, 18), 
      col = c("red", "yellow", "green", "blue"), 
      main = "100-year 24-hour Rainfall for Southeast USA (inches)")
 map('state', region = c('florida', 'arkansas', 'louisiana', 'mississippi', 
                         'alabama', 'georgia'), add = TRUE)
 
-
-###################################################
-### code chunk number 9: figy
-###################################################
+## ------------------------------------------------------------------------
+# midwest
 plot(x_mw, breaks = c(2, 5, 10, 15, 20), 
      col = c("red", "yellow", "green", "blue"),
      main = "1000-year 48-hour Rainfall for Midwest USA (inches)")
 map('state', region = c('colorado', 'north dakota', 'south dakota', 'nebraska', 
                         'oklahoma', 'minnesota', 'iowa', 'missouri', 
                         'wisconsin', 'michigan'), add = TRUE)
 
-
-###################################################
-### code chunk number 10: figz
-###################################################
+## ------------------------------------------------------------------------
+# hawaii
 plot(x_hi, breaks = c(1, 3, 6, 9, 12), 
      col = c("red", "yellow", "green", "blue"),
      main = "10-year 6-hour Rainfall for Hawaii (inches)")
 
-
diff --git a/inst/doc/rainfreq_demo.Rmd b/inst/doc/rainfreq_demo.Rmd
@@ -0,0 +1,115 @@
+<!--
+%\VignetteEngine{knitr}
+%\VignetteIndexEntry{Package Demo: rainfreq}
+-->
+
+```{r, echo = FALSE, message = FALSE}
+knitr::opts_chunk$set(
+  comment = "#>",
+  error = FALSE,
+  tidy = FALSE)
+```
+
+# Introduction to *rainfreq*
+
+This vignette first provides an overview of the rainfall frequency estimates from the National Weather Service ([NWS][url1_ref]) followed by some examples on how to obtain and plot the data using the *rainfreq* package.
+
+Rainfall frequency estimates for the USA from the NOAA National Weather Service's (NWS) division of Hydrometeorological Design Studies Center (HDSC) are often used in the the design of dams and other hydraulic structures and also in environmental planning and management. Data from NOAA NWS is available in various formats, including a user interface to extract the desired information. However, there is a lot of data and it is available in raw format as a large number of 1-km resolution GIS files. 
+
+The *rainfreq* package provides functionality to access 1-km rainfall frequency estimates in GIS format provided by the [NWS' PF Data Server][url2_ref]. The goal of the *rainfreq* package is to make the retrieval and analysis of this GIS data easier. Moreover, *rainfreq* also comes with NWS datasets on [record point rainfall measurements][url3_ref].
+
+
+# Using *rainfreq*
+
+After installing the package, load the package along with *RCurl* (for data extraction) and *SDMTools*, *raster* and *maps* for GIS analysis and graphics.
+
+```{r, message = FALSE}
+require(rainfreq)
+require(RCurl)
+require(SDMTools)
+require(raster)
+require(maps)
+```
+
+The main function provided by *rainfreq* is `extract_freq`. This could be used to extract data for any desired region. The default invocation of `extract_freq` of gets the 100-year 24-hour rainfall for the Southeast USA.
+
+```{r}
+x_se <- extract_freq()
+print(x_se)
+```
+
+In order to obtain the 1000-year 48-hour rainfall for the Midwest, change `region_name`, `storm_RP` and `storm_duration` arguments accordingly.
+
+```{r}
+x_mw <- extract_freq(region_name = "mw", storm_RP = 1000, storm_duration = "48h")
+print(x_mw)
+```
+
+Similarly, in order to obtain the 10-yr 6-hour rainfall for Hawaii, change the `region_name`, `storm_RP` and `storm_duration` arguments accordingly.
+
+```{r}
+x_hi <- extract_freq(region_name = "hi", storm_RP = 10, storm_duration = "6h")
+print(x_hi)
+```
+
+One could also obtain the record storm measurements provided by NWS using *rainfreq*. 
+
+```{r}
+data(rain_max_usa)
+head(rain_max_usa)
+data(rain_max_world)
+head(rain_max_world)
+```
+
+# Graphics
+
+The output from `extract_freq` is designed to be consistent with the `RasterLayer` class of the *SDMTools* package. This consistency enables the use of GIS functions for analysis and graphics provided by *SDMTools* and related packages.
+
+Before plotting the data, convert the data to appropriate units. The original units are in 1000th inches, so multiply by 0.001 to get rainfall in inches. 
+
+```{r}
+x_se <- x_se * 0.001
+x_mw <- x_mw * 0.001
+x_hi <- x_hi * 0.001
+```
+
+Here are the three rainfall estimates obtained so far. State boundaries are added for spatial reference.
+
+Rainfall amounts for selected frequency and duration periods - Souhteast USA.
+```{r}
+# southeast
+plot(x_se, breaks = c(6, 9, 12, 15, 18), 
+     col = c("red", "yellow", "green", "blue"), 
+     main = "100-year 24-hour Rainfall for Southeast USA (inches)")
+map('state', region = c('florida', 'arkansas', 'louisiana', 'mississippi', 
+                        'alabama', 'georgia'), add = TRUE)
+```
+
+Rainfall amounts for selected frequency and duration periods - Midwest USA.
+```{r}
+# midwest
+plot(x_mw, breaks = c(2, 5, 10, 15, 20), 
+     col = c("red", "yellow", "green", "blue"),
+     main = "1000-year 48-hour Rainfall for Midwest USA (inches)")
+map('state', region = c('colorado', 'north dakota', 'south dakota', 'nebraska', 
+                        'oklahoma', 'minnesota', 'iowa', 'missouri', 
+                        'wisconsin', 'michigan'), add = TRUE)
+```
+
+Rainfall amounts for selected frequency and duration periods - Hawaii.
+```{r}
+# hawaii
+plot(x_hi, breaks = c(1, 3, 6, 9, 12), 
+     col = c("red", "yellow", "green", "blue"),
+     main = "10-year 6-hour Rainfall for Hawaii (inches)")
+```
+
+
+# Future Work
+
+The `extract_freq` function's regional selection criterion does not include US territories such as Puerto Rico and Guam. Future updates would incorporate these regions. Also, functionality could be added to extract the upper and lower limits of the confidence intervals on frequency estimates. Currently, data for Texas and Pacific Northwest is not available from NWS; when such data becomes available, *rainfreq* would be updated accordingly.
+
+
+[url1_ref]: http://hdsc.nws.noaa.gov/hdsc/pfds/index.html "NWS"
+[url2_ref]: http://hdsc.nws.noaa.gov/hdsc/pfds/pfds_gis.html "NWS GIS Data"
+[url3_ref]: http://www.nws.noaa.gov/oh/hdsc/record_precip/record_precip.html "NWS Point Records"