propTestMdd.RdCompute the minimal detectable difference associated with a one- or two-sample proportion test, given the sample size, power, and significance level.
propTestMdd(n.or.n1, n2 = n.or.n1, p0.or.p2 = 0.5, alpha = 0.05, power = 0.95,
sample.type = "one.sample", alternative = "two.sided",
two.sided.direction = "greater", approx = TRUE,
correct = sample.type == "two.sample", warn = TRUE,
return.exact.list = TRUE, tol = 1e-07, maxiter = 1000)numeric vector of sample sizes. When sample.type="one.sample",
this argument denotes \(n\), the number of observations in the single sample.
When sample.type="two.sample", this argument denotes \(n_1\),
the number of observations from group 1.
Missing (NA), undefined (NaN), and infinite (Inf, -Inf) values are not allowed.
numeric vector of sample sizes for group 2. The default value is n2=n.or.n1.
This argument is ignored when sample.type="one.sample".
Missing (NA), undefined (NaN), and infinite (Inf, -Inf) values are not allowed.
numeric vector of proportions. When sample.type="one.sample",
this argument denotes the hypothesized value of \(p\), the probability of “success”.
When sample.type="two.sample", this argument denotes the value of \(p_2\),
the probability of “success” in group 2. The default value is p0.or.p2=0.5. Missing (NA), undefined (NaN), and infinite (Inf, -Inf) values are not allowed.
numeric vector of numbers between 0 and 1 indicating the Type I error level
associated with the hypothesis test. The default value is alpha=0.05.
numeric vector of numbers between 0 and 1 indicating the power associated with
the hypothesis test. The default value is power=0.95.
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 proportion.
When sample.type="two.sample", the computed power is based on a
hypothesis test for the difference between two proportions.
The default value is sample.type="one.sample".
character string indicating the kind of alternative hypothesis.
The possible values are "two.sided" (the default), "less", and
"greater".
character string indicating the direction (positive or negative) for the
minimal detectable difference when alternative="two.sided". When two.sided.direction="greater" (the default), the minimal
detectable difference is positive. When two.sided.direction="less",
the minimal detectable difference is negative. This argument
is ignored if alternative="less" or alternative="greater".
logical scalar indicating whether to compute the power based on the normal
approximation to the binomial distribution. The default value is approx=TRUE.
Currently, the exact method (approx=FALSE) is only available for the
one-sample case (i.e., sample.type="one.sample").
logical scalar indicating whether to use the continuity correction when approx=TRUE. The default value is approx=TRUE when sample.type="two.sample" and approx=FALSE when sample.type="one.sample". This argument is ignored when approx=FALSE.
logical scalar indicating whether to issue a warning. The default value is warn=TRUE. When approx=TRUE (power based on the normal approximation) and
warn=TRUE, a warning is issued for cases when the normal approximation to the
binomial distribution probably is not accurate. When approx=FALSE (power based on the exact test) and warn=TRUE,
a warning is issued when the user-supplied sample size is too small to
yield a significance level less than or equal to the user-supplied value of
alpha.
logical scalar relevant to the case when approx=FALSE
(i.e., when the power is based on the exact test). This argument indicates whether
to return a list containing extra information about the exact test in addition to
the power of the exact test. By default, propTestMdd returns only a vector
containing the computed minimal detectable difference(s) (see the VALUE section below).
When return.exact.list=TRUE (the default) and approx=FALSE, propTestMdd returns a list with components indicating the minimal detectable
difference(s), power of the exact test, the true significance level associated with
the exact test, and the critical values associated with the exact test (see the
DETAILS section for more information).
numeric scalar passed to the uniroot function that indicates the
tolerance to use in the search algorithm. The default value is tol=1e-7.
integer passed to the uniroot function that indicates the maximum
number of iterations to use in the search algorithm. The default value is
maxiter=1000.
If the arguments n.or.n1, n2, p0.or.p2, alpha, and
power are not all the same length, they are replicated to be the same
length as the length of the longest argument.
One-Sample Case (sample.type="one.sample")
The help file for propTestPower gives references that explain
how the power of the one-sample proportion test is computed based on the values of
\(p_0\) (the hypothesized value for \(p\), the probability of “success”),
\(p\) (the true value of \(p\)), the sample size \(n\), and the Type
I error level \(\alpha\). The function propTestMdd computes the value
of the minimal detectable difference \(p - p_0\) for specified values of
sample size, power, and Type I error level by calling the uniroot
function to perform a search.
Two-Sample Case (sample.type="two.sample")
The help file for propTestPower gives references that explain
how the power of the two-sample proportion test is computed based on the values of
\(p_1\) (the value of the probability of “success” for group 1),
\(p_2\) (the value of the probability of “success” for group 2),
the sample sizes for groups 1 and 2 (\(n_1\) and \(n_2\)), and the Type
I error level \(\alpha\). The function propTestMdd computes the value
of the minimal detectable difference \(p_1 - p_2\) for specified values of
sample size, power, and Type I error level by calling the uniroot
function to perform a search.
Approximate Test (approx=TRUE).
numeric vector of minimal detectable differences.
Exact Test (approx=FALSE).
If return.exact.list=FALSE, propTestMdd returns a numeric vector of
minimal detectable differences.
If return.exact.list=TRUE, propTestMdd returns a list with the
following components:
numeric vector of minimal detectable differences.
numeric vector of powers.
numeric vector containing the true significance levels.
Because of the discrete nature of the binomial distribution, the true significance
levels usually do not equal the significance level supplied by the user in the
argument alpha.
numeric vector of lower critical values for rejecting the null
hypothesis. If the observed number of "successes" is less than or equal to these values,
the null hypothesis is rejected. (Not present if alternative="greater".)
numeric vector of upper critical values for rejecting the null
hypothesis. If the observed number of "successes" is greater than these values,
the null hypothesis is rejected. (Not present if alternative="less".)
See the help file for propTestPower.
See the help file for propTestPower.
# Look at how the minimal detectable difference of the one-sample
# proportion test increases with increasing required power:
seq(0.5, 0.9, by = 0.1)
#> [1] 0.5 0.6 0.7 0.8 0.9
#[1] 0.5 0.6 0.7 0.8 0.9
mdd <- propTestMdd(n.or.n1 = 50, power = seq(0.5, 0.9, by=0.1))
round(mdd, 2)
#> [1] 0.14 0.16 0.17 0.19 0.22
#[1] 0.14 0.16 0.17 0.19 0.22
#----------
# Repeat the last example, but compute the minimal detectable difference
# based on the exact test instead of the approximation. Note that with a
# sample size of 50, the largest significance level less than or equal to
# 0.05 for the two-sided alternative is 0.03.
mdd.list <- propTestMdd(n.or.n1 = 50, power = seq(0.5, 0.9, by = 0.1),
approx = FALSE)
lapply(mdd.list, round, 2)
#> $delta
#> [1] 0.15 0.17 0.18 0.20 0.23
#>
#> $power
#> [1] 0.5 0.6 0.7 0.8 0.9
#>
#> $alpha
#> [1] 0.03 0.03 0.03 0.03 0.03
#>
#> $q.critical.lower
#> [1] 17 17 17 17 17
#>
#> $q.critical.upper
#> [1] 32 32 32 32 32
#>
#$delta
#[1] 0.15 0.17 0.18 0.20 0.23
#
#$power
#[1] 0.5 0.6 0.7 0.8 0.9
#
#$alpha
#[1] 0.03 0.03 0.03 0.03 0.03
#
#$q.critical.lower
#[1] 17 17 17 17 17
#
#$q.critical.upper
#[1] 32 32 32 32 32
#==========
# Look at how the minimal detectable difference for the two-sample
# proportion test decreases with increasing sample sizes. Note that for
# the specified significance level, power, and true proportion in group 2,
# no minimal detectable difference is attainable for a sample size of 10 in
# each group.
seq(10, 50, by=10)
#> [1] 10 20 30 40 50
#[1] 10 20 30 40 50
propTestMdd(n.or.n1 = seq(10, 50, by = 10), p0.or.p2 = 0.5,
sample.type = "two", alternative="greater")
#> Warning: Elements with a missing value (NA) indicate no attainable minimal detectable difference for the given values of 'n1', 'n2', 'p2', 'alpha', and 'power'
#> Warning: The sample sizes 'n1' and 'n2' are too small, relative to the computed value of 'p1' and the given value of 'p2', for the normal approximation to work well for the following element indices:
#> 2 3
#>
#> [1] NA 0.4726348 0.4023564 0.3557916 0.3221412
#[1] NA 0.4726348 0.4023564 0.3557916 0.3221412
#Warning messages:
#1: In propTestMdd(n.or.n1 = seq(10, 50, by = 10), p0.or.p2 = 0.5,
# sample.type = "two", :
# Elements with a missing value (NA) indicate no attainable minimal detectable
# difference for the given values of 'n1', 'n2', 'p2', 'alpha', and 'power'
#2: In propTestMdd(n.or.n1 = seq(10, 50, by = 10), p0.or.p2 = 0.5,
# sample.type = "two", :
# The sample sizes 'n1' and 'n2' are too small, relative to the computed value
# of 'p1' and the given value of 'p2', for the normal approximation to work
# well for the following element indices:
# 2 3
#----------
# Look at how the minimal detectable difference for the two-sample proportion
# test decreases with increasing values of Type I error:
mdd <- propTestMdd(n.or.n1 = 100, n2 = 120, p0.or.p2 = 0.4, sample.type = "two",
alpha = c(0.01, 0.05, 0.1, 0.2))
round(mdd, 2)
#> [1] 0.29 0.25 0.23 0.20
#[1] 0.29 0.25 0.23 0.20
#----------
# Clean up
#---------
rm(mdd, mdd.list)
#==========
# Modifying the example on pages 8-5 to 8-7 of USEPA (1989b), determine the
# minimal detectable difference to detect a difference in the proportion of
# detects of cadmium between the background and compliance wells. Set the
# compliance well to "group 1" and the background well to "group 2". Assume
# the true probability of a "detect" at the background well is 1/3, use a
# 5% significance level, use 80%, 90%, and 95% power, use the given sample
# sizes of 64 observations at the compliance well and 24 observations at the
# background well, and use the upper one-sided alternative (probability of a
# "detect" at the compliance well is greater than the probability of a "detect"
# at the background well).
# (The data are stored in EPA.89b.cadmium.df.)
#
# Note that the minimal detectable difference increases from 0.32 to 0.37 to 0.40 as
# the required power increases from 80% to 90% to 95%. Thus, in order to detect a
# difference in probability of detection between the compliance and background
# wells, the probability of detection at the compliance well must be 0.65, 0.70,
# or 0.74 (depending on the required power).
EPA.89b.cadmium.df
#> Cadmium.orig Cadmium Censored Well.type
#> 1 0.1 0.100 FALSE Background
#> 2 0.12 0.120 FALSE Background
#> 3 BDL 0.000 TRUE Background
#> 4 0.26 0.260 FALSE Background
#> 5 BDL 0.000 TRUE Background
#> 6 0.1 0.100 FALSE Background
#> 7 BDL 0.000 TRUE Background
#> 8 0.014 0.014 FALSE Background
#> 9 BDL 0.000 TRUE Background
#> 10 BDL 0.000 TRUE Background
#> 11 BDL 0.000 TRUE Background
#> 12 BDL 0.000 TRUE Background
#> 13 BDL 0.000 TRUE Background
#> 14 0.12 0.120 FALSE Background
#> 15 BDL 0.000 TRUE Background
#> 16 0.21 0.210 FALSE Background
#> 17 BDL 0.000 TRUE Background
#> 18 0.12 0.120 FALSE Background
#> 19 BDL 0.000 TRUE Background
#> 20 BDL 0.000 TRUE Background
#> 21 BDL 0.000 TRUE Background
#> 22 BDL 0.000 TRUE Background
#> 23 BDL 0.000 TRUE Background
#> 24 BDL 0.000 TRUE Background
#> 25 0.12 0.120 FALSE Compliance
#> 26 0.08 0.080 FALSE Compliance
#> 27 BDL 0.000 TRUE Compliance
#> 28 0.2 0.200 FALSE Compliance
#> 29 BDL 0.000 TRUE Compliance
#> 30 0.1 0.100 FALSE Compliance
#> 31 BDL 0.000 TRUE Compliance
#> 32 0.012 0.012 FALSE Compliance
#> 33 BDL 0.000 TRUE Compliance
#> 34 BDL 0.000 TRUE Compliance
#> 35 BDL 0.000 TRUE Compliance
#> 36 BDL 0.000 TRUE Compliance
#> 37 BDL 0.000 TRUE Compliance
#> 38 0.12 0.120 FALSE Compliance
#> 39 0.07 0.070 FALSE Compliance
#> 40 BDL 0.000 TRUE Compliance
#> 41 0.19 0.190 FALSE Compliance
#> 42 BDL 0.000 TRUE Compliance
#> 43 0.1 0.100 FALSE Compliance
#> 44 BDL 0.000 TRUE Compliance
#> 45 0.01 0.010 FALSE Compliance
#> 46 BDL 0.000 TRUE Compliance
#> 47 BDL 0.000 TRUE Compliance
#> 48 BDL 0.000 TRUE Compliance
#> 49 BDL 0.000 TRUE Compliance
#> 50 BDL 0.000 TRUE Compliance
#> 51 0.11 0.110 FALSE Compliance
#> 52 0.06 0.060 FALSE Compliance
#> 53 BDL 0.000 TRUE Compliance
#> 54 0.23 0.230 FALSE Compliance
#> 55 BDL 0.000 TRUE Compliance
#> 56 0.11 0.110 FALSE Compliance
#> 57 BDL 0.000 TRUE Compliance
#> 58 0.031 0.031 FALSE Compliance
#> 59 BDL 0.000 TRUE Compliance
#> 60 BDL 0.000 TRUE Compliance
#> 61 BDL 0.000 TRUE Compliance
#> 62 BDL 0.000 TRUE Compliance
#> 63 BDL 0.000 TRUE Compliance
#> 64 0.12 0.120 FALSE Compliance
#> 65 0.08 0.080 FALSE Compliance
#> 66 BDL 0.000 TRUE Compliance
#> 67 0.26 0.260 FALSE Compliance
#> 68 BDL 0.000 TRUE Compliance
#> 69 0.02 0.020 FALSE Compliance
#> 70 BDL 0.000 TRUE Compliance
#> 71 0.024 0.024 FALSE Compliance
#> 72 BDL 0.000 TRUE Compliance
#> 73 BDL 0.000 TRUE Compliance
#> 74 BDL 0.000 TRUE Compliance
#> 75 BDL 0.000 TRUE Compliance
#> 76 BDL 0.000 TRUE Compliance
#> 77 0.1 0.100 FALSE Compliance
#> 78 0.04 0.040 FALSE Compliance
#> 79 BDL 0.000 TRUE Compliance
#> 80 BDL 0.000 TRUE Compliance
#> 81 0.1 0.100 FALSE Compliance
#> 82 BDL 0.000 TRUE Compliance
#> 83 0.01 0.010 FALSE Compliance
#> 84 BDL 0.000 TRUE Compliance
#> 85 BDL 0.000 TRUE Compliance
#> 86 BDL 0.000 TRUE Compliance
#> 87 BDL 0.000 TRUE Compliance
#> 88 BDL 0.000 TRUE Compliance
# Cadmium.orig Cadmium Censored Well.type
#1 0.1 0.100 FALSE Background
#2 0.12 0.120 FALSE Background
#3 BDL 0.000 TRUE Background
# ..........................................
#86 BDL 0.000 TRUE Compliance
#87 BDL 0.000 TRUE Compliance
#88 BDL 0.000 TRUE Compliance
p.hat.back <- with(EPA.89b.cadmium.df,
mean(!Censored[Well.type=="Background"]))
p.hat.back
#> [1] 0.3333333
#[1] 0.3333333
p.hat.comp <- with(EPA.89b.cadmium.df,
mean(!Censored[Well.type=="Compliance"]))
p.hat.comp
#> [1] 0.375
#[1] 0.375
n.back <- with(EPA.89b.cadmium.df,
sum(Well.type == "Background"))
n.back
#> [1] 24
#[1] 24
n.comp <- with(EPA.89b.cadmium.df,
sum(Well.type == "Compliance"))
n.comp
#> [1] 64
#[1] 64
mdd <- propTestMdd(n.or.n1 = n.comp, n2 = n.back,
p0.or.p2 = p.hat.back, power = c(.80, .90, .95),
sample.type = "two", alternative = "greater")
round(mdd, 2)
#> [1] 0.32 0.37 0.40
#[1] 0.32 0.37 0.40
round(mdd + p.hat.back, 2)
#> [1] 0.65 0.70 0.73
#[1] 0.65 0.70 0.73
#----------
# Clean up
#---------
rm(p.hat.back, p.hat.comp, n.back, n.comp, mdd)