Quick Start

Michael Koohafkan

2019-03-18

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()
#>                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       WSN

To 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 rows

Once 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. 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
#>    <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>