Skip to contents

Provided a vector of y values, this function returns either the plain or per-capita difference or derivative between sequential values


  x = NULL,
  return = "derivative",
  percapita = FALSE,
  x_scale = 1,
  blank = NULL,
  subset_by = NULL,
  window_width = NULL,
  window_width_n = NULL,
  trans_y = "linear",
  na.rm = TRUE



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 dplyr::group_by and dplyr::mutate

window_width_n, window_width

Set how many data points are used to determine the slope at each point.

When both are NULL, calc_deriv calculates the difference or derivative of each point with the next point, appending NA at the end.

When one or both 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.

When using window_width and window_width_n at the same time, windows are conservative. Points included in each window will meet both the window_width and the window_width_n.

A value of window_width_n = 3 or window_width_n = 5 is often the most effective.


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


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


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\).