R: Horizontal asymptotes of rational functions

asymptote {SDLfilter}

R Documentation

Horizontal asymptotes of rational functions

Description

Function to find horizontal asymptotes of a rational function.

Usage

asymptote(
  data = NULL,
  x = NULL,
  y = NULL,
  degree = "optim",
  upper.degree = 5,
  d1 = NA,
  d2 = NA,
  threshold = 0.95,
  proportional = TRUE,
  max.asymptote = 1,
  estimator = "glm",
  ci.level = 0.95,
  ...
)

Arguments

`data`	An output object from `boot_overlap`, `combn_overlap`, or `boot_area`.
`x`, `y`	Numeric vectors of independent (x) and dependent (y) variables. These parameters will be ignored if data is supplied.
`degree`	The default 'optim' option selects the maximal degree of numerator and denominator of a rational function that minimises the mean squared error. Alternatively, an integer can be used to specify the maximal degree. The 'optim' option is recommended unless there is a strong reason that a maximal degree should be specified.
`upper.degree`	The upper limit of the maximal degree to be assessed when the 'optim' option is selected. Default is 5, meaning the "optimal" degree is searched from 1 and 10. The default usually gives good results. If the fit does not look good, a larger value may result in a better fit.
`d1`, `d2`	(Deprecated) Maximal degrees of numerator (d1) and denominator (d2) of a rational function. d1 and d2 must be equal. Use degree instead.
`threshold`	Threshold value for considering an asymptote. Once the y value reaches the threshold, it is considered that an asymptote is reached.
`proportional`	If TRUE (default), a threshold is calculated as estimated asymptote threshold. If FALSE, the value specified in threshold* is used in the analysis.
`max.asymptote`	The maximum limit of an expected asymptote. Default is 1 (i.e. maximum probability). If it is unknown, set as NA (e.g. max.asymptote = NA).
`estimator`	Method used to estimate the mean or predicted y relative to x (e.g. sample size). Available options are 'mean' using arithmetic means and 'glm' using the `glm` function.
`ci.level`	Confidence level for the mean or predicted y, which will be used to assess if/when an asymptote has been reached. If NULL, only the mean and predicted y are used for the assessment (see details).
`...`	Optional arguments passed to `glm`.

Details

This function fits a rational function to the input data. When an output object from boot_overlap, combn_overlap or boot_area is supplied, a rational function is fit to the means or predicted values of the bootstrap results (e.g. mean overlap probability) as a function of x (e.g. sample size). It then estimates horizontal asymptotes and identifies the sample size when an asymptote is considered. If ci.level = NULL and threshold = 0.95, an asymptote is considered when the mean or predicted y value reaches above 95 If ci.level is specified (e.g. 0.95) and threshold = 0.95, an asymptote is considered when the mean or predicted y value AND the confidence interval are above 95 When the "PHR" method was used in boot_overlap, binomial is generally a sensible family object for the GLM. gaussian and Gamma are often good options when the maximum y value exceeds 1 (e.g. area size). Please caution if estimated horizontal asymptote is very different from the expected asymptote. For example, the estimated horizontal asymptote should be around 1 when overlaps between UDs are calculated using the "PHR" method. see boot_overlap.

Value

A list containing a data frame (rational function fit associated with x values), an estimated horizontal asymptote, the minimum sample size if an asymptote is reached, and the estimated optimal degree of numerator and denominator of the rational function.

Author(s)

Takahiro Shimada

References

Shimada T, Thums M, Hamann M, Limpus CJ, Hays GC, FitzSimmons N, Wildermann NE, Duarte CD, Meekan MG (2021) Optimising sample sizes for animal distribution analysis using tracking data. Methods in Ecology and Evolution 12(2):288-297 doi:10.1111/2041-210X.13506

Press, W. H., S. A. Teukolsky, W. T. Vetterling, and B. P. Flannery (2007). Numerical Recipes: The Art of Numerical Computing. Third Edition, Cambridge University Press, New York.