plot.ithresh: Plot diagnostics an ithresh object

Description Usage Arguments Details Value See Also Examples

View source: R/ithresh_methods.R

Description

plot method for class "ithresh". Produces an extreme value threshold diagnostic plot based on an analysis performed by ithresh. Can also be used to produce a plot of the posterior sample generated by ithresh for a particular training threshold.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
## S3 method for class 'ithresh'
plot(
  x,
  y,
  ...,
  which_v = NULL,
  prob = TRUE,
  top_scale = TRUE,
  add_legend = FALSE,
  legend_pos = "topleft",
  which_u = NULL
)

Arguments

x

an object of class "ithresh", a result of a call to ithresh.

y

Not used.

...

Additional arguments passed on to matplot and/or legend and/or axis. If which_u is supplied then these arguments are passed to plot.evpost.

which_v

A numeric scalar or vector.

If which_u is not supplied (a threshold diagnostic plot is required) which_v specifies the validation thresholds, that is, the components of x$v_vec, to include in the plot.

If which_u is supplied (a plot of a posterior sample for a given threshold is required) then which_v is a numeric scalar that indicates which element of object$v_vec is used in selecting a single threshold (if which_u = "best"). Note: the default, which_v = 1 gives the lowest of the validation thresholds in object$v_vec.

prob

A logical scalar. If TRUE then the levels of thresholds are represented by the proportion of observations that lie below a threshold. If prob = FALSE then the values of the thresholds are used.

top_scale

A logical scalar indicating Whether or not to add a scale to the top horizontal axis. If this is added it gives the threshold on the scale not chosen by prob.

add_legend

A logical scalar indicating whether or not to add a legend to the plot. If method = "cv" then the legend gives the levels of the validation thresholds.

legend_pos

The position of the legend (if required) specified using the argument x in legend.

which_u

Either a character scalar or a numeric scalar. If which_u is supplied then plot.evpost is used to produce a plot of the posterior sample generated using a particular training threshold. By default a scatter plot of the posterior sample of Generalized Pareto parameters is produced.

If which_u = "best" then the training threshold achieving the largest measure of predictive performance in object$pred_perf, based on the validation threshold selected using which_v, is used. See summary.ithresh to print the best thresholds for each validation threshold.

Otherwise, which_u is a numeric scalar that selects training threshold x$u_vec[which_u]. Therefore, which_u must be an integer in 1, ..., length(x$u_vec).

Details

Produces plots of the threshold weights, defined in equation (14) of Northrop et al. (2017), against training threshold. A line is produced for each of the validation thresholds chosen in which_v. The result is a plot like those in the top row of Figure 7 in Northrop et al. (2017).

It is possible that a curve on the plot may be incomplete. This indicates that, for a particular threshold level, a measure of predictive performance is -Inf. This occurs when an observation in the data lies above the estimated upper end point of the predictive distribution produced when this observation is removed.

Value

If which_u is supplied then the object with which plot.evpost was called is returned (invisibly). Otherwise, a list is returned (again invisibly) with two components. x is a vector containing the coordinates plotted on the (lower) horizontal axis. y is an length(u_vec) by n_v matrix of threshold weights obtained by normalising the columns of the matrix pred_perf returned by ithresh. See equation (14) of Northrop et al. (2017).

See Also

ithresh for threshold selection in the i.i.d. case based on leave-one-out cross-validation.

summary.ithresh Summarizing measures of threshold predictive performance.

print.ithresh Prints the threshold weights.

predict.ithresh for predictive inference for the largest value observed in N years.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# [Smoother plots result from making n larger than the default n = 1000.]

# Threshold diagnostic plot
u_vec_gom <- quantile(gom, probs = seq(0, 0.9, by = 0.05))
gom_cv <- ithresh(data = gom, u_vec = u_vec_gom, n_v = 3)
plot(gom_cv, lwd = 2, add_legend = TRUE, legend_pos = "topleft")
mtext("significant wave height / m", side = 3, line = 2.5)

# Plot of Generalized Pareto posterior sample at the best threshold
# (based on the lowest validation threshold)
plot(gom_cv, which_u = "best")
# See which threshold was used
summary(gom_cv)

# Plot of Generalized Pareto posterior sample at the highest threshold
n_u <- length(u_vec_gom)
plot(gom_cv, which_u = n_u, points_par = list(pch = 20, col = "grey"))

Example output

       v v quantile best u best u quantile index of u_vec
1 4.6070         80 3.1598              55             12
2 5.1302         85 3.1598              55             12
3 5.8246         90 3.1598              55             12

threshr documentation built on Jan. 13, 2021, 8:17 a.m.