qua2ci {lmomco} | R Documentation

## Estimate Confidence Interval for a Single Quantile of a Parent Distribution

### Description

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.

### Usage

    qua2ci(f, para, n, ci=0.90, edist='nor', nsim=1000,
    verbose=FALSE, showpar=FALSE, maxlogdiff=6)

### Arguments

`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.

### Value

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.

### Author(s)

W.H. Asquith

### See Also

`lmoms`, `lmom2par`, `par2qua`, `genci`

### Examples

      # 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

[Package lmomco version 0.92 Index]