lmomco (version 0.88)

genci: 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 \le 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 \le F \le 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 \le$ 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 probabi

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 consi

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

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 confi

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, $\lambda_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.

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))
  ymax <- log10(max(CI$upper))
  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)