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,
  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



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, window_width_n, window_width_frac, window_width_n_frac

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 smooth_data 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.


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