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:
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():
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()
#> Item Name Class Provider
#> 1 day-air-tmp-avg Average Air Temperature Daily WSN
#> 2 day-air-tmp-avg Average Air Temperature Daily WSN
#> 3 day-air-tmp-min Minimum Air Temperature Daily WSN
#> 4 day-dew-pnt Dew Point Daily WSN
#> 5 day-eto CIMIS ETo Daily WSN
#> 6 day-asce-eto ASCE ETo Daily WSN & SCS
#> 7 day-asce-etr ASCE ETr Daily WSN
#> 8 day-precip Precipitation Daily WSN
#> 9 day-rel-hum-avg Average Relative Humidity Daily WSN
#> 10 day-rel-hum-max Maximum Relative Humidity Daily WSN
#> 11 day-rel-hum-min Minimum Relative Humidity Daily WSN
#> 12 day-soil-tmp-avg Average Soil Temperature Daily WSN
#> 13 day-soil-tmp-max Maximum Soil Temperature Daily WSN
#> 14 day-soil-tmp-min Minimum Soil Temperature Daily WSN
#> 15 day-sol-rad-avg Average Solar Radiation Daily WSN & SCS
#> 16 day-sol-rad-net Net Solar Radiation Daily WSN
#> 17 day-vap-pres-max Maximum Vapor Pressure Daily WSN
#> 18 day-vap-pres-avg Average Vapor Pressure Daily WSN
#> 19 day-wind-ene Wind East-North-East Daily WSN
#> 20 day-wind-ese Wind East-South-East Daily WSN
#> 21 day-wind-nne Wind North-North-East Daily WSN
#> 22 day-wind-nnw Wind North-North-West Daily WSN
#> 23 day-wind-run Wind Run Daily WSN
#> 24 day-wind-spd-avg Average Wind Speed Daily WSN
#> 25 day-wind-ssw Wind South-South-West Daily WSN
#> 26 day-wind-wnw Wind West-North-West Daily WSN
#> 27 day-wind-wsw Wind West-South-West Daily WSN
#> 28 hly-air-tmp Air Temperature Hourly WSN
#> 29 hly-dew-pnt Dew Point Hourly WSN
#> 30 hly-eto CIMIS ETo Hourly WSN
#> 31 hly-net-rad Net Radiation Hourly WSN
#> 32 hly-asce-eto ASCE ETo Hourly WSN
#> 33 hly-asce-etr ASCE ETr Hourly WSN
#> 34 hly-precip Precipitation Hourly WSN
#> 35 hly-rel-hum Relative Humidity Hourly WSN
#> 36 hly-res-wind Resultant Wind Hourly WSN
#> 37 hly-soil-tmp Soil Temperature Hourly WSN
#> 38 hly-sol-rad Solar Radiation Hourly WSN
#> 39 hly-vap-pres Vapor Pressure Hourly WSN
#> 40 hly-wind-dir Wind Direction Hourly WSN
#> 41 hly-wind-spd Wind Speed Hourly WSNTo get a list of station IDs, use cimis_station():
cimis_station()
#> # A tibble: 1,394 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,384 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,394 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,384 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 query_cimis():
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
#> <chr> <chr> <chr> <date> <int> <chr> <chr> <chr> <chr>
#> 1 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 2 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 3 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 4 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 5 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 6 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 7 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 8 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 9 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> 10 cimis stat~ wate~ 2018-09-25 268 170 english 94529, ~ daily
#> # ... with 88 more rows, and 4 more variables: Item <chr>, 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. 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
#> <chr> <chr> <chr> <dttm> <int> <chr> <chr> <chr>
#> 1 cimis stat~ wate~ 2018-09-25 00:00:00 268 170 english 94529, ~
#> 2 cimis stat~ wate~ 2018-09-26 00:00:00 269 170 english 94529, ~
#> 3 cimis stat~ wate~ 2018-09-27 00:00:00 270 170 english 94529, ~
#> 4 cimis stat~ wate~ 2018-09-25 01:00:00 268 170 english 94529, ~
#> 5 cimis stat~ wate~ 2018-09-25 02:00:00 268 170 english 94529, ~
#> 6 cimis stat~ wate~ 2018-09-25 03:00:00 268 170 english 94529, ~
#> 7 cimis stat~ wate~ 2018-09-25 04:00:00 268 170 english 94529, ~
#> 8 cimis stat~ wate~ 2018-09-25 05:00:00 268 170 english 94529, ~
#> 9 cimis stat~ wate~ 2018-09-25 06:00:00 268 170 english 94529, ~
#> 10 cimis stat~ wate~ 2018-09-25 07:00:00 268 170 english 94529, ~
#> # ... with 65 more rows, and 5 more variables: Scope <chr>, Item <chr>,
#> # Value <dbl>, Qc <chr>, Unit <chr>