genci {lmomco} | R Documentation

## Generate Confidence Intervals for Quantiles of a Parent Distribution

### Description

This function estimates the lower and upper limits of a specified confidence interval for a vector of quantile value of a specified parent distribution [quantile function Q(F,theta) with parameters theta] using Monte Carlo simulation. The quantile values, actually specified by a vector of nonexceedance probabilities (F for 0 <= F < 1) of the values, are specified by the user. The user also provides the parameters of the parent distribution (see `lmom2par`). This function is a wrapper on `qua2ci`; please consult the documentation for that function for further details of the simulation.

### Usage

    genci(para, n, F=NULL, ci=0.90, edist='nor', nsim=1000, expand=FALSE,
    verbose=FALSE, showpar=FALSE)

### Arguments

`para` | The parameters from `lmom2par` or similar.
`n` | The sample size that the Monte Carlo simulation will use.
`F` | Vector of nonexceedance probabilities (0 <= F <= 1) of the quantiles for which the confidence interval are needed. If `NULL`, then the vector as returned by `nonexceeds` is used.
`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 (`F`). This argument is passed unused to `qua2ci`.
`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. This argument is passed unused to `qua2ci`.
`nsim` | The number of simulations for the sample size `n` to perform. Much larger simulation numbers are highly recommended—see discussion about `qua2ci`. This argument is passed unused to `qua2ci`. Users are encouraged to play with `qua2ci` to get a feel for the value of `edist` and `nsim`.
`expand` | Should the returned values be expanded to include information relating to the distribution type and L-moments of the distribution at the corresponding nonexceedance probabilities—in other words the information necessary to reconstruct the reported confidence interval. The default is `FALSE`. If `expand=FALSE` then a single `data.frame` of the lower and upper limits along with the true quantile value of the parent is returned. If `expand=TRUE`, then a more complicated `list` containing multiple `data.frame`s is returned.
`verbose` | The verbosity of the operation of the function. This argument is passed unused to `qua2ci`.
`showpar` | The parameters of the `edist` for each simulation for each F value passed to `qua2ci` are printed. This argument is passed unused to `qua2ci`.

### Value

An R `data.frame` or `list` is returned (see discussion of argument `expand`). The following elements could be available.

`nonexceed_prob` | A vector of F values, which is returned for convenience so that post operations such as plotting are easily coded.
`lower` | The lower value of the confidence interval having nonexceedance probability equal to `(1-ci)/2`.
`true` | The true quantile value from Q(F,theta) for the corresponding F value.
`upper` | The upper value of the confidence interval having F equal to `1-(1-ci)/2`.
`lscale` | The second L-moment (L-scale, λ_2) of the distribution of quantiles for the corresponding F. This value is included in the primary returned `data.frame` because it measures the fundamental sampling variability.
`lcv` | The ratio of lscale to true. A measure of relative variability
`parent` | The paraments of the parent distribution if `expand=TRUE`.
`edist` | The type of error distribution used to model the confidence interval if `expand=TRUE`.
`elmoms` | The L-moment of the distribution of quantiles for the corresponding F if `expand=TRUE`.

### Author(s)

W.H. Asquith

### See Also

`lmoms`, `lmom2par`, `qua2ci`, `gen.freq.curves`

### Examples

      # For all these examples, nsim is way too small.
      MEAN  <- 0    # mean of zero
      SIGMA <- 100  # standard deviation of 100
      PAR   <- vec2par(c(MEAN,SIGMA),type='nor') # make parameter object
      F     <- nonexceeds() # list of useful nonexceedance probabilities
      # nsim is small for speed of example not accuracy.
      CI    <- genci(PAR,n=10,F=F,nsim=20)
      plot(CI$nonexceed_prob,CI$true,type='l',lwd=2)
      lines(CI$nonexceed_prob,CI$lower,col=2)
      lines(CI$nonexceed_prob,CI$upper,col=3)

      # The qnorm call has been added to produce "normal probability"
      # paper on the horizonal axis. The parent is heavy-tailed.
      GEV <- vec2par(c(3000,1500,-.3),type='gev') # a GEV distribution
      # use 15 simulations of size 20 samples
      # The generalized normal distribution is a general case of lognormal---
      # for illustration, suppose the parent GEV is modeling phenomena that
      # are strictly positive. So to prevent negative lower limits, use the
      # lognormal distribution as the error model.
      CI  <- genci(GEV,n=20,nsim=15,edist='gno')
      ymin <- log10(min(CI$lower[CI$lower > 0])) # > 0 to protect log10() call
      ymax <- log10(max(CI$upper[CI$upper > 0])) #    .. ditto ..
      plot(qnorm(CI$nonexceed_prob),log10(CI$true),type='l',ylim=c(ymin,ymax),lwd=2)
      lines(qnorm(CI$nonexceed_prob),log10(CI$lower),col=2)
      lines(qnorm(CI$nonexceed_prob),log10(CI$upper),col=3)

[Package lmomco version 0.92 Index]