Quantiles of the Maximum on a Period of Time

Compute the quantiles for the random maximum on a given period or collection of blocks of interest.

# S3 method for TVGEV
quantMax(
  object,
  prob,
  date = NULL,
  level = 0.95,
  psi = NULL,
  confintMethod = "delta",
  out = c("data.frame", "array"),
  trace = 1L,
  ...
)

Arguments

object: A TVGEV model object.
prob: A numeric vector giving the (non-exceedance) probabilities at which the quantiles will be computed.
date: A vector that can be coerced to the class "Date" giving the beginnings of the blocks for a period of interest.
level: The confidence level.
psi: Optional vector of coefficients. Caution not tested yet.
confintMethod: Character indicating the method to be used for the confidence intervals on the quantiles.
out: Character indicating what type of object will be returned. When out is "data.frame" the output actually has the (S3) class "quantMax.TVGEV" inheriting from "data.frame". A few methods exist for this class.
trace: Integer level of verbosity.
...: Not used.

Value

An object with its class depending on the value of

out.

out = "data.frame" An object inheriting from the "data.frame" class which can be used in methods such as autoplot.
out = "array" A 3-dimensional array with dimensions, probability, type of result (Quantile, Lower or Upper confidence limit) and confidence level.

Details

Let $M^\star := \max_{b} Y_b$ be the maximum over the blocks $b$ of interest. Since the blocks are assumed to be independent the distribution function of $M^\star$ is given by $$ F_{M^\star}(m^\star; \, \boldsymbol{\psi}) = \prod_{b} F_{\texttt{GEV}}(m^\star; \, \boldsymbol{\theta}_b) $$ and it depends on the vector $\boldsymbol{\psi}$ of the model parameters through $\boldsymbol{\theta}_b(\boldsymbol{\psi})$. For a given probability $p$, the corresponding quantile $q_{M^\star}(p;\,\boldsymbol{\psi})$ is the solution $m^\star$ of $F^\star(m^\star;\,\boldsymbol{\psi}) = p$. The derivative of the quantile w.r.t. $\boldsymbol{\psi}$ can be obtained by the implicit function theorem and then be used for the inference e.g., using the "delta method".

Examples

df <- within(TXMax_Dijon, Date <- as.Date(sprintf("%4d-01-01", Year)))
## fit a TVGEV model. Only the location parameter is TV.
tv <- TVGEV(data = df, response = "TXMax", date = "Date",
            design = breaksX(date = Date, breaks = "1970-01-01", degree = 1),
            loc = ~ t1 + t1_1970)
qM1 <- quantMax(tv, level = c(0.95, 0.70))
date2 <- as.Date(sprintf("%4d-01-01", 2025:2054))
qM2 <- quantMax(tv, date = date2, level = c(0.95, 0.70))
qM2
#>      Prob ProbExc    Quant        L        U Level
#> 1  0.8000  0.2000 41.59590 40.39165 42.80014  0.70
#> 2  0.8100  0.1900 41.63825 40.42609 42.85041  0.70
#> 3  0.8200  0.1800 41.68217 40.46162 42.90272  0.70
#> 4  0.8300  0.1700 41.72783 40.49836 42.95730  0.70
#> 5  0.8400  0.1600 41.77542 40.53644 43.01440  0.70
#> 6  0.8500  0.1500 41.82519 40.57603 43.07435  0.70
#> 7  0.8600  0.1400 41.87743 40.61732 43.13754  0.70
#> 8  0.8700  0.1300 41.93247 40.66053 43.20442  0.70
#> 9  0.8800  0.1200 41.99075 40.70594 43.27556  0.70
#> 10 0.8900  0.1100 42.05279 40.75390 43.35168  0.70
#> 11 0.9000  0.1000 42.11926 40.80485 43.43367  0.70
#> 12 0.9100  0.0900 42.19102 40.85933 43.52272  0.70
#> 13 0.9200  0.0800 42.26924 40.91808 43.62041  0.70
#> 14 0.9300  0.0700 42.35551 40.98211 43.72891  0.70
#> 15 0.9400  0.0600 42.45210 41.05284 43.85136  0.70
#> 16 0.9500  0.0500 42.56248 41.13239 43.99257  0.70
#> 17 0.9600  0.0400 42.69228 41.22417 44.16039  0.70
#> 18 0.9700  0.0300 42.85171 41.33426 44.36916  0.70
#> 19 0.9800  0.0200 43.06269 41.47537 44.65001  0.70
#> 20 0.9900  0.0100 43.39066 41.68416 45.09716  0.70
#> 21 0.9950  0.0050 43.68291 41.85907 45.50675  0.70
#> 22 0.9980  0.0020 44.02264 42.04852 45.99676  0.70
#> 23 0.9990  0.0010 44.24913 42.16572 46.33255  0.70
#> 24 0.9999  0.0001 44.84933 42.43190 47.26675  0.70
#> 25 0.8000  0.2000 41.59590 39.31860 43.87320  0.95
#> 26 0.8100  0.1900 41.63825 39.34598 43.93053  0.95
#> 27 0.8200  0.1800 41.68217 39.37403 43.99032  0.95
#> 28 0.8300  0.1700 41.72783 39.40282 44.05283  0.95
#> 29 0.8400  0.1600 41.77542 39.43243 44.11841  0.95
#> 30 0.8500  0.1500 41.82519 39.46295 44.18744  0.95
#> 31 0.8600  0.1400 41.87743 39.49448 44.26038  0.95
#> 32 0.8700  0.1300 41.93247 39.52714 44.33781  0.95
#> 33 0.8800  0.1200 41.99075 39.56109 44.42041  0.95
#> 34 0.8900  0.1100 42.05279 39.59651 44.50907  0.95
#> 35 0.9000  0.1000 42.11926 39.63362 44.60490  0.95
#> 36 0.9100  0.0900 42.19102 39.67270 44.70935  0.95
#> 37 0.9200  0.0800 42.26924 39.71411 44.82438  0.95
#> 38 0.9300  0.0700 42.35551 39.75832 44.95269  0.95
#> 39 0.9400  0.0600 42.45210 39.80600 45.09820  0.95
#> 40 0.9500  0.0500 42.56248 39.85808 45.26688  0.95
#> 41 0.9600  0.0400 42.69228 39.91599 45.46857  0.95
#> 42 0.9700  0.0300 42.85171 39.98211 45.72131  0.95
#> 43 0.9800  0.0200 43.06269 40.06097 46.06442  0.95
#> 44 0.9900  0.0100 43.39066 40.16356 46.61777  0.95
#> 45 0.9950  0.0050 43.68291 40.23391 47.13191  0.95
#> 46 0.9980  0.0020 44.02264 40.28945 47.75583  0.95
#> 47 0.9990  0.0010 44.24913 40.30926 48.18901  0.95
#> 48 0.9999  0.0001 44.84933 40.27782 49.42084  0.95
gg <- autoplot(qM2, fillConf = TRUE)
gg <- gg + ggtitle("Quantile of the maximum over years 2025-2054")
gg

## Use the 'autolayer' method for a quick comparison 
qM3 <-  quantMax(tv,
                 date = as.Date(sprintf("%4d-01-01", 2025:2035)),
                 level = c(0.95, 0.70))

gg + autolayer(qM3, colour = "SpringGreen3", linetype = "dashed")

## Compare with a simulation. Note that 'sim' has class "bts"  and
## is essentially a numeric matrix. Increas 'nsim' to get a more
## precise estimate of the high quantiles
sim <- simulate(tv, newdate = date2, nsim = 10000)
M <- apply(sim, 2, max)
probs <- c(0.9, 0.95, 0.98, 0.99, 0.995, 0.998)
qSim <- quantile(M, prob = probs)
dfSim <- data.frame(Prob = probs, ProbExc = 1 - probs, Quant = qSim)
gg + geom_point(data = dfSim, mapping = aes(x = ProbExc, y = Quant))