Provided a vector of y values, this function returns either the plain or per-capita difference or derivative between sequential values
calc_deriv(
y,
x = NULL,
return = "derivative",
percapita = FALSE,
x_scale = 1,
blank = NULL,
subset_by = NULL,
window_width = NULL,
window_width_n = NULL,
window_width_frac = NULL,
window_width_n_frac = NULL,
trans_y = "linear",
na.rm = TRUE,
warn_ungrouped = TRUE,
warn_logtransform_warnings = TRUE,
warn_logtransform_infinite = TRUE,
warn_window_toosmall = TRUE
)A vector of values for the plain (if percapita = FALSE)
or per-capita (if percapita = TRUE) difference
(if return = "difference") or derivative
(if return = "derivative") between y values. Vector
will be the same length as y, with NA values
at the ends
Data to calculate difference or derivative of
Vector of x values provided as a simple numeric.
One of c("difference", "derivative") for whether the
differences in y should be returned, or the
derivative of y with respect to x
When percapita = TRUE, the per-capita difference or derivative is returned
Numeric to scale x by in derivative calculation
Set x_scale to the ratio of the units of
x to the desired units. E.g. if x is in seconds, but the
desired derivative is in units of /minute, set
x_scale = 60 (since there are 60 seconds in 1 minute).
y-value associated with a "blank" where the density is 0.
Is required when percapita = TRUE.
If a vector of blank values is specified, blank values are assumed to be in the same order as unique(subset_by)
An optional vector as long as y.
y will be split by the unique values of this vector
and the derivative for each group will be calculated
independently of the others.
This provides an internally-implemented approach similar to group_by and mutate
Set how many data points are used to determine the slope at each point.
When all are NULL, calc_deriv
calculates the difference or derivative
of each point with the next point, appending
NA at the end.
When one or multiple are specified, a linear regression is fit to all points in the window to determine the slope.
window_width_n specifies the width of the
window in number of data points. window_width
specifies the width of the window in units of x.
window_width_n_frac specifies the width of the
window as a fraction of the total number of data points.
When using multiple window specifications at the same
time, windows are conservative. Points
included in each window will meet all of the
window_width, window_width_n, and
window_width_n_frac.
A value of window_width_n = 3 or
window_width_n = 5 is often a good default.
One of c("linear", "log") specifying the
transformation of y-values.
'log' is only available when calculating per-capita
derivatives using a fitting approach (when non-default
values are specified for window_width or
window_width_n).
For per-capita growth expected to be exponential or
nearly-exponential, "log" is recommended, since
exponential growth is linear when log-transformed. However,
log-transformations must be used with care, since y-values
at or below 0 will become undefined and results will be
more sensitive to incorrect values of blank.
logical whether NA's should be removed before analyzing
logical whether warning should be issued when
calc_deriv is being called on ungrouped data
and subset_by = NULL.
logical whether warning should be issued when log(y) produced warnings.
logical whether warning should be issued
when log(y) produced infinite values that will
be treated as NA.
logical whether warning should be issued
when only one data point is in the window
set by window_width_n,
window_width, or window_width_n_frac,
and so NA will be returned.
For per-capita derivatives, trans_y = 'linear' and
trans_y = 'log' approach the same value as time resolution
increases.
For instance, let's assume exponential growth \(N = e^rt\) with per-capita growth rate \(r\).
With trans_y = 'linear', note that \(dN/dt = r e^rt = r N\).
So we can calculate per-capita growth rate as \(r = dN/dt * 1/N\).
With trans_y = 'log', note that \(log(N) = log(e^rt) = rt\).
So we can calculate per-capita growth rate as the slope of a linear
fit of \(log(N)\) against time, \(r = log(N)/t\).