v0.2.4

Author: boshek

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: tidyhydat
 Title: Extract tidy hydrometric data
-Version: 0.2.3
+Version: 0.2.4
 Authors@R: c(person("Sam", "Albers", email = "sam.albers@gov.bc.ca", role = c("aut", "cre"),
            ), person("Dave", "Hutchinson", email = "david.hutchinson@canada.ca", role = "ctb"))
 Description: tidyhydat provides functions to extract river data from Water Survey of Canada sources and make it tidy.

NAMESPACE

@@ -18,6 +18,7 @@ export(STN_OPERATION_SCHEDULE)
 export(STN_REGULATION)
 export(STN_REMARKS)
 export(VERSION)
+export(download_hydat)
 export(download_realtime_dd)
 export(download_realtime_ws)
 export(get_ws_token)
@@ -35,3 +36,5 @@ importFrom(lubridate,year)
 importFrom(lubridate,ymd)
 importFrom(tibble,tibble)
 importFrom(tidyr,gather)
+importFrom(utils,download.file)
+importFrom(utils,unzip)

NEWS.md

@@ -1,9 +1,15 @@
+#tidyhydat 0.2.4
+* download_realtime_ws can now accept stations from multiple provinces or simply select multiple provinces
+* better error messages for get_ws_token and download_realtime_ws
+* All functions that previously accepted STATION_NUMBER == "ALL" now throw an error. 
+* Added function to download hydat
+
 #tidyhydat 0.2.3
 * Remove significant redundancy in station selecting mechanism
 * Added package startup message when HYDAT is out of date  
 * Add internal allstations data
 * Added all the tables as functions or data from HYDAT
-* Made missing station ouput truncated at 10 missign stations
+* Made missing station ouput truncated at 10 missing stations
 
 # tidyhdyat 0.2.2
 * Adding several new tables

R/tidyhydat.R

@@ -30,6 +30,8 @@
 #' @importFrom lubridate year
 #' @importFrom lubridate month
 #' @importFrom lubridate day
+#' @importFrom utils download.file
+#' @importFrom utils unzip
 #' @import readr
 #' @import dplyr
 #' @import httr
@@ -47,29 +49,3 @@
 #'   
 NULL
 
-
-#' REmoves notes from R CMD check for NSE
-#'
-.onLoad <- function(libname = find.package("tidyhydat"), pkgname = "tidyhydat"){
-  # CRAN Note avoidance
-  if(getRversion() >= "2.15.1")
-    utils::globalVariables(
-      # Vars used in Non-Standard Evaluations, declare here to avoid CRAN warnings
-      ## This is getting ridiculous
-      c("PROV_TERR_STATE_LOC", "FULL_MONTH", "MAX", "DAY", "FLOW", "MONTH",
-        "YEAR", "Date","stns", "FLOW", "LEVEL","PRECISION_CODE","NO_DAYS",
-        "variable","temp","DATA_SYMBOLS","FLOW_SYMBOL","SYMBOL_EN","Value",
-        "Unit","Grade","Symbol","Approval","Parameter","Code","param_id","Name_En",
-        "Name_Fr","LEVEL_SYMBOL","ID","val","key","CODE","GRADE","SYMBOL",
-        "DATA_TYPE","DATA_TYPES","DATA_TYPE_EN","MAX_DAY","MAX_MONTH","MAX_SYMBOL","MEAN",
-        "MIN","MIN_DAY","MIN_MONTH","MIN_SYMBOL","SUM_STAT","HOUR", "MINUTE", "PEAK", 
-        "PEAK_CODE", "REGIONAL_OFFICE_ID","TIME_ZONE","SUSCON",  "CONCENTRATION","CONCENTRATION_EN",
-        "CONVERSION_FACTOR", "DATE", "DATUM_EN","DATUM_EN_FROM", "DATUM_EN_TO", "LOAD", "MEASUREMENT_EN",
-        "MONTH_FROM", "MONTH_TO", "OPERATION_EN", "PARTICLE_SIZE", "PERCENT", "REMARK_EN", "REMARK_TYPE_EN",
-        "SAMPLER_TYPE", "SAMPLE_REMARK_EN", "SAMPLING_VERTICAL_EN", "SAMPLING_VERTICAL_LOCATION", "SED_DATA_TYPE_EN",
-        "SV_DEPTH2", "TEMPERATURE", "TIME_SYMBOL", "YEAR_FROM", "YEAR_TO",
-        "." # piping requires '.' at times
-      )
-    )
-  invisible()
-}

R/zzz.R

@@ -25,3 +25,29 @@
 #  
 #
 #}
+
+#' Removes notes from R CMD check for NSE
+#'
+.onLoad <- function(libname = find.package("tidyhydat"), pkgname = "tidyhydat"){
+  # CRAN Note avoidance
+  if(getRversion() >= "2.15.1")
+    utils::globalVariables(
+      # Vars used in Non-Standard Evaluations, declare here to avoid CRAN warnings
+      ## This is getting ridiculous
+      c("PROV_TERR_STATE_LOC", "FULL_MONTH", "MAX", "DAY", "FLOW", "MONTH",
+        "YEAR", "Date","stns", "FLOW", "LEVEL","PRECISION_CODE","NO_DAYS",
+        "variable","temp","DATA_SYMBOLS","FLOW_SYMBOL","SYMBOL_EN","Value",
+        "Unit","Grade","Symbol","Approval","Parameter","Code","param_id","Name_En",
+        "Name_Fr","LEVEL_SYMBOL","ID","val","key","CODE","GRADE","SYMBOL",
+        "DATA_TYPE","DATA_TYPES","DATA_TYPE_EN","MAX_DAY","MAX_MONTH","MAX_SYMBOL","MEAN",
+        "MIN","MIN_DAY","MIN_MONTH","MIN_SYMBOL","SUM_STAT","HOUR", "MINUTE", "PEAK", 
+        "PEAK_CODE", "REGIONAL_OFFICE_ID","TIME_ZONE","SUSCON",  "CONCENTRATION","CONCENTRATION_EN",
+        "CONVERSION_FACTOR", "DATE", "DATUM_EN","DATUM_EN_FROM", "DATUM_EN_TO", "LOAD", "MEASUREMENT_EN",
+        "MONTH_FROM", "MONTH_TO", "OPERATION_EN", "PARTICLE_SIZE", "PERCENT", "REMARK_EN", "REMARK_TYPE_EN",
+        "SAMPLER_TYPE", "SAMPLE_REMARK_EN", "SAMPLING_VERTICAL_EN", "SAMPLING_VERTICAL_LOCATION", "SED_DATA_TYPE_EN",
+        "SV_DEPTH2", "TEMPERATURE", "TIME_SYMBOL", "YEAR_FROM", "YEAR_TO","condensed_date",
+        "." # piping requires '.' at times
+      )
+    )
+  invisible()
+}

README.Rmd

@@ -47,6 +47,11 @@ To use most of the `tidyhydat` package you will need the most recent version of
 
 - http://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/
 
+`tidyhydat` also provides a convenience function to download hydat (be patient though this takes a long time!):
+```{r, eval=FALSE}
+download_hydat(hydat_path = "H:/")
+```
+
 You will need to download that file, unzip it and put it somewhere on local storage. The path to the sqlite3 must be specified within each function that uses HYDAT. If the path is very long it may be useful to store it as an object with a smaller name like this:
 ```{r eval = FALSE}
 hydat_loc = "A very long path that points to the HYDAT sqlite3 database"
@@ -64,6 +69,7 @@ It is important that you name the variable `hydat` as that is name of the variab
 
 ## Usage
 
+### HYDAT
 This is a basic example of `tidyhydat` usage. All functions that interact with HYDAT are capitalized (e.g. `STATIONS`). These functions follow a common argument structure which can be illustrated with the `DLY_FLOWS()` function. If you would like to extract only station `08LA001` you can supply the `STATION_NUMBER`. The `hydat_path` argument is supplied here as a local path the database. Yours will be different or missing altogether if you set the variable in your `.Renviron` file which is highly recommend. 
 
 ```{r example1, warning=FALSE}
@@ -81,6 +87,18 @@ You can also make use of auxiliary function in `tidyhdyat` called `search_name`
 search_name("liard")
 ```
 
+### Real-time
+To download real-time data using the datamart we can use approximately the same conventions discussed above. Using `download_realtime_dd()` we can easily select specific stations by supplying a station of interest:
+```{r}
+download_realtime_dd(STATION_NUMBER = "08LG006")
+```
+Another option is to provide simply the province as an argument and download all stations from that province:
+```{r}
+download_realtime_dd(PROV_TERR_STATE_LOC = "PE")
+```
+Additionally `download_realtime_ws()` provides another means of acquiring real time data.
+
+
 ## Project Status
 
 This package is under continual development.

README.md

@@ -37,6 +37,12 @@ To use most of the `tidyhydat` package you will need the most recent version of
 
 -   <http://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/>
 
+`tidyhydat` also provides a convenience function to download hydat (be patient though this takes a long time!):
+
+``` r
+download_hydat(hydat_path = "H:/")
+```
+
 You will need to download that file, unzip it and put it somewhere on local storage. The path to the sqlite3 must be specified within each function that uses HYDAT. If the path is very long it may be useful to store it as an object with a smaller name like this:
 
 ``` r
@@ -60,6 +66,8 @@ It is important that you name the variable `hydat` as that is name of the variab
 Usage
 -----
 
+### HYDAT
+
 This is a basic example of `tidyhydat` usage. All functions that interact with HYDAT are capitalized (e.g. `STATIONS`). These functions follow a common argument structure which can be illustrated with the `DLY_FLOWS()` function. If you would like to extract only station `08LA001` you can supply the `STATION_NUMBER`. The `hydat_path` argument is supplied here as a local path the database. Yours will be different or missing altogether if you set the variable in your `.Renviron` file which is highly recommend.
 
 ``` r
@@ -117,6 +125,52 @@ search_name("liard")
 #> 3        10BE006 LIARD RIVER ABOVE KECHIKA RIVER
 ```
 
+### Real-time
+
+To download real-time data using the datamart we can use approximately the same conventions discussed above. Using `download_realtime_dd()` we can easily select specific stations by supplying a station of interest:
+
+``` r
+download_realtime_dd(STATION_NUMBER = "08LG006")
+#> # A tibble: 17,508 x 8
+#>    STATION_NUMBER PROV_TERR_STATE_LOC                Date Parameter Value
+#>             <chr>               <chr>              <dttm>     <chr> <dbl>
+#>  1        08LG006                  BC 2017-07-30 08:00:00      FLOW  7.41
+#>  2        08LG006                  BC 2017-07-30 08:05:00      FLOW  7.41
+#>  3        08LG006                  BC 2017-07-30 08:10:00      FLOW  7.41
+#>  4        08LG006                  BC 2017-07-30 08:15:00      FLOW  7.38
+#>  5        08LG006                  BC 2017-07-30 08:20:00      FLOW  7.38
+#>  6        08LG006                  BC 2017-07-30 08:25:00      FLOW  7.38
+#>  7        08LG006                  BC 2017-07-30 08:30:00      FLOW  7.38
+#>  8        08LG006                  BC 2017-07-30 08:35:00      FLOW  7.38
+#>  9        08LG006                  BC 2017-07-30 08:40:00      FLOW  7.38
+#> 10        08LG006                  BC 2017-07-30 08:45:00      FLOW  7.38
+#> # ... with 17,498 more rows, and 3 more variables: Grade <chr>,
+#> #   Symbol <chr>, Code <chr>
+```
+
+Another option is to provide simply the province as an argument and download all stations from that province:
+
+``` r
+download_realtime_dd(PROV_TERR_STATE_LOC = "PE")
+#> # A tibble: 77,824 x 8
+#>    STATION_NUMBER PROV_TERR_STATE_LOC                Date Parameter Value
+#>             <chr>               <chr>              <dttm>     <chr> <dbl>
+#>  1        01CD005                  PE 2017-07-30 04:00:00      FLOW    NA
+#>  2        01CD005                  PE 2017-07-30 04:05:00      FLOW    NA
+#>  3        01CD005                  PE 2017-07-30 04:10:00      FLOW    NA
+#>  4        01CD005                  PE 2017-07-30 04:15:00      FLOW    NA
+#>  5        01CD005                  PE 2017-07-30 04:20:00      FLOW    NA
+#>  6        01CD005                  PE 2017-07-30 04:25:00      FLOW    NA
+#>  7        01CD005                  PE 2017-07-30 04:30:00      FLOW    NA
+#>  8        01CD005                  PE 2017-07-30 04:35:00      FLOW    NA
+#>  9        01CD005                  PE 2017-07-30 04:40:00      FLOW    NA
+#> 10        01CD005                  PE 2017-07-30 04:45:00      FLOW    NA
+#> # ... with 77,814 more rows, and 3 more variables: Grade <chr>,
+#> #   Symbol <chr>, Code <chr>
+```
+
+Additionally `download_realtime_ws()` provides another means of acquiring real time data.
+
 Project Status
 --------------
 

inst/doc/tidyhydat.R

@@ -32,6 +32,9 @@ DLY_FLOWS(hydat_path = "H:/Hydat.sqlite3",
           start_date = "1992-03-15",
           end_date = "1992-04-15")
 
+## ---- eval=FALSE---------------------------------------------------------
+#  download_hydat(hydat_path = "H:/")
+
 ## ------------------------------------------------------------------------
 VERSION(hydat_path = "H:/Hydat.sqlite3")
 
@@ -87,5 +90,8 @@ param_id
 #  WS_PWD = "here is the password that ECCC gave you"
 
 ## ------------------------------------------------------------------------
-download_realtime_dd(STATION_NUMBER = "08LG006", PROV_TERR_STATE_LOC = "BC")
+download_realtime_dd(STATION_NUMBER = "08LG006")
+
+## ------------------------------------------------------------------------
+download_realtime_dd(PROV_TERR_STATE_LOC = "PE")
 

inst/doc/tidyhydat.Rmd

@@ -89,6 +89,11 @@ All functions that interact with HYDAT are capitalized (e.g. `STATIONS`). To use
 
 - http://collaboration.cmc.ec.gc.ca/cmc/hydrometrics/www/
 
+`tidyhydat` also provides a convenience function to download hydat (be patient though this takes a long time!):
+```{r, eval=FALSE}
+download_hydat(hydat_path = "H:/")
+```
+
 You can check your version of HYDAT with the `VERSION()` function:
 ```{r}
 VERSION(hydat_path = "H:/Hydat.sqlite3")
@@ -192,11 +197,14 @@ WS_PWD = "here is the password that ECCC gave you"
 Now these values can be accessed within an R session without giving away your secrets (Using `Sys.getenv()`). Just remember to call them directly and don't assign them to a variable. 
 
 ## MSC datamart - `download_realtime_dd()`
-To download real-time data using the datamart we can use approximately the same conventions discussed above. Using `download_realtime_dd()` we can easily select specific stations by supplying a station of interest. Note that in contrast to `download_realtime_ws()` but similar to `DLY_FLOWS()`, we need to supply both the station and the province that we are interested in:
+To download real-time data using the datamart we can use approximately the same conventions discussed above. Using `download_realtime_dd()` we can easily select specific stations by supplying a station of interest:
 ```{r}
-download_realtime_dd(STATION_NUMBER = "08LG006", PROV_TERR_STATE_LOC = "BC")
+download_realtime_dd(STATION_NUMBER = "08LG006")
+```
+Another option is to provide simply the province as an argument and download all stations from that province:
+```{r}
+download_realtime_dd(PROV_TERR_STATE_LOC = "PE")
 ```
-
 
 ## Compare `download_realtime_ws` and `download_realtime_dd`
 `tidyhydat` provides two methods to download real-time data. `download_realtime_ws()`, coupled with `get_ws_token()`, is an API client for a web service hosted by ECCC. `download_realtime_dd()` provides a function to import openly accessible .csv files from [here](http://dd.weather.gc.ca/hydrometric/). `download_realtime_ws()` has several difference to `download_realtime_dd()`. These include: