Author: Michael Koohafkan
Date: 2021-02-17

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