qua2ci                package:lmomco                R Documentation

_E_s_t_i_m_a_t_e _C_o_n_f_i_d_e_n_c_e _I_n_t_e_r_v_a_l _f_o_r _a _S_i_n_g_l_e _Q_u_a_n_t_i_l_e _o_f _a _P_a_r_e_n_t _D_i_s_t_r_i_b_u_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

       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 base on
          experience with the Kappa distribution fit to a typical
          heavy-right tail flood magnitude data set. If 'verbose=TRUE'
          then a message will be printed when the 'maxlogdiff'
          condition is tripped.

_V_a_l_u_e:

     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.

_A_u_t_h_o_r(_s):

     W.H. Asquith

_S_e_e _A_l_s_o:

     'lmoms', 'lmom2par', 'par2qua', 'genci'

_E_x_a_m_p_l_e_s:

       # 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

