simulate.margarita: Simulate return levels, probabilities of threshold...
In harrysouthworth/margarita: Support functions for texmex

Simulate return levels and probabilities of threshold exceedences from a robust linear model and an extreme value model. The procedure is specific to the situation of extreme value modelling of residuals when predictions on the scale of the original data are required.

## S3 method for class 'margarita'
simulate(
  object,
  nsim = 1,
  seed = NULL,
  type = "rl",
  M = NULL,
  scale = "raw",
  Mlabels = NULL,
  ...
)

`object`	An object of class 'margarita'
`nsim`	Only used when `type='simple'`. The number of simulated sets of responses to produce. If `nsim=1`, the default, a vector of simulated responses is returned. Otherwise, a matrix with `nsim` columns, each being a simualted response vector..
`seed`	Used to set the seed for the random number generator. Defaults to `seed=NULL`.
`type`	What type of prediction is required: 'rl' for return levels averaged over baseline; 'prob' for threshold exceedance probabilities averaged over baseline; 'baserl' for return levels across the observed range of baselines; 'baseprob' for exceedance probabilities over the observed range of baselines; or 'simple' for simulated values. Defaults to `type = "rl"`. If `type='simple'` is used, the result is a vector or matrix of simulated response variables. Otherwise, objects of class 'simulate.margarita.rl' or 'simulate.margarita.prob' which have `summary` functions available..
`M`	The return level to be predicted. Defaults to `M=1000`. If `type="prob"`, M should be a vector containing the thresholds whose probabilities of exceedance the user is interested in, on the scale of the raw data (typically, something like `M = c(1, 3, 5, 20) * ULN`..
`scale`	The type of prediction being made. Valid values are 'raw', 'proportional' and 'difference'. Due to how the calculations are performed, `scale` needs to be specified in the call to `simulate` if threshold exceedence probabilities are being predicted, or the call to `summary.simulate` if return levels are being predicted. If `scale='raw'` it is assumed that the values of `M` are on the same scale as the response variable in the GPD model. If `scale='proportional'`, the values of `M` are taken to be fold-changes (e.g. 2, 5, 10 times baseline for return levels, or P(yMax > 2, 5, 10 times yBase)). If `scale='difference'`, absolute changes from baseline are assumed.
`Mlabels`	Labels to be used in the output. Defaults to `Mlabels=NULL` in which case the function guesses at meaningful labels.
`...`	Other arguments passed to `simulate`. `simulate.margarita.baseline.prob` accepts arguments `grid.n` for the number of points across the range of baseline values (defaulting to 25) and `baseline.range` for the range to be simulated over (defaulting to the observed range). If `method = "simple"`, argument `method` is allowed and can be "random" (the default – uses random draws from the posterior distributions of the parameters), "map" (uses the MAP estimates) or "posterior means".
`alpha`	In the corresponding `summary` methods, the levels of alpha for posterior interval estimates. Defaults to `alpha=c(0.1, 0.5)` resulting in 90% and 50% interval estimates.

If type="prob", the function computes simulated probabilities of breaching thresholds M. These are posterior probabilities, not expected proportions. The shape of the distribution will often have a mode at 0. If M is quite low, it might also have a mode at 1. Simple point estimates and intervals for such a distribution do not convey its shape. The summary function reports the median and quantiles. The median will often be lower than the mean. If you need the expected value, you'll need to do more work.

harrysouthworth/margarita documentation built on Aug. 19, 2021, 5 a.m.