--- title: "Quick Start" author: "Michael Koohafkan" date: "2021-02-17" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Quick Start} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- This document gets you up and running with `cimir `, an R interface to the [California Irrigiation Management Information System](https://cimis.water.ca.gov/) (CIMIS) [Web API](http://et.water.ca.gov/Home/Index). In order to use this package, you will need to [create a CIMIS account](https://cimis.water.ca.gov/Auth/Register.aspx) and [request a web services AppKey](http://et.water.ca.gov/Home/Register/). First, simply load the `cimir` library: ```r library(cimir) ``` If you want `cimir` to automatically use an existing AppKey when you attach the library, you can either set the option `cimir.appkey` in your `.Rprofile` or create an environment variable `CIMIS_APPKEY`. To set an AppKey for a single session, use `set_key()`: ```r set_key("YOUR-APP-KEY-HERE") ``` There are two types of CIMIS queries: station queries and data queries. Station queries return metadata on stations, while data queries return environmental monitoring data. For a list of possible data items, use the function `cimis_items()`: ```r cimis_items() #> Name Data Item Class Data Provider Support #> 1 Average Air Temperature day-air-tmp-avg Daily WSN #> 2 Maximum Air Temperature day-air-tmp-max Daily WSN #> 3 Minimum Air Temperature day-air-tmp-min Daily WSN #> 4 Dew Point day-dew-pnt Daily WSN #> 5 CIMIS ETo day-eto Daily WSN #> 6 ASCE ETo day-asce-eto Daily WSN & SCS #> 7 ASCE ETr day-asce-etr Daily WSN #> 8 Precipitation day-precip Daily WSN #> 9 Average Relative Humidity day-rel-hum-avg Daily WSN #> 10 Maximum Relative Humidity day-rel-hum-max Daily WSN #> 11 Minimum Relative Humidity day-rel-hum-min Daily WSN #> 12 Average Soil Temperature day-soil-tmp-avg Daily WSN #> 13 Maximum Soil Temperature day-soil-tmp-max Daily WSN #> 14 Minimum Soil Temperature day-soil-tmp-min Daily WSN #> 15 Average Solar Radiation day-sol-rad-avg Daily WSN & SCS #> 16 Net Solar Radiation day-sol-rad-net Daily WSN #> 17 Average Vapor Pressure day-vap-pres-avg Daily WSN #> 18 Maximum Vapor Pressure day-vap-pres-max Daily WSN #> 19 Minimum Vapor Pressure day-vap-pres-min Daily WSN #> 20 Wind East-North-East day-wind-ene Daily WSN #> 21 Wind East-South-East day-wind-ese Daily WSN #> 22 Wind North-North-East day-wind-nne Daily WSN #> 23 Wind North-North-West day-wind-nnw Daily WSN #> 24 Wind Run day-wind-run Daily WSN #> 25 Average Wind Speed day-wind-spd-avg Daily WSN #> 26 Wind South-South-East day-wind-sse Daily WSN #> 27 Wind South-South-West day-wind-ssw Daily WSN #> 28 Wind West-North-West day-wind-wnw Daily WSN #> 29 Wind West-South-West day-wind-wsw Daily WSN #> 30 Air Temperature hly-air-tmp Hourly WSN #> 31 Dew Point hly-dew-pnt Hourly WSN #> 32 CIMIS ETo hly-eto Hourly WSN #> 33 Net Radiation hly-net-rad Hourly WSN #> 34 ASCE ETo hly-asce-eto Hourly WSN #> 35 ASCE ETr hly-asce-etr Hourly WSN #> 36 Precipitation hly-precip Hourly WSN #> 37 Relative Humidity hly-rel-hum Hourly WSN #> 38 Resultant Wind hly-res-wind Hourly WSN #> 39 Soil Temperature hly-soil-tmp Hourly WSN #> 40 Solar Radiation hly-sol-rad Hourly WSN #> 41 Vapor Pressure hly-vap-pres Hourly WSN #> 42 Wind Direction hly-wind-dir Hourly WSN #> 43 Wind Speed hly-wind-spd Hourly WSN ``` To get a list of station IDs, use `cimis_station()`: ```r cimis_station() #> # A tibble: 1,473 x 15 #> StationNbr Name City RegionalOffice County ConnectDate DisconnectDate #> #> 1 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 2 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 3 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 4 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 5 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 6 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 7 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 8 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 9 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> 10 1 Fres~ Fres~ South Central~ Fresno 6/7/1982 9/25/1988 #> # ... with 1,463 more rows, and 8 more variables: IsActive , #> # IsEtoStation , Elevation , GroundCover , HmsLatitude , #> # HmsLongitude , ZipCodes , SitingDesc ``` To get metadata for a subset of stations, simply pass a vector of station IDs. You can also query metadata for stations associated with a particular zipcode (or spatial zipcode) `cimis_zipcode()` and `cimis_spatial_zipcode()`: ```r cimis_zipcode() #> # A tibble: 1,471 x 5 #> StationNbr ZipCode ConnectDate DisconnectDate IsActive #> #> 1 99 90401 12/11/1992 5/8/2050 True #> 2 99 90402 12/11/1992 5/8/2050 True #> 3 99 90403 12/11/1992 5/8/2050 True #> 4 99 90404 12/11/1992 5/8/2050 True #> 5 99 90405 12/11/1992 5/8/2050 True #> 6 99 90406 12/11/1992 5/8/2050 True #> 7 99 90407 12/11/1992 5/8/2050 True #> 8 99 90408 12/11/1992 5/8/2050 True #> 9 99 90409 12/11/1992 5/8/2050 True #> 10 99 90410 12/11/1992 5/8/2050 True #> # ... with 1,461 more rows cimis_spatial_zipcode() #> # A tibble: 1,715 x 4 #> ZipCode ConnectDate DisconnectDate IsActive #> #> 1 85328 2/20/2003 12/31/2030 True #> 2 85334 2/20/2003 12/31/2030 True #> 3 85344 2/20/2003 12/31/2030 True #> 4 85364 2/20/2003 12/31/2030 True #> 5 85365 2/20/2003 12/31/2030 True #> 6 86440 2/20/2003 12/31/2030 True #> 7 89003 2/20/2003 12/31/2030 True #> 8 89010 2/20/2003 12/31/2030 True #> 9 89013 2/20/2003 12/31/2030 True #> 10 89019 2/20/2003 12/31/2030 True #> # ... with 1,705 more rows ``` Once the stations or regions of interest are identified, you can retrieve data using `cimis_data()`: ```r cimis_data(targets = 170, start.date = "2018-09-25", end.date = "2018-10-01") #> # A tibble: 98 x 13 #> Name Type Owner Date Julian Station Standard ZipCodes Scope Item #> #> 1 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayA~ #> 2 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayA~ #> 3 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayA~ #> 4 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayD~ #> 5 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayA~ #> 6 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayP~ #> 7 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayR~ #> 8 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayR~ #> 9 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayR~ #> 10 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily DayS~ #> # ... with 88 more rows, and 3 more variables: Value , Qc , #> # Unit ``` The data are returned in tidy format, i.e. the `"Value"` column displays the recorded value for the data item specified in the `"Item"` column. The CIMIS Web API returns a predefined set of data items by default, but custom item sets can also be passed to `cimis_data()`. Data queries also support zipcodes, spatial coordinates (latitude and longitude, in decimal degrees) and street addresses, as well as additional options for data units and data providers. See `?cimis_data` and the [CIMIS Web API documentation](http://et.water.ca.gov/Rest/Index) for more information. When hourly data is retrieved, an additional column `"Hour"` is returned. If both hourly and daily data items are requested, the `"Hour"` column will be filled with `NA` values for the daily data items. The `cimis_to_datetime()` function provides a quick way to combine the columns `"Date"` and `"Hour"` to a single `"Datetime"` column. Note that when mixed daily and hourly data is present in the dataframe, the daily values are assumed to correspond to midnight (00:00). ```r cimis_to_datetime(cimis_data(targets = 170, start.date = "2018-09-25", end.date = "2018-09-27", items = c("hly-soil-tmp", "day-air-tmp-avg"))) #> # A tibble: 75 x 13 #> Name Type Owner Datetime Julian Station Standard ZipCodes Scope #> #> 1 cimis stat~ wate~ 2018-09-25 00:00:00 268 170 english 94529, ~ daily #> 2 cimis stat~ wate~ 2018-09-26 00:00:00 269 170 english 94529, ~ daily #> 3 cimis stat~ wate~ 2018-09-27 00:00:00 270 170 english 94529, ~ daily #> 4 cimis stat~ wate~ 2018-09-25 01:00:00 268 170 english 94529, ~ hour~ #> 5 cimis stat~ wate~ 2018-09-25 02:00:00 268 170 english 94529, ~ hour~ #> 6 cimis stat~ wate~ 2018-09-25 03:00:00 268 170 english 94529, ~ hour~ #> 7 cimis stat~ wate~ 2018-09-25 04:00:00 268 170 english 94529, ~ hour~ #> 8 cimis stat~ wate~ 2018-09-25 05:00:00 268 170 english 94529, ~ hour~ #> 9 cimis stat~ wate~ 2018-09-25 06:00:00 268 170 english 94529, ~ hour~ #> 10 cimis stat~ wate~ 2018-09-25 07:00:00 268 170 english 94529, ~ hour~ #> # ... with 65 more rows, and 4 more variables: Item , Value , #> # Qc , Unit ``` CIMIS data sometimes includes quality control flags in the `Qc` column that indicate potential issues with returned data. Descriptions of these flags can be retrieved `cimis_flags()`: ```r cimis_flags() #> Flag Class Period #> 1 I Severe Current #> 2 M Severe Current #> 3 S Severe Current #> 4 A Informative Current #> 5 E Informative Current #> 6 T Informative Current #> 7 H Informative Current #> 8 J Informative Current #> 9 K Informative Current #> 10 L Informative Current #> 11 N Informative Current #> 12 P Informative Current #> 13 Q Informative Current #> 14 R Informative Current #> 15 Y Informative Current #> Description #> 1 Data value has no meaning/ignore. #> 2 Missing. #> 3 Sensor is not in service or data is out of sensor threshold. #> 4 Historical average. #> 5 Historical average of one of the sensors used to calculate a parameter. #> 6 Historical average of one of the sensors used to calculate a parameter. #> 7 Daily data value flagged when corresponding hourly data is flagged M, Q, and S. This flag is not set when the corresponding hourly data is flagged N. #> 8 Monthly data value flagged when some daily data are missing. #> 9 Monthly data value flagged when daily data values are flagged. #> 10 Monthly data value flagged when some daily data are missing and some are flagged. #> 11 Data value is not collected by this station. #> 12 Quality test pending. #> 13 All quality control could not be performed because a comparison sensor is severe. This flag is not set when the comparison sensor is flagged N. #> 14 Data is far out of historical limits. #> 15 Data is moderately out of historical limits. ``` Note that quality control flag designations were changed in 1993. For more information, see the [CIMIS Data Overview - Quality Control](https://cimis.water.ca.gov/Resources.aspx). web page.