genci                 package:lmomco                 R Documentation

_G_e_n_e_r_a_t_e _C_o_n_f_i_d_e_n_c_e _I_n_t_e_r_v_a_l_s _f_o_r _Q_u_a_n_t_i_l_e_s _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 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.

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

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

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

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

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

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

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

     W.H. Asquith

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

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

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

       # 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)

