phest: Calculate PHEnological ESTimates

Description Usage Arguments Details Note References Examples

weib.limit estimates either the the lower or upper limit of a distribution of numbers given it. This is used in the manuscript to calculate the onset of flowering given a set of flowering dates.

weib.limit(x, k = NULL, upper = FALSE, alpha = 0.05)

weib.limit.bootstrap(x, k = NULL, n = 1000, max.iter = 10,
  upper = FALSE)

`x`	vector of dates/times of observations, given as numbers
`k`	how many entries in 'x' will be used to calculate the estimate. See 'Methods' in Pearse et al. (2017) for an explanation of why not all numbers need be used in the estimate
`upper`	whether to calculate the upper limit (if TRUE) or the lower limit (if FALSE, the default). In the context of plant flowering phenology, the default option calculates when flowering started (the focus of this manuscript)
`alpha`	the alpha value for the confidence intervals for the estimate of the limit of the distribution
`n`	how many times to run the bootstrapping
`max.iter`	it is not always possible to calculate an estimate for the limit (see Methods), and this means it is sometimes not possible to calculate an estimate across all bootstraps. If such a case occurs, this parameter sets how many times the function will try the bootstrapping again until the problem doesn't occur.

weib.se.bootstrap bootstraps an estimate of the Standard Error for a particular estimate of the limit of a distribution. As discussed in the Methods section of the manuscript, care should be taken when bootstrapping estimates: the confidence intervals of these estimates are asymmetrical, and so a single SE value should be interpreted with caution. There are many ways of calculating bootstrapped values, and (personally) I would advise you to write your own function to make sure you're comfortable with what's going on.

Smith (1987) discusses how there is a trade-off between choosing a value of k that is sufficiently large so as to detect signal, but not so large as to introduce signal from the bulk (centre) of the distribution. When there is evidence that the confidence intervals are being influenced by the bulk of the distribution this function returns NA confidence intervals and issues a warning. The estimate of the limit itself seems unaffected, but as with any statistical method you should inspect your estimates to ensure they make sense. This is a rare occurrence, WDP should add!

Pearse, W. D., Davis, C. C., Inouye, D. W., Primack, R. B., & Davies, T. J. (2017). A statistical estimator for determining the limits of contemporary and historic phenology. Nature Ecology & Evolution, 1. DOI: 10.1038/s41559-017-0350-0 Smith, R. L. (1987). Estimating tails of probability distributions. The annals of Statistics, 1174-1207.

# Gather some observations of when flowers were in bloom
observations <- 5:15
# Estimate the onset of flowering 
weib.limit(observations)
# Estimate the end of flowering
weib.limit(observations, upper=TRUE)
# Change the alpha value for the confidence about those observations
weib.limit(observations, alpha=.2)
# Make use of fewer observations in estimating the onset (note the CI widen as a result)
weib.limit(observations, k=10)
# Bootstrap some confidence limits about the estimate
weib.limit.bootstrap(observations)