EnvStats: plotPredIntNparSimultaneousDesign – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

plotPredIntNparSimultaneousDesign

Plots for a Sampling Design Based on a Simultaneous Nonparametric Prediction Interval

Description

Create plots involving sample size (n), number of future observations (m), minimum number of future observations the interval should contain (k), number of future sampling occasions (r), and confidence level (1-α) for a simultaneous nonparametric prediction interval.

Usage

plotPredIntNparSimultaneousDesign(x.var = "n", y.var = "conf.level", 
    range.x.var = NULL, n = max(25, lpl.rank + n.plus.one.minus.upl.rank + 1), 
    n.median = 1, k = 1, m = ifelse(x.var == "k", ceiling(max.x), 1), r = 2, 
    rule = "k.of.m", conf.level = 0.95, pi.type = "upper", 
    lpl.rank = ifelse(pi.type == "upper", 0, 1), 
    n.plus.one.minus.upl.rank = ifelse(pi.type == "lower", 0, 1), n.max = 5000, 
    maxiter = 1000, integrate.args.list = NULL, plot.it = TRUE, add = FALSE, 
    n.points = 100, plot.col = "black", plot.lwd = 3 * par("cex"), plot.lty = 1, 
    digits = .Options$digits, cex.main = par("cex"), ..., main = NULL, 
    xlab = NULL, ylab = NULL, type = "l")

Arguments

`x.var`	character string indicating what variable to use for the x-axis. Possible values are `"n"` (sample size; the default), `"conf.level"` (the confidence level), `"k"` (minimum number of future observations the interval should contain), `"m"` (number of future observations), and `"r"` (number of future sampling occasions).
`y.var`	character string indicating what variable to use for the y-axis. Possible values are `"conf.level"` (confidence level; the default), and `"n"` (sample size).
`range.x.var`	numeric vector of length 2 indicating the range of the x-variable to use for the plot. The default value depends on the value of `x.var`. When `x.var="n"` the default value is `c(2,50)`. When `x.var="conf.level"`, the default value is `c(0.5, 0.99)`. When `x.var="k"`, `x.var="m"`, or `x.var="r"`, the default value is c(1, 20).
`n`	numeric scalar indicating the sample size. The default value is `max(25, lpl.rank + n.plus.one.minus.upl.rank + 1)`. Missing (`NA`), undefined (`NaN`), and infinite (`Inf`, `-Inf`) values are not allowed. This argument is ignored if either `x.var="n"` or `y.var="n"`.
`n.median`	positive odd integer specifying the sample size associated with the future medians. The default value is `n.median=1` (i.e., individual observations). Note that all future medians must be based on the same sample size.
`k`	for the k-of-m rule (`rule="k.of.m"`), a positive integer specifying the minimum number of observations (or medians) out of m observations (or medians) (all obtained on one future sampling “occassion”) the prediction interval should contain. The default value is `k=1`. This argument is ignored when the argument `rule` is not equal to `"k.of.m"`.
`m`	positive integer specifying the maximum number of future observations (or medians) on one future sampling “occasion”. The default value is `m=2`, except when `rule="Modified.CA"`, in which case this argument is ignored and `m` is automatically set equal to `4`.
`r`	positive integer specifying the number of future sampling “occasions”. The default value is `r=1`.
`rule`	character string specifying which rule to use. The possible values are `"k.of.m"` (k-of-m rule; the default), `"CA"` (California rule), and `"Modified.CA"` (modified California rule). See the DETAILS section below for more information.
`conf.level`	numeric scalar between 0 and 1 indicating the confidence level associated with the prediction interval. The default value is `conf.level=0.95`.
`pi.type`	character string indicating what kind of prediction interval to compute. The possible values are `"upper"` (the default) and `"lower"`.
`lpl.rank`	non-negative integer indicating the rank of the order statistic to use for the lower bound of the prediction interval. If `pi.type="lower"`, the default value is `lpl.rank=1` (implying the minimum value is used as the lower bound of the prediction interval). If `pi.type="upper"`, this argument is set equal to `0`.
`n.plus.one.minus.upl.rank`	non-negative integer related to the rank of the order statistic to use for the upper bound of the prediction interval. A value of `n.plus.one.minus.upl.rank=1` (the default) means use the first largest value, and in general a value of `n.plus.one.minus.upl.rank=`i means use the i'th largest value. If `pi.type="lower"`, this argument is set equal to `0`.
`n.max`	numeric scalar indicating the maximum sample size to consider when `y.var="n"`. This argument is used in the search algorithm to determine the required sample size. The default value is `n.max=5000`.
`maxiter`	positive integer indicating the maximum number of iterations to use in the `uniroot` search algorithm when `y.var="n"`. The default value is `maxiter=1000`.
`integrate.args.list`	list of arguments to supply to the `integrate` function. The default value is `NULL`.
`plot.it`	a logical scalar indicating whether to create a plot or add to the existing plot (see `add`) on the current graphics device. If `plot.it=FALSE`, no plot is produced, but a list of (x,y) values is returned (see VALUE). The default value is `plot.it=TRUE`.
`add`	a logical scalar indicating whether to add the design plot to the existing plot (`add=TRUE`), or to create a plot from scratch (`add=FALSE`). The default value is `add=FALSE`. This argument is ignored if `plot.it=FALSE`.
`n.points`	a numeric scalar specifying how many (x,y) pairs to use to produce the plot. There are `n.points` x-values evenly spaced between `range.x.var[1]` and `range.x.var[2]`. The default value is `n.points=100`.
`plot.col`	a numeric scalar or character string determining the color of the plotted line or points. The default value is `plot.col="black"`. See the entry for `col` in the help file for `par` for more information.
`plot.lwd`	a numeric scalar determining the width of the plotted line. The default value is `3*par("cex")`. See the entry for `lwd` in the help file for `par` for more information.
`plot.lty`	a numeric scalar determining the line type of the plotted line. The default value is `plot.lty=1`. See the entry for `lty` in the help file for `par` for more information.
`digits`	a scalar indicating how many significant digits to print out on the plot. The default value is the current setting of `options("digits")`.
`cex.main, main, xlab, ylab, type, ...`	additional graphical parameters (see `par`).

Details

See the help file for predIntNparSimultaneous, predIntNparSimultaneousConfLevel, and
predIntNparSimultaneousN for information on how to compute a simultaneous nonparametric prediction interval, how the confidence level is computed when other quantities are fixed, and how the sample size is computed when other quantities are fixed.

Value

plotPredIntNparSimultaneousDesign invisibly returns a list with components x.var and y.var, giving coordinates of the points that have been or would have been plotted.

Note

See the help file for predIntNparSimultaneous.

Author(s)

Steven P. Millard (EnvStats@ProbStatInfo.com)

References

See the help file for predIntNparSimultaneous.

Examples

# For the 1-of-3 rule with r=20 future sampling occasions, look at the 
  # relationship between confidence level and sample size for a one-sided 
  # upper simultaneous nonparametric prediction interval.

  dev.new()
  plotPredIntNparSimultaneousDesign(k = 1, m = 3, r = 20, range.x.var = c(2, 20))

  #==========

  # Plot confidence level vs. sample size for various values of number of 
  # future sampling occasions (r):

  dev.new()
  plotPredIntNparSimultaneousDesign(m = 3, r = 10, rule = "CA", 
    ylim = c(0, 1), main = "") 

  plotPredIntNparSimultaneousDesign(m = 3, r = 20, rule = "CA", add = TRUE, 
    plot.col = "red") 

  plotPredIntNparSimultaneousDesign(m = 3, r = 30, rule = "CA", add = TRUE, 
    plot.col = "blue") 

  legend("bottomright", c("r=10", "r=20", "r=30"), lty = 1, lwd = 3 * par("cex"), 
    col = c("black", "red", "blue"), bty = "n") 

  title(main = paste("Confidence Level vs. Sample Size for Simultaneous", 
    "Nonparametric PI with Various Values of r", sep="\n"))

  #==========

  # Modifying Example 19-5 of USEPA (2009, p. 19-33), plot confidence level 
  # versus sample size (number of background observations requried) for 
  # a 1-of-3 plan assuming r = 10 compliance wells (future sampling occasions).
  
  dev.new()
  plotPredIntNparSimultaneousDesign(k = 1, m = 3, r = 10, rule = "k.of.m")

  #==========

  # Clean up
  #---------
  graphics.off()

EnvStats

Package for Environmental Statistics, Including US EPA Guidance

v2.4.0

GPL (>= 3)

Authors

Steven P. Millard [aut], Alexander Kowarik [ctb, cre] (<https://orcid.org/0000-0001-8598-4130>)

Initial release

2020-10-20