Skip to contents

Regula-Falsi Profile Likelihood Uncertainty Quantification

Source: R/uncertainty-rfpl.R
uncertainty_rfpl.Rd

Calculates return level estimates and confidence intervals at specified return periods (defaults to 2, 5, 10, 20, 50, and 100 years) using the regula-falsi profile likelihood root‐finding method.

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_rfpl(
  data,
  distribution,
  ns_years = NULL,
  ns_structure = NULL,
  ns_slices = NULL,
  alpha = 0.05,
  periods = c(2, 5, 10, 20, 50, 100),
  tolerance = 0.01
)

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

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.

periods

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

tolerance

The log-likelihood tolerance for Regula-Falsi convergence (default is 0.01).

Value

A list containing the following four items:

  • method: "RFPL"

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

Details

  1. Uses fit_mle() to obtain the maximum log‐likelihood.

  2. Defines an objective function \(f(y_p, p)\) by reparameterizing the log-likelihood.

  3. Iteratively brackets the root by rescaling initial guesses by 0.05 until \(f(y_p, p)\) changes sign.

  4. Uses the regula-falsi method to solve \(f(y_p, p) = 0\) for each return period probability.

  5. Returns lower and upper confidence bounds at significance level alpha.

Note

RFPL uncertainty quantification can be numerically unstable for some datasets. If this function encounters an issue, it will return an error and recommend using the parametric bootstrap method uncertainty_bootstrap() instead.

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). doi:10.1016/j.advwatres.2022.104151

Vidrio-Sahagún, C.T., He, J. & Pietroniro, A. Multi-distribution regula-falsi profile likelihood method for nonstationary hydrological frequency analysis. Stochastic Environmental Research and Risk Assessment 38, 843–867 (2024). doi:10.1007/s00477-023-02603-0

See also

utils_quantiles(), uncertainty_bootstrap(), uncertainty_rfgpl(), plot_sffa_estimates(), plot_nsffa_estimates()

Examples

data <- rnorm(n = 100, mean = 100, sd = 10)
uncertainty_rfpl(data, "GLO")
#> $method
#> [1] "RFPL"
#> 
#> $distribution
#> [1] "GLO"
#> 
#> $params
#> [1] 101.9869489   5.9714069   0.1510906
#> 
#> $ns_structure
#> NULL
#> 
#> $ns_slices
#> NULL
#> 
#> $ci
#>   periods estimates     lower    upper
#> 1       2  101.9869  99.73336 104.1409
#> 2       5  109.4556 107.47229 111.5811
#> 3      10  113.1519 111.08046 116.1748
#> 4      20  116.1792 113.76140 120.7106
#> 5      50  119.5574 116.40696 126.6877
#> 6     100  121.7703 117.93577 131.2453
#>