okmesonet (version 0.1.5)

okmts: Retrieve Oklahoma Mesonet climatological data

Description

Retrieve Oklahoma Mesonet time series (MTS) data for a given time period and station. Alternatively, if station is omitted and latitude and longitude are given, retrieve MTS data for the closest operating station during the given time period.

Usage

okmts(begintime, endtime, station = NULL, lat = NULL, lon = NULL, variables = "ALL", localtime = TRUE, missingNA = TRUE, mcores = FALSE)

Arguments

begintime

character string or POSIXct object. Start time of time period. Character strings must be formatted as 'YYYY-MM-DD HH:MM:SS'.

endtime

character string or POSIXct object. End time of time period. Character strings must be formatted as 'YYYY-MM-DD HH:MM:SS'.

station

character string. Four letter Mesonet station identifier. See 'Details'.

lat

numeric. latitude of point of interest in decimal degrees.

lon

numeric. longitude of point of interest in decimal degrees.

variables

character string. Mesonet variables to retrieve. See 'Details'.

localtime

logical; if TRUE, input and output time is local to Oklahoma. If FALSE, input and output time is Coordinated Universal Time (UTC or GMT). See 'Details'.

missingNA

logical; if TRUE, missing values are replaced with NA. See 'Details'.

mcores

integer or logical; use n cores for file retrieval. See 'Details'.

Value

A data frame with values from MTS files for the given station, time period, and desired variables. Time values for each measurement are returned as POSIXct class; time zone is determined by localtime.

Details

The Oklahoma Mesonet is a network of automated climate monitoring stations throughout Oklahoma, USA. Data collection began January 01, 1994; as of November 2014, there are 120 active stations. Measurements are recorded every five minutes and sent to a central facility for verification and quality control by the Oklahoma Climatological Survey.

Data access may be restricted by organization and/or location. Please refer to and follow policies found within the Oklahoma Mesonet Data Access Policy. The authors and maintainers of okmesonet assume no responsibility for the use or misuse of okmesonet.

The objects used to define the time period for okmts can be either character strings or POSIXct objects. Character strings should be in the format "2009-09-08 09:05" or "2005-12-13 00:00:00". POSIXct objects need to have a time zone specified; okmts converts time zones appropriately to download correct MTS data.

Four letter Mesonet station identifier can be found in okstations or on the Oklahoma Mesonet website.

Available Mesonet variables and units are described in the MDF/MTS Files webpage, 'Parameter Description' readme file, or MTS specification. Multiple variables can be retrieved by combining values into a vector, e.g. c("TAIR", "RELH"). "ALL" indicates all available variables.

Time records of Oklahoma MTS data are stored in Coordinated Universal Time (UTC or GMT). To easily convert to local Oklahoma time, localtime=TRUE indicates that times used to define the time period (begintime and endtime) are local Oklahoma time. Time zone conversion is done internally, and accounts for Daylight Savings Time (as reliably as R can; see timezone). localtime=TRUE will also direct okmts to output in local Oklahoma time. localtime=FALSE indicates that UTC is used for both begintime and endtime; output is also UTC. If time inputs are of POSIXct class, localtime only affects time output.

Missing values are stored as negative integer codes and can be converted to NA with the missingNA parameter. Missing value descriptions can be found in the MDF/MTS Files webpage.

The use of multiple cores can speed up data retrieval for lengthy time periods. mcores specifies the number of cores to be used. mcores=TRUE will direct okmts to use the number cores less one in the current machine (determined by detectCores-1).

To prevent repeated retrieval of frequently used data, the data frame returned by okmts can be saved (e.g. save) or written to a file (e.g. write.table).

See Also

avgokmts to summarize MTS data.

Examples

## Not run: 
# ## Retrieve Bessie station MTS files for 00:00 Jun 01, 1997
# ## through 23:55 Oct 31, 1997
# bess.mts <- okmts(begintime="1997-06-01 00:00:00",
#  endtime="1997-10-31 23:55", station="bess")
# 
# ## Use POSIXct class to retrieve Medicine Park station air
# ## temperature for 09:30 through 20:30 Aug 12, 2004
# ## Set times, using 'America/Chicago' for Oklahoma time zone
# medi.time <- c(as.POSIXct("2004-08-12 09:30", tz="America/Chicago"),
#  as.POSIXct("2004-08-12 20:30", tz="America/Chicago"))
# medi.mts <- okmts(begintime=medi.time[1], endtime=medi.time[2],
#  station="medi", variables=c("TAIR", "RELH"))
# 
# ## Download all data for 2001 for station closest to
# ## 36.575284 latitude, -99.478455 longitude, using multiple cores
# stn.mts <- okmts(begintime="2001-01-01 00:00:00",
#  endtime="2001-12-31 23:55:00", lat=36.575284, lon=-99.478455, mcores=T)
# 
# ## Retrieve Idabel station MTS data for 00:00 through 12:00 UTC (GMT)
# ## Nov 23, 2003
# ## Time values are returned in UTC
# idab.mts <- okmts(begintime="2003-11-23 00:00:00",
#  endtime="2003-11-23 12:00:00", station="idab", localtime=F)
# 
# ## Combine air temperature with bison movement data.
# ## Retrieve Foraker station MTS files for 00:00 Jan 31, 2011
# ## through 15:00 Feb 05, 2011
# fora.mts <- okmts(begintime="2011-01-31 00:00:00",
#  endtime="2011-02-05 15:00:00", station="fora")
# ## Round bison timestamp down to five minute mark
# bison$newtime <- round(bison$timestamp, "min")
# bison$newtime$min <- as.integer(format(bison$newtime, "%M")) %/% 5 * 5
# bison$newtime <- as.POSIXct(bison$newtime)
# ## Add Foraker station air temperature to bison data
# bison$TAIR <- fora.mts$TAIR[match(bison$newtime, fora.mts$TIME)]
# ## End(Not run)