Performs frequency analysis of annual maximum series data including distribution selection, parameter estimation, uncertainty quantification, and model assessment. Supports both stationary (S-FFA) or nonstationary (NS-FFA) flood frequency analysis.
framework_ffa(
data,
years,
ns_splits = NULL,
ns_structures = NULL,
generate_report = TRUE,
report_path = NULL,
report_formats = "html",
...
)modelling_assumptions: A list describing the model(s) used for the analysis.
approach: Either "S-FFA", "NS-FFA", or "Piecewise NS-FFA".
ns_splits: The ns_splits argument, if given.
ns_structures: The ns_structures argument, if given.
submodule_results: A list of lists of containing the results of frequency analysis.
Each list contains:
name: Either "Distribution Selection", "Parameter Estimation", "Uncertainty
Quantification", or "Model Assessment".
start: The first year of the homogeneous subperiod.
end: The last year of the homogeneous subperiod.
Additional items specific to the the submodule.
Numeric vector of observed annual maximum series values. Must be strictly positive, finite, and not missing.
Numeric vector of observation years corresponding to data.
Must be the same length as data and strictly increasing.
An integer vector of years used to split the data into homogeneous
subperiods. For S-FFA, set to NULL (default). For NS-FFA, specify an integer vector
of years with physical justification for change points, or NULL if no such years exist.
In R, integers have the suffix L, so 1950L is a valid input to ns_splits, but 1950
is not (since R may interpret it as a floating point number).
For S-FFA, set to NULL (default) to use a stationary model
for all homogeneous subperiods. For NS-FFA, provide a list of length(ns_splits) + 1
sublists specifying the nonstationary model structure for each homogeneous subperiod.
Each sublist must contain logical elements location and scale, indicating
monotonic trends in the mean and variability, respectively.
If TRUE (default), generate a report.
A character scalar, the file path for the generated report.
If NULL (default), the report will be saved to a new temporary directory.
A character vector specifying the output format for the
report. Supported values are "md", "pdf", "html", and "json".
Additional arguments. See the "Optional Arguments" section for a complete list.
selection: Distribution selection method (default is "L-distance"). Must be
one of "L-distance", "L-kurtosis" or "Z-statistic". Alternatively, set
selection to a three-letter distribution code (e.g., "GUM") to use a specific
distribution.
s_estimation: Parameter estimation method for S-FFA (default is "L-moments").
Must be "L-moments", "MLE", or "GMLE". Method "GMLE" requires
selection = "GEV".
ns_estimation: Parameter estimation method for NS-FFA (default is "MLE").
Must be "MLE" or "GMLE". Method "GMLE" requires selection = "GEV".
s_uncertainty: Uncertainty quantification method for S-FFA (default is
"Bootstrap"). Must be one of "Bootstrap", "RFPL", or RFGPL". Using
method "RFPL" requires s_estimation = "MLE" and method "RFGPL" requires
s_estimation = "GMLE".
ns_uncertainty: Uncertainty quantification method for NS-FFA (default is
"RFPL"). Must be one of "Bootstrap", "RFPL", or RFGPL". Using method
"RFPL" requires ns_estimation = "MLE" and method "RFGPL" requires
ns_estimation = "GMLE".
z_samples: Integer number of bootstrap samples for selection method
"Z-statistic" (default is 10000).
gev_prior: Parameters for the prior distribution of the shape parameter of the
GEV distribution (default is 6, 9). Used with estimation method "GMLE".
return_periods: Integer list of return periods (in years) for estimating return
levels. Uses the 2, 5, 10, 20, 50, and 100 year return periods by default.
ns_slices: Integer vector of years at which to estimate the return levels for
nonstationary models. Slices outside of the period will be ignored (default is
1925, 1975, 2025).
bootstrap_samples: Integer number of samples for uncertainty quantification
method `"Bootstrap" (default is 10000).
rfpl_tolerance: Log-likelihood tolerance for uncertainty quantification method
"RFPL"(default is 0.01).
pp_formula: Plotting position formula for model assessment. Must be one of:
"Weibull" (default): \(i / (n + 1)\)
"Blom": \((i - 0.375) / (n + 0.25)\)
"Cunnane": \((i - 0.4) / (n + 0.2)\)
"Gringorten": \((i - 0.44) / (n + 0.12)\)
"Hazen": \((i - 0.5) / n\)
select_ldistance(), select_lkurtosis(), select_zstatistic(),
fit_lmoments(), fit_mle(), fit_gmle(), uncertainty_bootstrap(),
uncertainty_rfpl(), uncertainty_rfgpl(), model_assessment()