upper.limit: Calculation of the upper limit.

In theGreatWhiteShark/climex: Estimating Extreme Events in Climatic Time Series (using Data of the DWD)

Calculation of the upper limit.

Description

Calculates the upper limit and its error estimate for Weibull-typed Generalized Extreme Value distribution (GEV) and Generalized Pareto (GP) distributions (both only in case of shape parameters smaller than 0).

Usage

upper.limit(x, error.estimation = c("none", "MC", "MLE", "bootstrap"),
  model = c("gev", "gpd"), monte.carlo.sample.size = 100,
  bootstrap.sample.size = 100, threshold = NULL,
  extreme.type = c("max", "min"), mc.cores = NULL)

Arguments

x	A list of class numeric, climex.fit.gev, or climex.fit.gpd objects.
error.estimation	Method for calculating the standard error of the upper limit. For all three methods of estimating the fitting error of the upper limit an underlying series of threshold exceedances or block maxima is required. In case the user supplies numerical values to specify the GEV/GP parameters and not the output of either the fit.gev or fit.gpd function, no error estimation can be performed. MLE: The variances of the GEV/GP parameters will be calculated as the square roots of the diagonal elements of the inverse of the hessian matrix evaluated at the Maximum Likelihood estimates (MLE) of the GEV/GP parameters, the so-called observed information matrix. The standard error of the upper limit is calculated using error propagation and multiplying the gradient of the equation for the upper limit to both sides of its inverse. Sometimes the inversion of the hessian fails (because there are some NaN in the hessian) when calculating the error estimates using the Maximum Likelihood approach (MLE). This might happen especially with older versions of the optim package. In such cases the Monte Carlo (MC) method is used as a fallback. MC: Alternatively one can use a Monte Carlo method for which monte.carlo.sample.size samples of the same length as x will be drawn from a GEV/GP distribution constituted by the obtained MLE of the GEV/GP parameters of x. The standard error is then calculated for the upper limits of all sampled series. Note: In its essence this approach is not an estimation of the error involved in fitting the time series to a GEV/GP distribution. It is rather the mean error of fitting a GEV/GP-distribution with the same length and parameters as estimated ones. bootstrap: Using this option the provided time series x will be sampled with replacement bootstrap.sample.size times and with the same length as the original time series. The standard errors of the upper limits of all those sampled series are calculated and returned as an estimate of the fitting error. Note: Since the data is (hopefully) GEV/GP-distributed, such a sampling has to be treated with a lot of care. none skips the calculation of the error. Default = "MLE".
model	String determining whether to calculate the initial parameters of the GEV ("gev") or GP ("gpd") function. Default = "gev"
monte.carlo.sample.size	Number of samples used to obtain the Monte Carlo estimate of the standard error of the fitting. Default = 100.
bootstrap.sample.size	Number of samples with replacements to drawn from the original series x in order to determine the standard errors for the upper limit. Default = 100.
threshold	Optional threshold for the GP model. If present it will be added to the upper limit to produce a value which fits to underlying time series. Default = NULL.
extreme.type	String indicating whether to calculate the quantiles at the right ("max") or left ("min") side of the PDF of the series. Default = "max".
mc.cores	A numerical input specifying the number of cores to use for the multi core application of the function (see detectCores). This functionality is only available if the input is a list of different objects. If NULL, the function will be calculated classically with only one core. Default = NULL.

Details

Three different ways of calculating the fitting errors are supported: The MLE option using the error propagation of the covariance matrix obtained via the Maximum Likelihood estimators, the two statistical methods MC and bootstrap with the former calculating the standard deviation of the upper limits fitted to a set Monte Carlo samples distributed according to the maximum likelihood estimates of the GEV or GP distribution and the latter by using samples generated via bootstrap instead.

Since the upper limit is only defined for shape parameters smaller than zero, all upper limits calculated for the bootstrap or Monte Carlo samples showing positive shapes have to be discarded. This results in a negative bias of estimator. On the other hand, this can also lead to an estimate for the fitting error if the actual Maximum Likelihood estimate of the shape parameter is slightly bigger than zero. Please keep this in mind when interpreting the results.

This function is also capable of working with lists of fit or numerical objects.

Value

A list containing the estimates "upper.limit" and their standard errors "error" if the input was a fitting object or a numerical input. If, on the other hand, the input was a list of such objects, the output is a list of the aforementioned list.

See Also

Other extremes: block.list, block.xts, block, decluster.list, decluster.xts, decluster, extremal.index, gev.density, gpd.density, qevd, return.level.climex.fit.gev, return.level.climex.fit.gpd, return.level.list, return.level.numeric, return.level, revd, rlevd, threshold.list, threshold.xts, threshold, upper.limit.climex.fit.gev, upper.limit.climex.fit.gpd, upper.limit.list, upper.limit.numeric

Examples

fit.results <- fit.gev( block( anomalies( temp.potsdam ) ) )
upper.limit( fit.results, error.estimation = "MLE" )

theGreatWhiteShark/climex documentation built on July 13, 2022, 9:11 a.m.