theopwms: The Theoretical Probability-Weighted Moments using...

In wasquith/lmomco: L-Moments, Censored L-Moments, Trimmed L-Moments, L-Comoments, and Many Distributions

The Theoretical Probability-Weighted Moments using Integration of the Quantile Function

Description

Compute the theoretical probability-weighted moments (PWMs) for a distribution. A theoretical PWM in integral form is

\beta_r = \int^1_0 x(F)\,F^r\,\mathrm{d}F \mbox{,}

where x(F) is the quantile function of the random variable X for nonexceedance probability F and r represents the order of the PWM. This function loops across the above equation for each nmom set in the argument list. The function x(F) is computed through the par2qua function. The distribution type is determined using the type attribute of the para argument, which is a parameter object of lmomco (see vec2par).

Usage

theopwms(para, nmom=5, minF=0, maxF=1, quafunc=NULL,
               nsim=50000, fold=5,
               silent=TRUE, verbose=FALSE, ...)

Arguments

para	A distribution parameter object such as that by lmom2par or vec2par.
nmom	The number of moments to compute. Default is 5.
minF	The end point of nonexceedance probability in which to perform the integration. Try setting to non-zero (but small) if you have a divergent integral.
maxF	The end point of nonexceedance probability in which to perform the integration. Try setting to non-unity (but close) if you have a divergent integral.
quafunc	An optional and arbitrary quantile function that simply needs to except a nonexceedance probability and the parameter object in para. This is a feature that permits computation of the PWMs of a quantile function that does not have to be implemented in the greater overhead hassles of the lmomco style. This feature might be useful for estimation of quantile function mixtures or those distributions not otherwise implemented in this package.
nsim	Simulation size for Monte Carlo integration is such is internally deemed necessary (see silent argument).
fold	The number of fractions or number of folds of nsim, which in other words, means that nsim is divided by folds and a loop creating folds integrations of nsim/folds is used from which the mean and mean absolute error of the integrand are computed. This is to try to recover similar output as integrate().
silent	The argument of silent for the try() operation wrapped on integrate(). If set true and the integral is probability divergent, Monte Carlo integration is triggered using nsim and folds. The user would have to set verbose=TRUE to then acquire the returned table in integrations of the integration passes including those are or are not Monte Carlo.
verbose	Toggle verbose output. Because the R function integrate is used to perform the numerical integration, it might be useful to see selected messages regarding the numerical integration.
...	Additional arguments to pass.

Value

An R list is returned.

betas	The PWMs. Note that convention is the have a \beta_0, but this is placed in the first index i=1 of the betas vector.
nsim	Echo of the nsim argument if and only if at least one Monte Carlo integration was required, otherwise this is set to “not needed” on the return.
folds	Echo of the folds argument if and only if at least one Monte Carlo integration was required, otherwise this is set to “not needed” on the return.
monte_carlo	A logical vector of whether one or more Monte Carlo integrations was needed for the r-th index of the vector during the integrations for the r-th PWM (beta).
source	An attribute identifying the computational source of the probability-weighted moments: “theopwms”.
integrations	If verbose=TRUE, then the results of the integrations are a data frame stored here. Otherwise, integrations is not present in the list.

Author(s)

W.H. Asquith

References

Hosking, J.R.M., 1990, L-moments–Analysis and estimation of distributions using linear combinations of order statistics: Journal of the Royal Statistical Society, Series B, v. 52, p. 105–124.

See Also

theoLmoms, pwm, pwm2lmom

Examples

para     <- vec2par(c(0,1),type='nor') # standard normal
the.pwms <- theopwms(para) # compute PWMs
str(the.pwms)

## Not run: 
  # This example has a divergent integral triggered on the beta0. Monte Carlo (MC)
  # integration is thus triggered. The verbose=TRUE saves numerical or MC
  # integration result table to the return.
  para <- vec2par(c(2,2, 1.8673636098392308, -0.1447286792099476), type="kap")
  pwmkap <- lmom2pwm( lmomkap(para) )
  print(pwmkap$betas) # 0.1155903 1.2153105 0.9304619 0.7282926 0.5938137
  pwmthe <- theopwms(para, nmom=5, verbose=TRUE)
  print(pwmthe$betas) # 0.1235817 1.2153104 0.9304619 0.7282926 0.5938137

  para <- vec2par(c(2,2, 0.9898362024687231, -0.5140894097276032), type="kap")
  pwmkap <- lmom2pwm( lmomkap(para) )
  print(pwmkap$betas) # -0.06452787  1.33177963  1.06818379  0.85911124  0.71308145
  pwmthe <- theopwms(para, nmom=5, verbose=TRUE)
  print(pwmthe$betas) # -0.06901669  1.33177952  1.06818379  0.85911123  0.71308144 
## End(Not run)

wasquith/lmomco documentation built on May 6, 2024, 1:43 a.m.