EnvStats: plotTolIntNparDesign – R documentation

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

plotTolIntNparDesign

Plots for a Sampling Design Based on a Nonparametric Tolerance Interval

Description

Create plots involving sample size (n), coverage (β), and confidence level (1-α) for a nonparametric tolerance interval.

Usage

plotTolIntNparDesign(x.var = "n", y.var = "conf.level", range.x.var = NULL, n = 25, 
    coverage = 0.95, conf.level = 0.95, ti.type = "two.sided", cov.type = "content", 
    ltl.rank = ifelse(ti.type == "upper", 0, 1), 
    n.plus.one.minus.utl.rank = ifelse(ti.type == "lower", 0, 1), 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), `"coverage"` (the coverage), and `"conf.level"` (the confidence level).
`y.var`	character string indicating what variable to use for the y-axis. Possible values are `"conf.level"` (the confidence level; the default), `"n"` (sample size), and `"coverage"` (the coverage).
`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="coverage"` or `x.var="conf"`, the default value is `c(0.5, 0.99)`.
`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"`.
`coverage`	numeric scalar between 0 and 1 specifying the coverage of the tolerance interval. The default value is `coverage=0.95`. This argument is ignored if `x.var="coverage"` or `y.var="coverage"`.
`conf.level`	a scalar between 0 and 1 indicating the confidence level associated with the tolerance interval. The default value is `conf.level=0.95`. This argument is ignored if `x.var="conf.level"` or `y.var="conf.level"`, or if `cov.type="expectation"`.
`ti.type`	character string indicating what kind of tolerance interval to compute. The possible values are `"two-sided"` (the default), `"lower"`, and `"upper"`.
`cov.type`	character string specifying the coverage type for the tolerance interval. The possible values are `"content"` (β-content; the default), and `"expectation"` (β-expectation).
`ltl.rank`	vector of positive integers indicating the rank of the order statistic to use for the lower bound of the tolerance interval. If `ti.type="two-sided"` or `ti.type="lower"`, the default value is `ltl.rank=1` (implying the minimum value of `x` is used as the lower bound of the tolerance interval). If `ti.type="upper"`, this argument is set equal to `0`.
`n.plus.one.minus.utl.rank`	vector of positive integers related to the rank of the order statistic to use for the upper bound of the tolerance interval. A value of `n.plus.one.minus.utl.rank=1` (the default) means use the first largest value, and in general a value of `n.plus.one.minus.utl.rank=`i means use the i'th largest value. If `ti.type="lower"`, this argument is set equal to `0`.
`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 tolIntNpar, tolIntNparConfLevel, tolIntNparCoverage, and tolIntNparN for information on how to compute a nonparametric tolerance interval, how the confidence level is computed when other quantities are fixed, how the coverage is computed when other quantites are fixed, and and how the sample size is computed when other quantities are fixed.

Value

plotTolIntNparDesign 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 tolIntNpar.

In the course of designing a sampling program, an environmental scientist may wish to determine the relationship between sample size, coverage, and confidence level if one of the objectives of the sampling program is to produce tolerance intervals. The functions tolIntNparN, tolIntNparCoverage, tolIntNparConfLevel, and plotTolIntNparDesign can be used to investigate these relationships for constructing nonparametric tolerance intervals.

Author(s)

Steven P. Millard (EnvStats@ProbStatInfo.com)

References

See the help file for tolIntNpar.

Examples

# Look at the relationship between confidence level and sample size for a two-sided 
  # nonparametric tolerance interval.

  dev.new()
  plotTolIntNparDesign()

  #==========

  # Plot confidence level vs. sample size for various values of coverage:

  dev.new()
  plotTolIntNparDesign(coverage = 0.7, ylim = c(0,1), main = "") 

  plotTolIntNparDesign(coverage = 0.8, add = TRUE, plot.col = "red") 

  plotTolIntNparDesign(coverage = 0.9, add = TRUE, plot.col = "blue") 

  legend("bottomright", c("coverage = 70%", "coverage = 80%", "coverage = 90%"), lty=1, 
    lwd = 3 * par("cex"), col = c("black", "red", "blue"), bty = "n") 

  title(main = paste("Confidence Level vs. Sample Size for Nonparametric TI", 
    "with Various Levels of Coverage", sep = "\n"))

  #==========

  # Example 17-4 on page 17-21 of USEPA (2009) uses copper concentrations (ppb) from 3 
  # background wells to set an upper limit for 2 compliance wells.  There are 6 observations 
  # per well, and the maximum value from the 3 wells is set to the 95% confidence upper 
  # tolerance limit, and we need to determine the coverage of this tolerance interval.  

  tolIntNparCoverage(n = 24, conf.level = 0.95, ti.type = "upper")
  #[1] 0.8826538

  # Here we will modify the example and look at confidence level versus coverage for 
  # a set sample size of n = 24.

  dev.new()
  plotTolIntNparDesign(x.var = "coverage", y.var = "conf.level", n = 24, ti.type = "upper")

  #==========

  # 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