This document gets you up and running with cimir, an R interface to the California Irrigiation Management Information System (CIMIS) Web API. In order to use this package, you will need to create a CIMIS account and request a web services AppKey.
First, simply load the cimir library:
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():
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():
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 WSNTo get a list of station IDs, use cimis_station():
cimis_station()
#> # A tibble: 1,473 x 15
#> StationNbr Name City RegionalOffice County ConnectDate DisconnectDate
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 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 <chr>,
#> # IsEtoStation <chr>, Elevation <chr>, GroundCover <chr>, HmsLatitude <chr>,
#> # HmsLongitude <chr>, ZipCodes <chr>, SitingDesc <chr>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():
cimis_zipcode()
#> # A tibble: 1,471 x 5
#> StationNbr ZipCode ConnectDate DisconnectDate IsActive
#> <int> <chr> <chr> <chr> <chr>
#> 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
#> <chr> <chr> <chr> <chr>
#> 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 rowsOnce the stations or regions of interest are identified, you can retrieve data using cimis_data():
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
#> <chr> <chr> <chr> <date> <int> <chr> <chr> <chr> <chr> <chr>
#> 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 <dbl>, Qc <chr>,
#> # Unit <chr>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 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).
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
#> <chr> <chr> <chr> <dttm> <int> <chr> <chr> <chr> <chr>
#> 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 <chr>, Value <dbl>,
#> # Qc <chr>, Unit <chr>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():
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. web page.