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 \le F \le 1\)) of the value, is specified by the user. The user also provides the parameters of the parent distribution (see lmom2par). This function does consider an estimate of the variance-covariance structure of the sample data (for that see qua2ci.cov). The qua2ci.simple is the original implementation and dates close to the initial releases of lmomco and was originally named qua2ci. That name is now deprecated but retained as an alias, which will be removed at some later release.
For nsim simulation runs (ideally a large number), samples of size \(n\) are drawn from \(Q(F,\theta)\). The L-moments of each simulated sample are computed using lmoms and a distribution of the same type is fit. 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 (edist) 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\). The error distribution defaults to the Generalized Normal (see pargno) because this distribution has the Normal as a special case but extends the fit to the 3rd L-moment (\(\tau_3\)) for exotic situations in which some asymmetry in the quantile distribution might exist.
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.simple does just that and uses qua2ci.simple as the computational underpinning.
qua2ci.simple(f,para,n, level=0.90, edist="gno", nsim=1000, showpar=FALSE,
empdist=TRUE, verbose=FALSE, maxlogdiff=6, ...)An R
list is returned. The lwr and upr match the nomenclature of qua2ci.cov but because qua2ci.simple is provided the parent, the true value is returned, whereas qua2ci.cov returns the fit.
The lower value of the confidence interval having nonexceedance probability equal to \((1-\)level\()/2\).
The value returned by par2qua(f,para).
The upper value of the confidence interval having nonexceedance probability equal to \(1-(1-\)level\()/2\).
The L-moments from lmoms of the distribution of simulated of quantiles.
The parameters of the error distribution fit using the elmoms.
An R environment (see below).
A diagnostic value. A value of zero means that successful exit was made.
A descriptive message related to the ifail value.
An echoing of the nsim argument for the function.
The number of executions of the while loop (see Note below).
The empdist element in the returned list is an R
environment that contains:
A nsim-long vector of the simulated quantiles for f.
The lower limit derived from the R quantile function for type=6, which uses \(i/(n+1)\).
The upper limit derived from the R quantile function for type=6, which uses \(i/(n+1)\).
The lower limit estimated by the Bernstein smoother in dat2bernqua for
poly.type = "Bernstein" and bound.type = "none".
The upper limit estimated by the Bernstein smoother in dat2bernqua for
poly.type = "Bernstein" and bound.type = "none".
The product moments of the simulated quantiles from pmoms.
Nonexceedance probability (\(0 \le F \le 1\)) of the quantile for which the confidence interval is needed. This function is not vectorized and therefore only the first value will be used. This is in contrast to the vectorization of \(F\) in the conceptually similar function qua2ci.cov.
The parameters from lmom2par or vec2par---these parameters represent the “true” parent.
The sample size for each Monte Carlo simulation will use.
The confidence interval (\(0 \le \) level \( < 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 simulated quantile distribution as specified by the nonexceedance probability argument. The arguments level and f therefore are separate features.
The model for the error distribution. Although the Normal (the default) commonly is assumed in error analyses, it need not be, as support for other distributions supported by lmomco is available. The default is the Generalized Normal so the not only is the Normal possible but asymmetry is also accomodated (lmomgno). For example, 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\)), then the Generalized Normal or some alternative distribution would likely provide more reliable confidence interval estimation.
The number of simulations (replications) 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. Larger simulation numbers are recommended.
The parameters of the edist for each simulation are printed.
If TRUE, then an R environment is appended onto the element empdist in the returned list, otherwise empdist is NA.
The verbosity of the operation of the function.
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. The concern motivating this feature is that as the number of parameters increases, it seems progressively there is more chance for a distribution tail to swing wildy into regions for which an analyst would not be comfortable with given discipline-specific knowledge. The choice of 6-log cycles is ad hoc at best, and users are encouraged to do their own exploration. If verbose=TRUE then a message will be printed when the maxlogdiff condition is tripped.
Additional arguments to pass such as to lmom2par.
W.H. Asquith
lmoms, pmoms, par2qua, genci.simple, qua2ci.cov