t_running_sum {fromo} | R Documentation |
Compute sums or means over a sliding time window.
Description
Compute the mean or sum over an infinite or finite sliding time window, returning a vector the same size as the lookback times.
Usage
t_running_sum(v, time = NULL, time_deltas = NULL, window = NULL,
wts = NULL, lb_time = NULL, na_rm = FALSE, min_df = 0L,
restart_period = 10000L, variable_win = FALSE, wts_as_delta = TRUE,
check_wts = FALSE)
t_running_mean(v, time = NULL, time_deltas = NULL, window = NULL,
wts = NULL, lb_time = NULL, na_rm = FALSE, min_df = 0L,
restart_period = 10000L, variable_win = FALSE, wts_as_delta = TRUE,
check_wts = FALSE)
Arguments
v |
a vector. |
time |
an optional vector of the timestamps of |
time_deltas |
an optional vector of the deltas of timestamps. If given, must be
the same length as |
window |
the window size, in time units. if given as finite integer or double, passed through.
If |
wts |
an optional vector of weights. Weights are ‘replication’
weights, meaning a value of 2 is shorthand for having two observations
with the corresponding |
lb_time |
a vector of the times from which lookback will be performed. The output should
be the same size as this vector. If not given, defaults to |
na_rm |
whether to remove NA, false by default. |
min_df |
the minimum df to return a value, otherwise |
restart_period |
the recompute period. because subtraction of elements can cause loss of precision, the computation of moments is restarted periodically based on this parameter. Larger values mean fewer restarts and faster, though potentially less accurate results. Unlike in the computation of even order moments, loss of precision is unlikely to be disastrous, so the default value is rather large. |
variable_win |
if true, and the |
wts_as_delta |
if true and the |
check_wts |
a boolean for whether the code shall check for negative weights, and throw an error when they are found. Default false for speed. |
Details
Computes the mean or sum of the elements, using a Kahan's Compensated Summation Algorithm, a numerically robust one-pass method.
Given the length n
vector x
, we output matrix M
where
M_{i,1}
is the sum or mean
of some elements x_i
defined by the sliding time window.
Barring NA
or NaN
, this is over a window of time width window
.
Value
A vector the same size as the lookback times.
Time Windowing
This function supports time (or other counter) based running computation.
Here the input are the data x_i
, and optional weights vectors, w_i
, defaulting to 1,
and a vector of time indices, t_i
of the same length as x
. The
times must be non-decreasing:
t_1 \le t_2 \le \ldots
It is assumed that t_0 = -\infty
.
The window, W
is now a time-based window.
An optional set of lookback times are also given, b_j
, which
may have different length than the x
and w
.
The output will correspond to the lookback times, and should be the same
length. The j
th output is computed over indices i
such that
b_j - W < t_i \le b_j.
For comparison functions (like Z-score, rescaling, centering), which compare
values of x_i
to local moments, the lookbacks may not be given, but
a lookahead L
is admitted. In this case, the j
th output is computed over
indices i
such that
t_j - W + L < t_i \le t_j + L.
If the times are not given, ‘deltas’ may be given instead. If
\delta_i
are the deltas, then we compute the times as
t_i = \sum_{1 \le j \le i} \delta_j.
The deltas must be the same length as x
.
If times and deltas are not given, but weights are given and the ‘weights as deltas’
flag is set true, then the weights are used as the deltas.
Some times it makes sense to have the computational window be the space
between lookback times. That is, the j
th output is to be
computed over indices i
such that
b_{j-1} - W < t_i \le b_j.
This can be achieved by setting the ‘variable window’ flag true and setting the window to null. This will not make much sense if the lookback times are equal to the times, since each moment computation is over a set of a single index, and most moments are underdefined.
Note
The moment computations provided by fromo are numerically robust, but will often not provide the same results as the 'standard' implementations, due to differences in roundoff. We make every attempt to balance speed and robustness. User assumes all risk from using the fromo package.
Note that when weights are given, they are treated as replication weights.
This can have subtle effects on computations which require minimum
degrees of freedom, since the sum of weights will be compared to
that minimum, not the number of data points. Weight values
(much) less than 1 can cause computations to return NA
somewhat unexpectedly due to this condition, while values greater
than one might cause the computation to spuriously return a value
with little precision.
Author(s)
Steven E. Pav shabbychef@gmail.com
References
Terriberry, T. "Computing Higher-Order Moments Online." http://people.xiph.org/~tterribe/notes/homs.html
J. Bennett, et. al., "Numerically Stable, Single-Pass, Parallel Statistics Algorithms," Proceedings of IEEE International Conference on Cluster Computing, 2009. https://www.semanticscholar.org/paper/Numerically-stable-single-pass-parallel-statistics-Bennett-Grout/a83ed72a5ba86622d5eb6395299b46d51c901265
Cook, J. D. "Accurately computing running variance." http://www.johndcook.com/standard_deviation.html
Cook, J. D. "Comparing three methods of computing standard deviation." http://www.johndcook.com/blog/2008/09/26/comparing-three-methods-of-computing-standard-deviation
Kahan, W. "Further remarks on reducing truncation errors," Communications of the ACM, 8 (1), 1965. https://doi.org/10.1145/363707.363723
Wikipedia contributors "Kahan summation algorithm," Wikipedia, The Free Encyclopedia, https://en.wikipedia.org/w/index.php?title=Kahan_summation_algorithm&oldid=777164752 (accessed May 31, 2017).
Examples
x <- rnorm(1e5)
xs <- t_running_sum(x,time=seq_along(x),window=10)
xm <- t_running_mean(x,time=cumsum(runif(length(x))),window=7.3)