Fitting the simplified Metastatistical Extreme Value Distribution (SMEV)
fsmev.RdFit the SMEV distribution to rainfall observations with different estimation methods.
Arguments
- data
A data frame or numeric vector. If a data.frame, column one must contain dates of class
Date, and the last column must contain rainfall values. If a vector, daily data starting from '1970-01-01' is assumed. Negative values are disallowed, and NA values are removed with a warning.- threshold
Numeric threshold defining wet days. Values below or equal to the threshold are set to NA.
- method
Character string for estimating Weibull parameters
candw. Options are probability weighted moments ("pwm"), maximum likelihood ("mle"), or least squares ("ls"). Default is"pwm"(see details).- censor
Logical. If
TRUE, data is left-censored to ensure maxima follow a Weibull tail. Default isFALSE.- censor_opts
A list of censoring options:
thresholds: range of quantiles.mon: start month of the block.nrtrials: number of trials.R: number of synthetic samples.
See
weibull_tail_test.- warn
Logical. If
TRUE(default), censoring warnings are displayed.- sd
Logical. If
TRUE, confidence intervals are calculated (see details). Default isFALSE.- sd.method
Character string for confidence interval methods. Currently only nonparametric bootstrap (
"boot") is supported.- R
Integer. Number of bootstrap samples for confidence intervals.
- left_cens
Numeric in [0, 1). Fraction of smallest ordinary events left-censored (see details). Default is
0. Cannot be combined withcensor = TRUE.
Value
A list of class mevr with components:
cSingle value of the Weibull scale parameter of the SMEV.
wSingle value of the Weibull shape parameter of the SMEV.
nMean number of wet events, averaged over all years. Wet events are defined as rainfall >
threshold.paramsA named vector of the fitted parameters.
maximaMaximum values corresponding to each year.
stdStandard error of fitted parameters (if
sd = TRUE).varcovCovariance matrix of fitted parameters (if
sd = TRUE).dataFiltered data used to fit the SMEV and additional components useful for further analysis.
yearsVector of years as YYYY.
thresholdThe chosen threshold.
methodMethod used to fit the MEVD.
censorTRUEwhen the data series was left-censored andFALSEotherwise.left_censThe fixed left-censoring quantile used for estimating
candw.typeThe type of distribution ("SMEV").
rejectedIf
censor = TRUE,TRUEwhen the Weibull tail assumption is rejected, andFALSEotherwise. Omitted ifcensor = FALSE.opt_quantIf
censor = TRUE, the left-censoring quantile found by the Weibull tail test,NAif the Weibull tail assumption is rejected. Omitted ifcensor = FALSE.opt_threshIf
censor = TRUE, the left-censoring threshold, i.e. the value of the ordinary events atopt_quant,NAif the Weibull tail assumption is rejected. Omitted ifcensor = FALSE.
If censor = TRUE and sd = TRUE, the bootstrap refits the
censored least squares estimator of the Weibull tail test at the fixed
quantile opt_quant to each bootstrap sample, so the uncertainty of
the choice of the quantile itself is not included.
Details
The SMEV was introduced by (Marra et al., 2019) as a simplified version of
the MEVD (Marani and Ignaccolo, 2015) with the assumption of a stationary
parent Weibull distribution as
$$F = [1 - exp(-x/C)^w]^n$$
for \(w > 0\) and \(C > 0\) being the Weibull shape and scale parameter
and \(n > 0\) being the mean number of wet days over all years.
Wet days are defined as rainfall events > threshold. As it was shown by
e.g. Schellander et al., 2019, probability weighted moments should be
preferred over maximum likelihood for the estimation of the Weibull
parameters w and C. Therefore method = 'pwm' is the default.
Confidence intervals of the SMEV distribution can be calculated using a non parametric bootstrap technique. Note that this very slow.
The estimators above assume that all ordinary events are Weibull distributed.
This is usually acceptable for daily rainfall, but not for sub-daily
durations, where the lower part of the sample is affected by the gauge
resolution and by weak events that do not share the tail of the intense
ones. Fitted to the complete sample, the shape parameter is then
overestimated and return levels are strongly underestimated.
Following Marra et al. (2019, 2020) the Weibull distribution can be fitted
to the tail only by left-censoring: with left_cens = 0.9 the
smallest 90 percent of the ordinary events are censored, i.e. their
magnitudes are ignored but they keep their non-exceedance probability,
and n is still the mean number of all ordinary events per year.
With method = 'ls' this is the least squares regression in
Weibull-transformed coordinates used by Marra et al. (2020),
method = 'mle' maximizes the likelihood of the left-censored sample
and method = 'pwm' uses partial probability weighted moments
(Wang, 1990). For sub-daily data, ordinary events should be defined with
event_separation
and ordinary_events.
This function returns the parameters of the fitted SMEV distribution as well as some additional fitting results and input parameters useful for further analysis.
References
Marra, F. et al. (2019) 'A simplified MEV formulation to model extremes emerging from multiple nonstationary underlying processes', Advances in Water Resources. Elsevier Ltd, 127(April), pp. 280-290. doi:10.1016/j.advwatres.2019.04.002 .
Marra, F. et al. (2020) 'A unified framework for extreme subdaily precipitation frequency analyses based on ordinary events', Geophysical Research Letters, 47, e2020GL090209. doi:10.1029/2020GL090209 .
Wang, Q. J. (1990) 'Estimation of the GEV distribution from censored samples by method of partial probability weighted moments', Journal of Hydrology, 120, pp. 103-114.
Examples
data(dailyrainfall)
fit <- fsmev(dailyrainfall)
fit
#> MEVD fitting
#>
#> Type: SMEV
#> Estimator: pwm
#>
#> Parameters:
#> Scale C:
#> [1] 89.59
#>
#> Shape w:
#> [1] 0.8643
#>
#> Mean number of wet events n:
#> [1] 179.2
#>
#> Threshold:
#> [1] 0
plot(fit)
# estimate c and w from the largest 25 percent of the ordinary events only
fit_lc <- fsmev(dailyrainfall, left_cens = 0.75)
fit_lc
#> MEVD fitting
#>
#> Type: SMEV
#> Estimator: pwm
#>
#> Parameters:
#> Scale C:
#> [1] 91.79
#>
#> Shape w:
#> [1] 0.8842
#>
#> Mean number of wet events n:
#> [1] 179.2
#>
#> Threshold:
#> [1] 0
#>
#> Left-censoring quantile:
#> [1] 0.75
# left censor data prior to fitting
set.seed(123)
sample_dates <- seq.Date(from = as.Date("2000-01-01"),
to = as.Date("2020-12-31"),
by = 1)
sample_data <- data.frame(dates = sample_dates,
val = sample(rnorm(length(sample_dates))))
d <- sample_data |>
filter(val >= 0 & !is.na(val))
fit <- fsmev(d)
fit_c <- fsmev(d,
censor = TRUE,
censor_opts = list(thresholds = c(seq(0.5, 0.9, 0.1), 0.95),
mon = 1,
nrtrials = 2,
R = 100))
rp <- 2:100
rl <- return.levels.mev(fit, return.periods = rp)
rl_c <- return.levels.mev(fit_c, return.periods = rp)
plot(sort(pp.weibull(fit$maxima)), sort(fit$maxima),
xlab = "Return period (a)", ylab = "daily rain (mm)")
lines(rl$rp, rl$rl)
lines(rl_c$rp, rl_c$rl, col = "red")
legend("bottomright", legend = c("std", "censored"),
col = c("black", "red"), lty = c(1, 2), lwd = c(1, 1.5), bty = "n")