lag_time {gcplyr}

Calculate lag time

Description

Lag time is calculated by projecting a tangent line at the point of maximum (per-capita) derivative backwards to find the time when it intersects with the minimum y-value

Usage

lag_time(
  x = NULL,
  y = NULL,
  deriv = NULL,
  trans_y = "log",
  na.rm = TRUE,
  slope = NULL,
  x1 = NULL,
  y1 = NULL,
  y0 = NULL,
  warn_logtransform_warnings = TRUE,
  warn_logtransform_infinite = TRUE,
  warn_min_y_mismatch = TRUE,
  warn_multiple_maxderiv = TRUE,
  warn_one_lag = TRUE,
  warn_no_lag = TRUE
)

Arguments

x

Vector of x values (typically time)

y

Vector of y values (typically density)

deriv

Vector of derivative values (typically per-capita derivative)

trans_y

One of c("linear", "log") specifying the transformation of y-values.

'log' is the default, producing calculations of lag time assuming a transition to exponential growth

'linear' is available for alternate uses

na.rm

a logical indicating whether missing values or values that become NA or infinite during log-transformation should be removed

slope

Slope to project from x1,y1 to y0 (typically per-capita growth rate). If not provided, will be calculated as max(deriv)

x1

x value (typically time) to project slope from. If not provided, will be calculated as x[which.max(deriv)].

y1

y value (typically density) to project slope from. If not provided, will be calculated as y[which.max(deriv)].

y0

y value (typically density) to find intersection of slope from x1, y1 with. If not provided, will be calculated as min(y)

warn_logtransform_warnings

logical whether warning should be issued when log(y) produced warnings.

warn_logtransform_infinite

logical whether warning should be issued when log(y) produced infinite values that will be treated as NA.

warn_min_y_mismatch

logical whether warning should be issued when min(y) does not equal min(y[!is.na(x)]).

warn_multiple_maxderiv

logical whether warning should be issued when there are multiple points in deriv that are tied for the highest, and only the first will be used.

warn_one_lag

logical whether warning should be issued when some, but not all, inputs are vectorized, and only one lag time value will be returned.

warn_no_lag

logical whether warning should be issued when calculated lag time is less than the minimum value of x

Details

For most typical uses, simply supply x, y, and deriv (using the per-capita derivative and trans_y = 'log').

Advanced users may wish to use alternate values for the slope, origination point, or minimum y-value. In that case, values can be supplied to slope, x1, y1, and/or y0, which will override the default calculations. If and only if all of slope, x1, y1, and y0 are provided, lag_time is vectorized on their inputs and will return a vector of lag time values.

Value

Typically a scalar of the lag time in units of x. See Details for cases when value will be a vector.