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)A data.frame in either timestamp format or doy format.
Character string, indicates the time zone in which the measurements have been recorded.
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).
Character string, indicates the format of the timestamp.
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).
Numeric, longitude in decimal degrees East to perform the solar time
conversion. Only required when solar.time=TRUE.
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).
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).
A zoo object or data.frame in the appropriate format for other functionalities.
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.
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)
}