The runner package

Dawid Kałędkowski

2019-12-09

About

Package contains running functions (rolling or sliding window) with additional options. runner provides extended functionality like varying windows size, windows dependent on date, handling missing value. runner brings also other utility functions like filling missing values, rolling streak and rolling which.

Installation

Install package from from GitHub or from CRAN.

# devtools::install_github("gogonzo/runner")
install.packages("runner")

Running windows

runner functionality revolves around time series and running windows. Diagram below illustrates what running windows are - in this case running k = 4 windows. For each of 15 elements of a vector each window contains current 4 elements.

Windows are defined by several parameters, like size, lag and indexes of observation (or date).

Window size

k denotes number of elements in window. If k is a single value then window size is constant for all elements of x. For varying window size one should specify k as integer vector of length(k) == length(x) where each element of k defines window length. If k is empty it means that window will be cumulative (like base::cumsum). Example below illustrates window of k = 4 for 10’th element of vector x.

Window lag

lag denotes how many observations windows will be lagged by. If lag is a single value than it’s constant for all elements of x. For varying lag size one should specify lag as integer vector of length(lag) == length(x) where each element of lag defines lag of window. Default value of lag = 0. Example below illustrates window of k = 4 lagged by lag = 2 for 10’th element of vector x. Lag can also be negative value, which shifts window forward instead of backward.

Windows depending on date

Sometimes data points in dataset are not equally spaced (missing weekends, holidays, other missings) and thus window size should vary to keep expected time frame. If one specifies idx argument, than running functions are applied on windows depending on date. idx should be the same length as x of class Date or integer. Including idx can be combined with varying window size, than k will denote number of periods in window different for each data point. Example below illustrates window of size k = 5 lagged by lag = 2. In parentheses ranges for each window.

NA padding

Using runner one can also specify na_pad = TRUE which would return NA for any window which is partially out of range - meaning that there is no sufficient number of observations to fill the window. By default na_pad = FALSE, which means that incomplete windows are calculated anyway. na_pad is applied on normal cumulative windows and on windows depending on date.

Using package

Any R function with runner

Package contains most fundamental function runner::runner which gives possibility to apply any R function f on running window. runner::runner serve as sapply on running windows. Only x value needs to be specified while k, lag and idx are optional.

Below example of using base::mean inside of the runner function.

library(runner)
x <- runif(15)
k <- sample(1:15, 15, replace = TRUE)
idx <- cumsum(sample(c(1, 2, 3, 4), 15, replace = TRUE))

# simple call
simple_mean <- runner(x = x, k = 4, f = mean)

# additional arguments for mean
trimmed_mean <- runner(x = x, k = 4, f = function(x) mean(x, trim = 0.05))

# varying window size
varying_window <- runner(x = x, k = k, f = function(x) mean(x, trim = 0.05))

# windows depending on date
date_windows <- runner(x = x, k = k, idx = idx, f = function(x) mean(x, trim = 0.05))

data.frame(x, k, idx, simple_mean, trimmed_mean, varying_window, date_windows)
##            x  k idx simple_mean trimmed_mean varying_window date_windows
## 1  0.5187593 11   2   0.5187593    0.5187593      0.5187593    0.5187593
## 2  0.8779030 14   3   0.6983311    0.6983311      0.6983311    0.6983311
## 3  0.8291403 12   4   0.7419342    0.7419342      0.7419342    0.7419342
## 4  0.5064969  9   8   0.6830748    0.6830748      0.6830748    0.6830748
## 5  0.4876408  3   9   0.6752952    0.6752952      0.6077593    0.4970688
## 6  0.4841933 12  12   0.5768678    0.5768678      0.6173556    0.6173556
## 7  0.6139901 14  15   0.5230803    0.5230803      0.6168748    0.6168748
## 8  0.1275693  6  19   0.4283484    0.4283484      0.5081718    0.3707797
## 9  0.7638903  4  22   0.4974108    0.4974108      0.4974108    0.4457298
## 10 0.3246819  4  25   0.4575329    0.4575329      0.4575329    0.5442861
## 11 0.9386148 14  27   0.5386891    0.5386891      0.5884436    0.5537493
## 12 0.8685000 13  30   0.7239218    0.7239218      0.6117817    0.6046513
## 13 0.1299957  8  33   0.5654481    0.5654481      0.5314294    0.6457035
## 14 0.9807301 15  37   0.7294602    0.7294602      0.6037218    0.6485045
## 15 0.9519282  7  40   0.7327885    0.7327885      0.7083344    0.9663292

builtin functions

With runner one can use any R functions, but some of them are optimized for speed reasons. These functions are:
- aggregating functions - length_run, min_run, max_run, minmax_run, sum_run, mean_run, streak_run
- utility functions - fill_run, lag_run, which_run

More details about using built-in functions.