fsmev: Fitting the simplified Metastatistical Extreme Value...
In mevr: Fitting the Metastatistical Extreme Value Distribution MEVD

fsmev

R Documentation

Fitting the simplified Metastatistical Extreme Value Distribution (SMEV)

Description

Fit the SMEV distribution to rainfall observations with different estimation methods.

Usage

fsmev(
  data,
  threshold = 0,
  method = c("pwm", "mle", "ls"),
  censor = FALSE,
  censor_opts = list(),
  warn = TRUE,
  sd = FALSE,
  sd.method = "boot",
  R = 502,
  left_cens = 0
)

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 `c` and `w`. 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 is `FALSE`.
`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 is `FALSE`.
`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 with `censor = TRUE`.

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.

Value

A list of class mevr with components:

c: Single value of the Weibull scale parameter of the SMEV.
w: Single value of the Weibull shape parameter of the SMEV.
n: Mean number of wet events, averaged over all years. Wet events are defined as rainfall > threshold.
params: A named vector of the fitted parameters.
maxima: Maximum values corresponding to each year.
std: Standard error of fitted parameters (if sd = TRUE).
varcov: Covariance matrix of fitted parameters (if sd = TRUE).
data: Filtered data used to fit the SMEV and additional components useful for further analysis.
years: Vector of years as YYYY.
threshold: The chosen threshold.
method: Method used to fit the MEVD.
censor: TRUE when the data series was left-censored and FALSE otherwise.
left_cens: The fixed left-censoring quantile used for estimating c and w.
type: The type of distribution ("SMEV").
rejected: If censor = TRUE, TRUE when the Weibull tail assumption is rejected, and FALSE otherwise. Omitted if censor = FALSE.

Author(s)

Harald Schellander, Alexander Lieb

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. \Sexpr[results=rd]{tools:::Rd_expr_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. \Sexpr[results=rd]{tools:::Rd_expr_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
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

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

mevr documentation built on Oct. 13, 2026, 5:07 p.m.