ftmev: Fitting the temporal Metastatistical Extreme Value...
In mevr: Fitting the Metastatistical Extreme Value Distribution MEVD
ftmev R Documentation
Fitting the temporal Metastatistical Extreme Value Distribution (TMEV)
Description
Fit the temporal MEVD distribution TMEV to rainfall observations with a
cyclic spline to account for seasonality.
Usage
ftmev(
data,
threshold = 0,
minyears = 10,
day_year_interaction = FALSE,
verbose = FALSE,
yday_ti_shape_k = 10,
yday_ti_scale_k = 10,
year_ti_shape_k = 10,
year_ti_scale_k = 10
)
Arguments
data
The data to which the TMEV should be fitted to.
data must
be a data.frame with two columns. The first column must contain dates
of class Date, the second or last column must contain the rainfall
values corresponding to datums in the rows. No negative values are allowed.
NA values are removed with a warning.
threshold
A numeric value used
to define wet days as values exceeding
the threshold. Values below are set to NA.
minyears
Minimum number of years
required for fitting a cyclic spline
to non-stationary data (see details).
day_year_interaction
Logical.
Should a year-by-day interaction be used
for the temporal trend in seasonality?
Default is FALSE.
verbose
Logical. If TRUE, verbose output of the temporal
fitting process is shown during runtime.
yday_ti_shape_k
A numeric used
to set the basis dimension for the smooth term ti()
for yday in the formula for shape.
yday_ti_scale_k
A numeric used
to set the basis dimension for the smooth term ti()
for yday in the formula for scale.
year_ti_shape_k
A numeric used
to set the basis dimension for the smooth term ti()
for year in the formula for shape
(only used when day_year_interaction == TRUE).
year_ti_scale_k
A numeric used
to set the basis dimension for the smooth term ti()
for year in the formula for scale
(only used when day_year_interaction == TRUE).
Details
With the aim of exploiting the full temporal information for parameter
estimation, Falkensteiner et al., (2023) introduced the TMEV, which is
an explicitly non-stationary formulation of the MEVD
(Marani and Ignaccolo, 2015). Adopting a Weibull distribution for
ordinary rainfall events, the assumption of yearly
constant coefficients is relaxed by allowing the Weibull
parameters to fluctuate with time. The TMEV can then be written as
\begin{aligned}
F = \frac{1}{T} \sum_{j=1}^T &\prod_{k \in A_j}
\left( 1 - \exp\left( -\left(\frac{x}{C(j,k)}\right)^{w(j,k)} \right) \right)
\end{aligned}
with w > 0 and C > 0 being the Weibull shape and scale
parameters, and $A_j \subseteq (1, ..., 366)$ being the wet days in year j.
The temporal and the superimposed seasonal dependence on w and c is modeled
with a cyclic seasonal effect on the day of the year.
Technically this is accomplished by fitting a cyclic spline to
the daily rainfall values. The following formula is used for the fitting
procedure of both the Weibull scale and shape parameter with the function
bamlss from package bamlss:
parameter = x \sim s(year) + ti(yday, bs = "cc", k = 10)
The first effect models the long-term temporal trend of the parameter
with a thin-plate spline. The second effect models the superimposed seasonal
fluctuations of the parameter with the 'day of the year' with a cyclic cubic
regression spline and 10 knots, to ensure a smooth transition between
December and January. The number of knots (k) in the above equation can be
set separately for the year and yday effect as well as separately for the
shape and scale parameter of the Weibull distribution. This can be done
by overwriting the parameters yday_ti_shape_k, yday_ti_scale_k,
year_ti_shape_k, year_ti_scale_k in the call to ftmev.
Note that these values depend on many factors, such as the structure of
the data, the TMEV is fitted to.
Please refer to the documentation of the packages
bamlss and,
in particular, mgcv.
For data series with lengths < 10 years, the first temporal effect
is changed to a simple linear time trend.
For trend analysis, an additional interaction term can be added to the
model formula. The following term models the relationship between the
seasonality as day of the year and the year itself with a combination of
a thin plate and a cyclic cubic spline:
\begin{aligned}
ti(&year, yday, bs = c("tp", "cc"), \\
&d = c(1, 1), k = c(year\_ti\_k, yday\_ti\_k))
\end{aligned}
This function returns the parameters of the fitted TMEV distribution
as well as some additional fitting results and input parameters useful
for further analysis.
Value
A list of class mevr with components:
cVector of Weibull scale parameters of the TMEV,
where each row refers to an event (daily rainfall).
wVector of Weibull shape parameters of the TMEV,
where each row refers to an event (daily rainfall).
nNumber of wet events per year. Wet events are defined
as rainfall > threshold.
maximaMaximum values corresponding to each year.
dataA data frame with the data used to fit the TMEV
and the fitted Weibull parameters c and w.
yearsVector of years as YYYY.
thresholdThe chosen threshold.
xThe fitted bamlss object.
typeThe type of distribution ("TMEV").
minyearsThe minimum number of years used to fit
the TMEV as provided.
Author(s)
Marc-Andre Falkensteiner, Harald Schellander
References
Marani, M. and Ignaccolo, M. (2015)
'A metastatistical approach to rainfall extremes',
Advances in Water Resources. Elsevier Ltd, 79(Supplement C),
pp. 121-126. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.advwatres.2015.03.001")}.
Falkensteiner, M., Schellander, H., Hell, T. (2023)
'Accounting for seasonality in the metastatistical extreme value
distribution', (Weather and Climate Extremes, 42, 2023,
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.wace.2023.100601")}).
See Also
fmev, fsmev
Examples
data(dailyrainfall)
filtered_data <- subset(
dailyrainfall,
as.numeric(format(dates, "%Y")) >= 1971 &
as.numeric(format(dates, "%Y")) <= 1978
)
fit <- ftmev(filtered_data, minyears = 5)
plot(fit, type = "rl")
# temporal trend of the Weibull parameters
pred <- predict(fit)
pred_year <- predict(fit, term = "year")
boxplot(c.pred ~ year, data = pred)
with(pred_year, lines(year - 1970,
c.pred.year,
type = "b",
pch = 20,
col = "red"))
mevr documentation built on Oct. 13, 2026, 5:07 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| ftmev | R Documentation |
Fitting the temporal Metastatistical Extreme Value Distribution (TMEV)
Description
Fit the temporal MEVD distribution TMEV to rainfall observations with a cyclic spline to account for seasonality.
Usage
ftmev(
data,
threshold = 0,
minyears = 10,
day_year_interaction = FALSE,
verbose = FALSE,
yday_ti_shape_k = 10,
yday_ti_scale_k = 10,
year_ti_shape_k = 10,
year_ti_scale_k = 10
)
Arguments
data |
The data to which the TMEV should be fitted to.
|
threshold |
A numeric value used to define wet days as values exceeding the threshold. Values below are set to NA. |
minyears |
Minimum number of years required for fitting a cyclic spline to non-stationary data (see details). |
day_year_interaction |
Logical.
Should a year-by-day interaction be used
for the temporal trend in seasonality?
Default is |
verbose |
Logical. If |
yday_ti_shape_k |
A numeric used to set the basis dimension for the smooth term ti() for yday in the formula for shape. |
yday_ti_scale_k |
A numeric used to set the basis dimension for the smooth term ti() for yday in the formula for scale. |
year_ti_shape_k |
A numeric used to set the basis dimension for the smooth term ti() for year in the formula for shape (only used when day_year_interaction == TRUE). |
year_ti_scale_k |
A numeric used to set the basis dimension for the smooth term ti() for year in the formula for scale (only used when day_year_interaction == TRUE). |
Details
With the aim of exploiting the full temporal information for parameter estimation, Falkensteiner et al., (2023) introduced the TMEV, which is an explicitly non-stationary formulation of the MEVD (Marani and Ignaccolo, 2015). Adopting a Weibull distribution for ordinary rainfall events, the assumption of yearly constant coefficients is relaxed by allowing the Weibull parameters to fluctuate with time. The TMEV can then be written as
\begin{aligned}
F = \frac{1}{T} \sum_{j=1}^T &\prod_{k \in A_j}
\left( 1 - \exp\left( -\left(\frac{x}{C(j,k)}\right)^{w(j,k)} \right) \right)
\end{aligned}
with w > 0 and C > 0 being the Weibull shape and scale
parameters, and $A_j \subseteq (1, ..., 366)$ being the wet days in year j.
The temporal and the superimposed seasonal dependence on w and c is modeled
with a cyclic seasonal effect on the day of the year.
Technically this is accomplished by fitting a cyclic spline to
the daily rainfall values. The following formula is used for the fitting
procedure of both the Weibull scale and shape parameter with the function
bamlss from package bamlss:
parameter = x \sim s(year) + ti(yday, bs = "cc", k = 10)
The first effect models the long-term temporal trend of the parameter
with a thin-plate spline. The second effect models the superimposed seasonal
fluctuations of the parameter with the 'day of the year' with a cyclic cubic
regression spline and 10 knots, to ensure a smooth transition between
December and January. The number of knots (k) in the above equation can be
set separately for the year and yday effect as well as separately for the
shape and scale parameter of the Weibull distribution. This can be done
by overwriting the parameters yday_ti_shape_k, yday_ti_scale_k,
year_ti_shape_k, year_ti_scale_k in the call to ftmev.
Note that these values depend on many factors, such as the structure of
the data, the TMEV is fitted to.
Please refer to the documentation of the packages
bamlss and,
in particular, mgcv.
For data series with lengths < 10 years, the first temporal effect is changed to a simple linear time trend.
For trend analysis, an additional interaction term can be added to the model formula. The following term models the relationship between the seasonality as day of the year and the year itself with a combination of a thin plate and a cyclic cubic spline:
\begin{aligned}
ti(&year, yday, bs = c("tp", "cc"), \\
&d = c(1, 1), k = c(year\_ti\_k, yday\_ti\_k))
\end{aligned}
This function returns the parameters of the fitted TMEV distribution as well as some additional fitting results and input parameters useful for further analysis.
Value
A list of class mevr with components:
cVector of Weibull scale parameters of the TMEV, where each row refers to an event (daily rainfall).
wVector of Weibull shape parameters of the TMEV, where each row refers to an event (daily rainfall).
nNumber of wet events per year. Wet events are defined as rainfall >
threshold.maximaMaximum values corresponding to each year.
dataA data frame with the data used to fit the TMEV and the fitted Weibull parameters
candw.yearsVector of years as YYYY.
thresholdThe chosen threshold.
xThe fitted
bamlssobject.typeThe type of distribution ("TMEV").
minyearsThe minimum number of years used to fit the TMEV as provided.
Author(s)
Marc-Andre Falkensteiner, Harald Schellander
References
Marani, M. and Ignaccolo, M. (2015) 'A metastatistical approach to rainfall extremes', Advances in Water Resources. Elsevier Ltd, 79(Supplement C), pp. 121-126. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.advwatres.2015.03.001")}.
Falkensteiner, M., Schellander, H., Hell, T. (2023) 'Accounting for seasonality in the metastatistical extreme value distribution', (Weather and Climate Extremes, 42, 2023, \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.wace.2023.100601")}).
See Also
fmev, fsmev
Examples
data(dailyrainfall)
filtered_data <- subset(
dailyrainfall,
as.numeric(format(dates, "%Y")) >= 1971 &
as.numeric(format(dates, "%Y")) <= 1978
)
fit <- ftmev(filtered_data, minyears = 5)
plot(fit, type = "rl")
# temporal trend of the Weibull parameters
pred <- predict(fit)
pred_year <- predict(fit, term = "year")
boxplot(c.pred ~ year, data = pred)
with(pred_year, lines(year - 1970,
c.pred.year,
type = "b",
pch = 20,
col = "red"))
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.