qua2ci {lmomco} | R Documentation |
This function estimates the lower and upper limits of a specified confidence interval for an aribitrary quantile value of a specified parent distribution [quantile function Q(F,theta) with parameters theta] using Monte Carlo simulation. The quantile value, actually the nonexceedance probability (F for 0 <= F < 1) of the value, is specified by the user. The user also provides the parameters of the parent distribution (see lmom2par
).
For nsim
simulation runs (ideally a very large number), samples of size n are drawn from Q(F,theta) using the R-function runif(n)
to generate the simulated F values and the lmomco function par2qua
function to compute the quantile. The L-moments of the simulated sample are computed using lmoms
and a distribution of the same type as the parent is fit to these simulated L-moments. The F-quantile of the just-fitted distribution is computed and placed into a vector. The process of simulating the sample, computing the L-moments, computing the parameters, and solving for the F-quantile is repeated for the specified number of simulation runs.
To estimate the confidence interval, the L-moments of the vector simulated quantiles are computed. Subsequently, the parameters of a user-specified distribution “error” distribution are computed. The two quantiles of this error distribution for the specified confidence interval are computed. These two quantiles represent the estimated lower and upper limits for the confidence interval of the parent distribution for samples of size n.
Finally, it is often useful to have vectors of lower and upper limits for confidence intervals for a vector of F values. The function genci
does just that and uses the qua2ci
function as the computational engine.
qua2ci(f, para, n, ci=0.90, edist='nor', nsim=1000, verbose=FALSE, showpar=FALSE, maxlogdiff=6)
f |
Nonexceedance probability (0 <= F <= 1) of the quantile for which the confidence interval is needed. |
para |
The parameters from lmom2par or similar. |
n |
The sample size that the Monte Carlo simulation will use. |
ci |
The confidence interval (0.5 <= ci < 1). The interval is specified as the size of the interval. The default is 0.90 or the 90th percentile. The function will return the 5th (1-0.90)/2 and 95th (1-(1-0.90)/2) percentile cumulative probability of the error distribution for the parent quantile as specified by the nonexceedance probability argument. The arguments ci and f therefore are separate features. |
edist |
The model for the error distribution. Although the normal (the default) is typically assumed in error analyses, it need not be, as support for other distributions supported by the lmomco package is available. However, one should seriously consider the values of the simulated L-moments when choosing an error distribution other than the normal. If the L-skew (tau_4) or L-kurtosis (tau_4) values depart considerably from those of the normal (tau_3 = 0 and tau_4 = 0.122602), alternative distributions would likely provide more reliable confidence interval estimation. |
nsim |
The number of simulations for the sample size n to perform. Large numbers produce more refined confidence limit estimates at the cost of CPU time. The default is anticipated to be large enough for evaluative-useage without too much computational delay. Much larger simulation numbers are highly recommended. |
verbose |
The verbosity of the operation of the function. |
showpar |
The parameters of the edist for each simulation are printed. |
maxlogdiff |
The maximum permitted difference in log10 space between a simulated quantile and the true value. It is possible that a well fit simulated sample to the parent distribution type provides crazy quantile estimates in the far reaches of either tail. The default value of 6 was chosen based on experience with the Kappa distribution fit to a typical heavy-right tail flood magnitude data set. However, the choice of 6-log cycles is ad hoc at best; users are encouraged to do their own exploration. If verbose=TRUE then a message will be printed when the maxlogdiff condition is tripped. |
An R list
is returned.
lower |
The lower value of the confidence interval having nonexceedance probability equal to (1-ci )/2. |
true |
The value returned by par2qua(f,para) . |
upper |
The upper value of the confidence interval having nonexceedance probability equal to 1-(1-ci )/2. |
elmoms |
The L-moments of the distribution of simulated of quantiles. |
epara |
The parameters of the error distribution fit using the elmoms . |
ifail |
A diagnostic value. A value of zero means that successful exit was made. |
ifailtext |
A descriptive message related to the ifail value. |
W.H. Asquith
lmoms
, lmom2par
, par2qua
, genci
# It is well known that standard deviation (sigma) of the # sample mean is equal to sigma/sample_size. MEAN <- 0 SIGMA <- 100 PAR <- vec2par(c(MEAN,SIGMA),type='nor') CI <- qua2ci(0.5,PAR,n=10,nsim=20) # F=0.5-->median=mean # Theoretrical sample mean sigma = 100/10 = 10 # L-moment theory: L-scale*sqrt(pi) = sigma # Thus, it follows that CI$elmoms$lambdas[2]/sqrt(pi) # approaches 10 as nsim --> Inf. # Another example. D <- c(123,34,4,654,37,78, 93, 95, 120) # fake sample lmr <- lmoms(D) # compute the lmoments of the data WEI <- parwei(lmr) # estimate parameters of the weibull CI <- qua2ci(0.75,WEI,20,nsim=20,ci=0.95) # CI contains the estimate 95-percent # confidence interval for the 75th-percent of the parent # weibull distribution for size 20 samples from the parent