DTSg (version 2.0.0)

aggregate.DTSg: Aggregate values

Description

Applies a temporal aggregation level function to the .dateTime column of a DTSg object and aggregates its values column-wise to the function's temporal aggregation level utilising one or more provided summary functions. Additionally, it sets the object's aggregated field to TRUE.

Usage

# S3 method for DTSg
aggregate(
  x,
  funby,
  fun,
  ...,
  cols = self$cols(class = "numeric"),
  n = FALSE,
  ignoreDST = FALSE,
  multiplier = 1L,
  funbyHelpers = NULL,
  funbyApproach = self$funbyApproach,
  clone = getOption("DTSgClone")
)

Value

Returns an aggregated DTSg object.

Arguments

x

A DTSg object (S3 method only).

funby

One of the temporal aggregation level functions described in TALFs or a user defined temporal aggregation level function. See corresponding section for further information.

fun

A summary function, (named) list of summary functions or (named) character vector specifying summary functions applied column-wise to all the values of the same temporal aggregation level. The return value(s) must be of length one. See corresponding section for further information.

...

Further arguments passed on to fun.

cols

A character vector specifying the columns to aggregate. Another possibility is a character string containing either comma separated column names, for example, "x,y,z", or the start and end column separated by a colon, for example, "x:z".

n

A logical specifying if a column named .n giving the number of values per temporal aggregation level shall be added. See corresponding section for further information.

ignoreDST

A logical specifying if day saving time shall be ignored by funby. See corresponding section for further information.

multiplier

A positive integerish value “multiplying” the temporal aggregation level of certain TALFs. See corresponding section for further information.

funbyHelpers

An optional list with helper data passed on to funby. See corresponding section for further information.

funbyApproach

A character string specifying the flavour of the applied temporal aggregation level function. Either "timechange", which utilises timechange::time_floor, or "base", which utilises as.POSIXct, or "fasttime", which utilises fasttime::fastPOSIXct, or "RcppCCTZ", which utilises RcppCCTZ::parseDatetime as the main function for transforming timestamps.

clone

A logical specifying if the object shall be modified in place or if a deep clone (copy) shall be made beforehand.

User defined TALFs, TALFs helper data and multiplier

User defined temporal aggregation level functions have to return a POSIXct vector of the same length as the time series and accept two arguments: a POSIXct vector as its first and a list with helper data as its second. The default elements of this list are as follows:

• timezone: Same as the timezone field.

• ignoreDST: Same as the ignoreDST argument.

• periodicity: Same as the periodicity field.

• na.status: Same as the na.status field.

• multiplier: Same as the multiplier argument.

• funbyApproach: Same as the funbyApproach argument.

Any additional element specified in the funbyHelpers argument is appended to the end of the default list. In case funbyHelpers contains an ignoreDST, multiplier or funbyApproach element, it takes precedence over the respective method argument. timezone, periodicity and na.status elements are rejected, as they are always taken directly from the object.

The temporal aggregation level of certain TALFs can be adjusted with the help of the multiplier argument. A multiplier of 10, for example, makes byY_____ aggregate to decades instead of years. Another example is a multiplier of 6 provided to by_m____. The function then aggregates all months of all first and all months of all second half years instead of all months of all years separately. This feature is supported by the following TALFs of the package:

• byY_____

• byYm____

• byYmdH__ (UTC and equivalent as well as all Etc/GMT time zones only)

• byYmdHM_

• byYmdHMS

• by_m____

• by___H__ (UTC and equivalent as well as all Etc/GMT time zones only)

• by____M_

• by_____S

Summary functions

Some examples for fun are as follows:

• mean

• list(min = min, max = max)

• c(sd = "sd", var = "var")

A list or character vector must have names in case more than one summary function is provided. The method can benefit from data.table's GForce optimisation in case a character vector specifying summary functions is provided.

Number of values per temporal aggregation level

Depending on the number of columns to aggregate, the .n column contains different counts:

• One column: The counts are calculated from the columns' values disregarding any missing values.

• More than one column: The counts are calculated from the .dateTime column including all missing values.

Ignore day saving time

ignoreDST tells a temporal aggregation level function if it is supposed to ignore day saving time while transforming the timestamps. This can be a desired feature for time series strictly following the position of the sun such as hydrological time series. Doing so ensures that diurnal variations are preserved by all means and all intervals are of the “correct” length, however, a possible limitation might be that the day saving time shift is invariably assumed to be one hour long. This feature requires that the periodicity of the time series has been recognised and is supported by the following TALFs of the package:

• byY_____

• byYQ____

• byYm____

• byYmd___

• by_Q____

• by_m____

• by___H__

See Also

cols, getOption

Examples

# new DTSg object
x <- DTSg$new(values = flow)

# mean yearly river flows
## R6 method
x$aggregate(
  funby = byY_____,
  fun = "mean",
  na.rm = TRUE
)$print()

## S3 method
print(aggregate(
  x = x,
  funby = byY_____,
  fun = "mean",
  na.rm = TRUE
))

# variance and standard deviation of river flows per quarter
## R6 method
x$aggregate(
  funby = byYQ____,
  fun = c(var = "var", sd = "sd"),
  na.rm = TRUE
)$print()

## S3 method
print(aggregate(
  x = x,
  funby = byYQ____,
  fun = c(var = "var", sd = "sd"),
  na.rm = TRUE
))

# mean of river flows of all first and all second half years
## R6 method
x$aggregate(
  funby = by_m____,
  fun = "mean",
  na.rm = TRUE,
  multiplier = 6
)$print()

## S3 method
print(aggregate(
  x = x,
  funby = by_m____,
  fun = "mean",
  na.rm = TRUE,
  multiplier = 6
))