hsGroupByInterval: Group Data in Time Intervals

In KWB-R/kwb.base: Functions supporting data analysis with R at KWB

Group Data in Time Intervals

Description

Builds groups of rows belonging to the same time interval and aggregates the values within the group by using a given function (e.g. sum, mean, min, max)

Usage

hsGroupByInterval(
  data,
  interval,
  FUN,
  tsField = names(data)[1],
  offset1 = 0,
  offset2 = interval/2,
  limits = FALSE,
  ...,
  dbg = FALSE
)

Arguments

data	data frame containing a timestamp field and data fields to be aggregated over time.
interval	length of time interval in seconds
FUN	function used to aggregate the values within one and the same interval, e.g. sum, mean, min, max
tsField	name of timestamp column, default: name of first column
offset1	number of seconds by which all timestamps are shifted before they are grouped into intervals. The grouping to intervals is done by dividing the timestamps (converted to number of seconds since 1970-01-01) by the interval length and taking the integer part of the division as interval number. Thus, with offset1 = 0 and an interval length of e.g. 60 seconds, the first interval is from 00:00:00 to 00:00:59, the second from 00:01:00 to 00:01:59 etc., whereas offset1 = 30 in this case would lead to intervals 00:00:30 to 00:01:29, 00:01:30 to 00:02:29 etc..
offset2	value given in seconds determining which of the timestamps in an interval represents the interval in the output. If 0, each time interval is represented by the smallest timestamp belonging to the interval. By default, offset2 is half the interval length, meaning that each time interval is represented by the timestamp in the middle of the interval.
limits	if TRUE, two additional columns will be added showing the minimum and maximum value of the interval
...	further arguments passed to aggregate, the internally called function
dbg	if TRUE, debug messages are shown

Examples

## Get an example time-series with values every one minute
step <- 60
df <- hsExampleTSeries(step)

## Calculate 5-min-means with
## offset1 = 0 (default), offset2 = interval/2 (default)
df.agg1 <- hsGroupByInterval(df, interval = 5*step, mean, limits = TRUE)
df.agg1

## Shift the interval limits with
## offset1 = 2.5*60, offset2 = interval/2 (default)
df.agg2 <- hsGroupByInterval(df, interval = 5*step, mean, limits = TRUE,
                             offset1 = 2.5*step)
df.agg2

## Shift the timestamps representing the intervals with
## offset1 = 0, offset2 = 0
df.agg3 <- hsGroupByInterval(df, interval = 5*step, mean, limits = TRUE,
                             offset1 = 0, offset2 = 0)
df.agg3

## Show a plot demonstrating the effect of offset1 and offset2
## Not run: 
demoGroupByInterval(df)

## End(Not run)
## Handling NA values...

## Set y to NA at 2 random positions
df[sample(nrow(df), 2), 2] <- NA
df ## Let' have a look at df

## Count NA values per group
hsGroupByInterval(df, interval = 300, function(x){sum(is.na(x))})

## default behaviour: mean(values containing at least one NA) = NA
hsGroupByInterval(df, interval = 300, mean)

## ignore NA values by passing na.rm = TRUE to the aggregate function
hsGroupByInterval(df, interval = 300, mean, na.rm = TRUE)

KWB-R/kwb.base documentation built on June 19, 2022, 3:30 a.m.