ffaframework (version 0.1.0)

uncertainty_bootstrap: Parametric Bootstrap Uncertainty Quantification

Description

Computes return level estimates and confidence intervals at the specified return periods (defaults to 2, 5, 10, 20, 50, and 100 years) using the parametric bootstrap. This function supports many probability models and parameter estimation methods.

For NS-FFA: To perform uncertainty quantification for a nonstationary model, include the observation years (ns_years), the nonstationary model structure (ns_structure), and a list of years at which to compute the return level estimates and confidence intervals (ns_slices).

Usage

uncertainty_bootstrap(
  data,
  distribution,
  method,
  prior = NULL,
  ns_years = NULL,
  ns_structure = NULL,
  ns_slices = NULL,
  alpha = 0.05,
  samples = 10000L,
  periods = c(2, 5, 10, 20, 50, 100)
)

Value

A list containing the following six items:

• method: "Bootstrap"

• distribution: The distribution argument.

• params: The fitted parameters.

• ns_structure: The ns_structure argument, if given.

• ns_slices: The ns_slices argument, if given.

• ci: A dataframe containing confidence intervals (S-FFA only)

• ci_list: A list of dataframes containing confidence intervals (NS-FFA only).

The dataframe(s) in ci and ci_list have four columns:

• estimates: Estimated quantiles for each return period.

• lower: Lower bound of the confidence interval for each return period.

• upper: Upper bound of the confidence interval for each return period.

• periods: The periods argument.

Arguments

data

Numeric vector of observed annual maximum series values. Must be strictly positive, finite, and not missing.

distribution

A three-character code indicating the distribution family. Must be "GUM", "NOR", "LNO", "GEV", "GLO", "GNO", "PE3", "LP3", or "WEI".

method

Character scalar specifying the estimation method. Must be "L-moments", "MLE", or "GMLE".

prior

Numeric vector of length 2. Specifies the parameters of the Beta prior for the shape parameter \(\kappa\).

ns_years

For NS-FFA only: Numeric vector of observation years corresponding to data. Must be the same length as data and strictly increasing.

ns_structure

For NS-FFA only: Named list indicating which distribution parameters are modeled as nonstationary. Must contain two logical scalars:

• location: If TRUE, the location parameter has a linear temporal trend.

• scale: If TRUE, the scale parameter has a linear temporal trend.

ns_slices

For NS-FFA only: Numeric vector specifying the years at which to evaluate the return levels confidence intervals of a nonstationary probability distribution. ns_slices do not have to be elements of the ns_years argument.

alpha

Numeric scalar in \([0.01, 0.1]\). The significance level for confidence intervals or hypothesis tests. Default is 0.05.

samples

Integer scalar. The number of bootstrap samples. Default is 10000.

periods

Numeric vector used to set the return periods for FFA. All entries must be greater than or equal to 1.

Details

Bootstrap samples are obtained from the fitted distribution via inverse transform sampling. For each bootstrapped sample, the parameters are re-estimated based on the method argument. Then, the bootstrapped parameters are used to compute a new set of bootstrapped quantiles. Confidence intervals are obtained from the empirical nonexceedance probabilities of the bootstrapped quantiles.

References

Vidrio-Sahagún, C.T., He, J. Enhanced profile likelihood method for the nonstationary hydrological frequency analysis, Advances in Water Resources 161, 10451 (2022). tools:::Rd_expr_doi("10.1016/j.advwatres.2022.104151")

See Also

fit_lmoments(), fit_mle(), fit_gmle(), utils_sample_lmoments() utils_quantiles(), plot_sffa_estimates(), plot_nsffa_estimates()

Examples

data <- rnorm(n = 100, mean = 100, sd = 10)
uncertainty_bootstrap(data, "WEI", "L-moments")