R: Plots for a Sampling Design Based on a One- or Two-Sample...

plotTTestLnormAltDesign {EnvStats}

R Documentation

Plots for a Sampling Design Based on a One- or Two-Sample t-Test, Assuming Lognormal Data

Description

Create plots involving sample size, power, ratio of means, coefficient of variation, and significance level for a one- or two-sample t-test, assuming lognormal data.

Usage

  plotTTestLnormAltDesign(x.var = "n", y.var = "power", range.x.var = NULL, 
    n.or.n1 = 25, n2 = n.or.n1, 
    ratio.of.means = switch(alternative, greater = 2, less = 0.5, 
      two.sided = ifelse(two.sided.direction == "greater", 2, 0.5)), 
    cv = 1, alpha = 0.05, power = 0.95, 
    sample.type = ifelse(!missing(n2), "two.sample", "one.sample"), 
    alternative = "two.sided", two.sided.direction = "greater", approx = FALSE, 
    round.up = FALSE, n.max = 5000, tol = 1e-07, maxiter = 1000, plot.it = TRUE, 
    add = FALSE, n.points = 50, 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), `"ratio.of.means"` (minimal or maximal detectable ratio of means), `"cv"` (coefficient of variaiton), `"power"` (power of the test), and `"alpha"` (significance level of the test).
`y.var`	character string indicating what variable to use for the y-axis. Possible values are `"power"` (power of the test; the default), `"ratio.of.means"` (minimal or maximal detectable ratio of means), 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="ratio.of.means"` and `alternative="greater"` or `alternative="two.sided"` and `two.sided.direction="greater"`, the default value is `c(1, 2)`. When `x.var="delta"` and `alternative="less"` or `alternative="two.sided"` and `two.sided.direction="less"`, the default value is `c(0.5, 1)`. When `x.var="cv"` the default value is `c(0.5, 2)`. When `x.var="power"` the default value is `c(alpha + .Machine$double.eps, 0.95)`. When `x.var="alpha"`, the default value is `c(0.01, 0.2)`.
`n.or.n1`	numeric scalar indicating the sample size. The default value is `n.or.n1=25`. When `sample.type="one.sample"`, `n.or.n1` denotes the number of observations in the single sample. When `sample.type="two.sample"`, `n.or.n1` denotes the number of observations from group 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"`.
`n2`	numeric scalar indicating the sample size for group 2. The default value is the value of `n.or.n1`. Missing (`NA`), undefined (`NaN`), and infinite (`Inf`, `-Inf`) values are not allowed. This argument is ignored when `sample.type="one.sample"`.
`ratio.of.means`	numeric scalar specifying the ratio of the first mean to the second mean. When `sample.type="one.sample"`, this is the ratio of the population mean to the hypothesized mean. When `sample.type="two.sample"`, this is the ratio of the mean of the first population to the mean of the second population. When `alternative="greater"` or `alternative="two.sided"` and `two.sided.direction="greater"`, the default value is `ratio.of.means=2`. When `alternative="less"` or `alternative="two.sided"` and `two.sided.direction="less"`, the default value is `ratio.of.means=0.5`. This argument is ignored when `x.var="ratio.of.means"` or `y.var="ratio.of.means"`.
`cv`	numeric scalar: a positive value specifying the coefficient of variation. When `sample.type="one.sample"`, this is the population coefficient of variation. When `sample.type="two.sample"`, this is the coefficient of variation for both the first and second population. The default value is `cv=1`.
`alpha`	numeric scalar between 0 and 1 indicating the Type I error level associated with the hypothesis test. The default value is `alpha=0.05`.
`power`	numeric scalar between 0 and 1 indicating the power associated with the hypothesis test. The default value is `power=0.95`.
`sample.type`	character string indicating whether to compute power based on a one-sample or two-sample hypothesis test. When `sample.type="one.sample"`, the computed power is based on a hypothesis test for a single mean. When `sample.type="two.sample"`, the computed power is based on a hypothesis test for the difference between two means. The default value is `sample.type="one.sample"` unless the argument `n2` is supplied.
`alternative`	character string indicating the kind of alternative hypothesis. The possible values are `"two.sided"` (the default), `"greater"`, and `"less"`.
`two.sided.direction`	character string indicating the direction (greater than 1 or less than 1) for the detectable ratio of means when `alternative="two.sided"`. When `two.sided.direction="greater"` (the default), the detectable ratio of means is greater than 1. When `two.sided.direction="less"`, the detectable ratio of means is less than 1 (but greater than 0). This argument is ignored if `alternative="less"` or `alternative="greater"`.
`approx`	logical scalar indicating whether to compute the power based on an approximation to the non-central t-distribution. The default value is `approx=FALSE`.
`round.up`	logical scalar indicating whether to round up the values of the computed sample size(s) to the next smallest integer. The default value is `TRUE`.
`n.max`	for the case when `y.var="n"`, a positive integer greater than 1 indicating the maximum sample size when `sample.type="one.sample"` or the maximum sample size for group 1 when `sample.type="two.sample"`. The default value is `n.max=5000`.
`tol`	numeric scalar indicating the toloerance to use in the `uniroot` search algorithm. The default value is `tol=1e-7`.
`maxiter`	positive integer indicating the maximum number of iterations argument to pass to the `uniroot` function. The default value is `maxiter=1000`.
`plot.it`	a logical scalar indicating whether to create a new 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 files for tTestLnormAltPower, tTestLnormAltN, and tTestLnormAltRatioOfMeans for information on how to compute the power, sample size, or ratio of means for a one- or two-sample t-test assuming lognormal data.

Value

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

Examples

  # Look at the relationship between power and sample size for a two-sample t-test, 
  # assuming lognormal data, a ratio of means of 2, a coefficient of variation 
  # of 1, and a 5% significance level:

  dev.new()
  plotTTestLnormAltDesign(sample.type = "two")

  #----------

  # For a two-sample t-test based on lognormal data, plot sample size vs. the 
  # minimal detectable ratio for various levels of power, assuming a coefficient 
  # of variation of 1 and using a 5% significance level:

  dev.new()
  plotTTestLnormAltDesign(x.var = "ratio.of.means", y.var = "n", 
    range.x.var = c(1.5, 2), sample.type = "two", ylim = c(20, 120), main="") 

  plotTTestLnormAltDesign(x.var = "ratio.of.means", y.var = "n", 
    range.x.var = c(1.5, 2), sample.type="two", power = 0.9, 
    add = TRUE, plot.col = "red") 

  plotTTestLnormAltDesign(x.var = "ratio.of.means", y.var = "n", 
    range.x.var = c(1.5, 2), sample.type="two", power = 0.8, 
    add = TRUE, plot.col = "blue") 

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

  title(main = paste("Sample Size vs. Ratio of Lognormal Means for", 
    "Two-Sample t-Test, with CV=1, Alpha=0.05 and Various Powers", 
    sep="\n")) 

  #==========

  # The guidance document Soil Screening Guidance: Technical Background Document 
  # (USEPA, 1996c, Part 4) discusses sampling design and sample size calculations 
  # for studies to determine whether the soil at a potentially contaminated site 
  # needs to be investigated for possible remedial action. Let 'theta' denote the 
  # average concentration of the chemical of concern.  The guidance document 
  # establishes the following goals for the decision rule (USEPA, 1996c, p.87):
  #
  #     Pr[Decide Don't Investigate | theta > 2 * SSL] = 0.05
  #
  #     Pr[Decide to Investigate | theta <= (SSL/2)] = 0.2
  #
  # where SSL denotes the pre-established soil screening level.
  #
  # These goals translate into a Type I error of 0.2 for the null hypothesis
  #
  #     H0: [theta / (SSL/2)] <= 1
  #
  # and a power of 95% for the specific alternative hypothesis
  #
  #     Ha: [theta / (SSL/2)] = 4
  #
  # Assuming a lognormal distribution, a coefficient of variation of 2, and the above 
  # values for Type I error and power, create a performance goal diagram 
  # (USEPA, 1996c, p.89) showing the power of a one-sample test versus the minimal 
  # detectable ratio of theta/(SSL/2) when the sample size is 6 and the exact power 
  # calculations are used.

  dev.new()
  plotTTestLnormAltDesign(x.var = "ratio.of.means", y.var = "power", 
    range.x.var = c(1, 5), n.or.n1 = 6, cv = 2, alpha = 0.2, 
    alternative = "greater", approx = FALSE, ylim = c(0.2, 1), 
    xlab = "theta / (SSL/2)") 

  #==========

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

[Package EnvStats version 2.8.1 Index]

Plots for a Sampling Design Based on a One- or Two-Sample t-Test, Assuming Lognormal Data

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples