In mkoohafkan/cimir: Interface to the CIMIS Web API

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.

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  echo = TRUE
)

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

To get a list of station IDs, use cimis_station():

cimis_station()

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()
cimis_spatial_zipcode()

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")

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")))

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():