lag_time: 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,
  blank = 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,
  warn_blank_length = TRUE
)

Value

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

Arguments

x

Vector of x values (typically time)

y

Vector of y values (typically density)

deriv

Vector of derivative values (typically per-capita derivative)

blank

y-value associated with a "blank" where the density is 0. Is required when trans_y = TRUE.

A vector of blank values may be specified only when all of slope, x1, y1, and y0 are provided as vectors

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.

warn_blank_length

logical whether warning should be issued when an unexpected number of blank values was provided and only the first will be used

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 of the tangent line (slope), origination point of the tangent line (x1, y1), or minimum y-value y0. If specified, these values 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.