DTSg: DTSg class

In gisler/DTSg: A Class for Working with Time Series Data Based on 'data.table' and 'R6' with Largely Optional Reference Semantics

DTSg class

Description

The DTSg class is the working horse of the package. It is an R6::R6Class and offers an S3 interface in addition to its native R6 interface. In the usage sections of the documentation, unfortunately, only the usage of the S3 methods are displayed, however, the examples always show both ways of calling the respective method. Generally, they are very similar anyway. While the R6 interface always has the object first and the method is then selected with the help of the $ operator, for instance, x$cols(), the S3 interface always has the method first and then the object as its first argument, for instance, cols(x). An exception is the new method. It is not an S3 method, but an abused S4 constructor with the character string "DTSg" as its first argument. Regarding the R6 interface, the DTSg class generator has to be used to access the new method with the help of the $ operator.

Usage

new(Class, values, ID = "", parameter = "", unit = "", variant = "",
  aggregated = FALSE, fast = getOption("DTSgFast"), swallow = FALSE,
  na.status = getOption("DTSgNA.status"), funbyApproach =
  getOption("DTSgFunbyApproach"))

Arguments

Class	A character string. Must be "DTSg" in order to create a DTSg object. Otherwise a different object may or may not be created (S4 constructor only).
values	A data.frame or object inherited from class data.frame, e.g. data.table::data.table. Its first column must be of class POSIXct or coercible to it. It serves as the object's time index and is renamed to .dateTime.
ID	A character string specifying the ID (name) of the time series data object.
parameter	A character string specifying the parameter name of the time series data.
unit	A character string specifying the unit of the time series data.
variant	A character string specifying further metadata of the time series, for instance, "min" to point out that it is a time series of lower bound measurements.
aggregated	A logical specifying how the timestamps of the series have to be interpreted: as snap-shots (FALSE) or as periods between subsequent timestamps (TRUE).
fast	A logical specifying if all rows (FALSE) or only the first 1000 rows (TRUE) shall be used to check the object's integrity and for the automatic detection of the time series' periodicity.
swallow	A logical specifying if the object provided through the values argument shall be “swallowed” by the DTSg object, i.e. no copy of the data shall be made. This is generally more resource efficient, but only works when the provided object is a data.table::data.table. Be warned, however, that when the creation of the DTSg object fails for some reason, the first column of the provided data.table::data.table might have been coerced to POSIXct and keyed (see data.table::setkey for further information). Furthermore, all references to the “swallowed” data.table::data.table in the global (and only the global) environment are removed upon the successful creation of the DTSg object.
na.status	A character string. Either "explicit", which makes missing timestamps explicit according to the recognised periodicity, or "implicit", which removes timestamps with missing values on all value columns, or "undecided" for no such action. Please note that DTSg objects work best with explicitly missing values.
funbyApproach	A character string specifying the default flavour of TALFs used with the created DTSg object. Either "base", which utilises as.POSIXct, or "fasttime", which utilises fasttime::fastPOSIXct, or "RcppCCTZ", which utilises RcppCCTZ::parseDatetime as the main function for transforming timestamps. Custom approaches for user defined temporal aggregation level functions are also possible.

Value

Returns a DTSg object.

Methods

A DTSg object has the following methods:

• aggregate: See aggregate for further information.

• alter: See alter for further information.

• clone: See clone for further information.

• colapply: See colapply for further information.

• cols: See cols for further information.

• getCol: See getCol for further information.

• merge: See merge for further information.

• nas: See nas for further information.

• plot: See plot for further information.

• print: See print for further information.

• refresh: See refresh for further information.

• rollapply: See rollapply for further information.

• rowaggregate: See rowaggregate for further information.

• rowbind: See rowbind for further information.

• setColNames: See setColNames for further information.

• setCols: See setCols for further information.

• subset: See subset for further information.

• summary: See summary for further information.

• values: See values for further information.

Fields

A DTSg object has the following fields or properties as they are often called. They are implemented through so called active bindings, which means that they can be accessed and actively set with the help of the $ operator, for instance, x$ID gets the value of the ID field and x$ID <- "River Flow" sets its value. Please note that fields are always modified in place, i.e. no deep clone (copy) of the object is made beforehand. See clone for further information. Some of the fields are read-only though:

• aggregated: Same as the aggregated argument.

• fast: Same as the fast argument.

• funbyApproach: Same as the funbyApproach argument.

• ID: Same as the ID argument. It is used as the title of plots.

• na.status: Same as the na.status argument. When set, the missing values of the object are expanded or collapsed accordingly.

• parameter: Same as the parameter argument. It is used as the label of the primary axis of plots.

• periodicity: A difftime object for a regular and a character string for an irregular DTSg object describing its periodicity or containing "unrecognised" in case it could not be detected. When set, the periodicity of the time series is changed as specified. See the by argument of alter for further information.

• regular: A logical signalling if all lags in seconds between subsequent timestamps are the same (TRUE) or if some are different (FALSE). A, for instance, monthly time series is considered irregular in this sense (read-only).

• timestamps: An integer showing the total number of timestamps of the time series (read-only).

• timezone: A character string showing the time zone of the time series. When set, the series is converted to the specified time zone. Only names from OlsonNames are accepted.

• unit: Same as the unit argument. It is added to the label of the primary axis of plots when the parameter field is set.

• variant: Same as the variant argument. It is added to the label of the primary axis of plots when the parameter field is set.

The parameter, unit and variant fields are especially useful for time series of a single variable. For time series of multiple variables with differing units the functionality of the units package may pose a viable alternative.

Options

The behaviour of DTSg objects can be customised with the help of the following option. See options for further information:

• DTSgClone: A logical specifying if DTSg objects are, by default, modified in place (FALSE) or if a deep clone (copy) shall be made beforehand (TRUE).

• DTSgDeprecatedWarnings: A logical specifying if warnings are displayed when calling deprecated features.

• DTSgFast: Default value for the fast argument.

• DTSgFunbyApproach: Default value for the funbyApproach argument.

• DTSgNA.status: Default value for the na.status argument.

Note

Due to the POSIXct nature of the .dateTime column, the same sub-second accuracy, issues and limitations apply to DTSg objects. In order to prevent at least some of the possible precision issues, the lags between subsequent timestamps are rounded to microseconds during integrity checks. This corresponds to the maximum value allowed for options("digits.secs"). As a consequence, time series with a sub-second accuracy higher than a microsecond will never work.

Examples

# new DTSg object
## R6 constructor
DTSg$new(
  values = flow,
  ID = "River Flow"
)

## abused S4 constructor
new(
  Class = "DTSg",
  values = flow,
  ID = "River Flow"
)

gisler/DTSg documentation built on Dec. 12, 2024, 1:23 a.m.