RecordTest (version 2.0.0)

p.plot: Probabilities of Record Plots

Description

This function builds a ggplot object to display different functions of the record probabilities at time \(t\), \(p_t\). A graphical tool to study the hypothesis of the classical record model.

Usage

p.plot(
  X,
  plot = c("1", "2", "3"),
  record = c(FU = 1, FL = 1, BU = 1, BL = 1),
  point.col = c(FU = "red", FL = "blue", BU = "red", BL = "blue"),
  point.shape = c(FU = 19, FL = 19, BU = 4, BL = 4),
  conf.int = TRUE,
  conf.level = 0.9,
  conf.aes = c("ribbon", "errorbar"),
  conf.col = "gray69",
  smooth = TRUE,
  smooth.formula = y ~ x,
  smooth.method = stats::lm,
  smooth.weight = TRUE,
  smooth.linetype = c(FU = 1, FL = 1, BU = 2, BL = 2),
  ...
)

Arguments

X

A numeric vector, matrix (or data frame).

plot

One of the values "1", "2" or "3" (character or numeric class are both allowed). It determines the type of plot to be displayed (see Details).

record

Logical vector. Vector with four elements indicating if forward upper, forward lower, backward upper and backward lower are going to be shown, respectively. Logical values or 0,1 values are accepted.

point.col, point.shape

Vector with four elements indicating the color and shape of the points. Every one of the four elements represents forward upper, forward lower, backward upper and backward lower, respectively.

conf.int

Logical. Indicates if the CIs are also shown.

conf.level

(If conf.int == TRUE) Confidence level of the CIs.

conf.aes

(If conf.int == TRUE) A character string indicating the aesthetic to display for the CIs, "ribbon" (gray area) or "errorbar" (vertical lines).

conf.col

Color used to plot the expected value and (if conf.int == TRUE) CIs.

smooth

(If plot = 1 or 3) Logical. If TRUE, a smoothing in the probabilities is also plotted.

smooth.formula

(smooth = TRUE) formula to use in the smooth function, e.g., y ~ x, y ~ poly(x, 2, raw = TRUE), y ~ log(x).

smooth.method

(If smooth = TRUE) Smoothing method (function) to use, e.g., lm or loess.

smooth.weight

(If smooth = TRUE) Logical. If TRUE (the default) the smoothing is estimated with weights.

smooth.linetype

(If smooth = TRUE) Vector with four elements indicating the line type of the smoothing. Every one of the four elements represents forward upper, forward lower, backward upper and backward lower, respectively.

...

Further arguments to pass through the smooth (see ggplot2::geom_smooth).

Value

A ggplot object.

Details

Three different types of plots which aim to analyse the hypothesis of the classical record model using the record probabilities are implemented. Estimations of the record probabilities \(\hat p_t\) used in the plots are obtained as the proportion of records at time \(t\) in \(M\) vectors (columns of matrix X) (see p.record).

Type 1 is the plot of the observed values \(t \hat p_t\) versus time \(t\) (see p.regression.test for its associated test and details). The expected values under the classical record model are \(1\) for any value \(t\), so that a cloud of points around \(1\) and with no trend should be expected. The estimated values are plotted, together with binomial confidence intervals (CIs). In addition, a smoothing function can be fitted to the cloud of points.

Type 2 is the plot of the estimated record probabilities \(p_t\) versus time \(t\). The expected probabilities under the classical record model, \(p_t=1/t\), are also plotted, together with binomial CIs.

Type 3 is the same plot but on a logarithmic scale, so that the expected value is \(-\log(t)\). In this case, another smoothing function can be fitted to the cloud of points.

Type 1 plot was proposed by Cebri<U+00E1>n, Castillo-Mateo, As<U+00ED>n (2021), while type 2 and 3 appear in Benestad (2003, 2004) in Figures 8 and 9 (2003) and Figure 4 (2004).

References

Benestad RE (2003). <U+201C>How Often Can We Expect a Record Event?<U+201D> Climate Research, 25(1), 3<U+2013>13.

Benestad RE (2004). <U+201C>Record-Values, Nonstationarity Tests and Extreme Value Distributions.<U+201D> Global and Planetary Change, 44(1<U+2013>4), 11<U+2013>26.

Cebri<U+00E1>n A, Castillo-Mateo J, As<U+00ED>n J (2021). <U+201C>Record Tests to detect non stationarity in the tails with an application to climate change.<U+201D> Unpublished manuscript.

See Also

p.regression.test

Examples

# NOT RUN {
# three plots available
p.plot(ZaragozaSeries, plot = 1)
p.plot(ZaragozaSeries, plot = 2)
p.plot(ZaragozaSeries, plot = 3)

# Posible fits (plot 1):
#fit a line
p.plot(ZaragozaSeries, record = c(1,0,0,0))
# fit a second order polynomial
p.plot(ZaragozaSeries, record = c(1,0,0,0), 
  smooth.formula = y ~ poly(x, degree = 2))
# force the line to pass by E(t*p_t) = 1 when t = 1, i.e., E(t*p_t) = 1 + beta_1 * (t-1)
p.plot(ZaragozaSeries, record = c(1,0,0,0), 
  smooth.formula = y ~ I(x-1) - 1 + offset(rep(1, length(x))))
# force the second order polynomial pass by E(t*p_t) = 1 when t = 1
p.plot(ZaragozaSeries, record = c(1,0,0,0), 
  smooth.formula = y ~ I(x-1) + I(x^2-1) - 1 + offset(rep(1, length(x))))
# fit a loess
p.plot(ZaragozaSeries, record = c(1,0,0,0), 
  smooth.method = stats::loess, span = 0.25)
# }