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, quiet=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.frames 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.
quiet Suppress incremental counter for a count down of the F values.

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.96.3 Index]