Quick Start

Michael Koohafkan

2021-02-17

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                   WSN

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

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