Tests if the structure of the input matches the requirements of TREX functions and specifies the time zone. The input has to be presented in one of two different data.frame formats. i) Timestamp format: including a 1) timestamp of the measurements column (character), and 2) value of \(\Delta V\) (or \(\Delta T\); [as.numeric]). ii) DOY format: including a 1) year of measurements column as.integer, 2) day of the year (DOY) of measurement (as.integer), 3) hour of the measurement (character), and 4) value of \(\Delta V\) (or \(\Delta T\); [as.numeric]). TREX functions are applied on time series obtained from a set of thermal dissipation probes. This includes the option where the thermal dissipation method (TDM) is used with only a reference and heating probe, or when including addition reference probes (see ref.add). These reference probe measurements can be added to the DOY or timestamp format in \(\Delta V\) (or \(\Delta T\)) (as.numeric) labelled ref1, ref2, etc. (depending on the number of reference probes). For this function the following column names have to be present within the data.frame: "timestamp" or "year" & "doy" & "hour" = indicators of time and "value" = TDM measurements (option "ref1", "ref2, ..., refn = reference probes). After specifying the time zone (tz), one can select whether to standardize the temporal series to solar time (see solar.time) by providing the longitude in decimal degrees at which the measurements were obtained (in long.deg). All timestamps within the function are rounded to minute resolution and output can be either provided in a zoo format (df = FALSE) or data.frame (df = TRUE; default is FALSE). Note, that the output time series is always given in UTC time zone.

is.trex(data, tz = 'UTC', tz.force = FALSE, time.format = '%m/%d/%y %H:%M:%S',
  solar.time = TRUE, long.deg = 7.7459,
   ref.add = FALSE, df = FALSE)

Arguments

data

A data.frame in either timestamp format or doy format.

tz

Character string, indicates the time zone in which the measurements have been recorded.

tz.force

Logical; if TRUE, the time zone is forced to "UTC" or re-labelled yet not shifted in time. "UTC" is required for internal processing (default = FALSE).

time.format

Character string, indicates the format of the timestamp.

solar.time

Logical; if TRUE, time is converted to solar time, depending upon the location where the measurements have been taken. If FALSE, the output is provided in "UTC" (default = FALSE).

long.deg

Numeric, longitude in decimal degrees East to perform the solar time conversion. Only required when solar.time=TRUE.

ref.add

Logical; if TRUE, additional probes provided within data are considered. The \(\Delta T\) values are then corrected by subtracting the \(\Delta T\) measured between the reference probes from the \(\Delta T\) measured between the heated and unheated probe (default = FALSE).

df

Logical; if TRUE, output is provided in a data.frame format with a timestamp and a value (\(\Delta T\) or \(\Delta V\)) column. If FALSE, output is provided as a zoo object (default = FALSE).

Value

A zoo object or data.frame in the appropriate format for other functionalities.

Details

To prevent errors occurring in subsequent TREX functions, it is advised to run this function for checking the data structure and preparing it for further analyses. For the specific time zone see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones or for formatting see OlsonNames(). The format of the timestamp has to be provided according to https://www.stat.berkeley.edu/~s133/dates.html. For the method behind the solar time conversion, see the solar package (https://CRAN.R-project.org/package=solaR). The longitude has to be provided in positive decimal degrees for study sites East from the Greenwich meridian and negative for sites to the West.

Examples

if (FALSE) {
#validating and structuring example data
raw   <- example.data(type="doy")
input <- is.trex(raw,tz="GMT",time.format="%H:%M",
    solar.time=TRUE,long.deg=7.7459,
    ref.add=FALSE,df=FALSE)
head(raw)
str(input)
head(input)
plot(input)
}