| % File src/library/stats/man/power.prop.test.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright (C) 1995-2017 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{power.prop.test} |
| \alias{power.prop.test} |
| \encoding{UTF-8} |
| \title{Power Calculations for Two-Sample Test for Proportions} |
| \description{ |
| Compute the power of the two-sample test for proportions, or determine |
| parameters to obtain a target power. |
| } |
| \usage{ |
| power.prop.test(n = NULL, p1 = NULL, p2 = NULL, sig.level = 0.05, |
| power = NULL, |
| alternative = c("two.sided", "one.sided"), |
| strict = FALSE, tol = .Machine$double.eps^0.25) |
| } |
| \arguments{ |
| \item{n}{number of observations (per group)} |
| \item{p1}{probability in one group} |
| \item{p2}{probability in other group} |
| \item{sig.level}{significance level (Type I error probability)} |
| \item{power}{power of test (1 minus Type II error probability)} |
| \item{alternative}{one- or two-sided test. Can be abbreviated.} |
| \item{strict}{use strict interpretation in two-sided case} |
| \item{tol}{numerical tolerance used in root finding, the default |
| providing (at least) four significant digits.} |
| } |
| \details{ |
| Exactly one of the parameters \code{n}, \code{p1}, \code{p2}, |
| \code{power}, and \code{sig.level} must be passed as NULL, and that |
| parameter is determined from the others. Notice that \code{sig.level} |
| has a non-NULL default so \code{NULL} must be explicitly passed if you |
| want it computed. |
| |
| If \code{strict = TRUE} is used, the power will include the probability of |
| rejection in the opposite direction of the true effect, in the two-sided |
| case. Without this the power will be half the significance level if the |
| true difference is zero. |
| |
| Note that not all conditions can be satisfied, e.g., for \preformatted{power.prop.test(n=30, p1=0.90, p2=NULL, power=0.8, strict=TRUE)} |
| there is no proportion \code{p2} between \code{p1 = 0.9} and 1, as |
| you'd need a sample size of at least \eqn{n = 74} to yield the |
| desired power for \eqn{(p1,p2) = (0.9, 1)}. |
| |
| For these impossible conditions, currently a warning |
| (\code{\link{warning}}) is signalled which may become an error |
| (\code{\link{stop}}) in the future. |
| } |
| \value{ |
| Object of class \code{"power.htest"}, a list of the arguments |
| (including the computed one) augmented with \code{method} and |
| \code{note} elements. |
| } |
| \author{Peter Dalgaard. Based on previous work by Claus |
| \enc{Ekstrøm}{Ekstroem}} |
| |
| \note{ |
| \code{\link{uniroot}} is used to solve power equation for unknowns, so |
| you may see errors from it, notably about inability to bracket the |
| root when invalid arguments are given. If one of \code{p1} and |
| \code{p2} is computed, then \eqn{p1 < p2} is assumed and will hold, |
| but if you specify both, \eqn{p2 \le p1}{p2 <= p1} is allowed. |
| } |
| |
| \seealso{\code{\link{prop.test}}, \code{\link{uniroot}}} |
| |
| \examples{ |
| power.prop.test(n = 50, p1 = .50, p2 = .75) ## => power = 0.740 |
| power.prop.test(p1 = .50, p2 = .75, power = .90) ## => n = 76.7 |
| power.prop.test(n = 50, p1 = .5, power = .90) ## => p2 = 0.8026 |
| power.prop.test(n = 50, p1 = .5, p2 = 0.9, power = .90, sig.level=NULL) |
| ## => sig.l = 0.00131 |
| power.prop.test(p1 = .5, p2 = 0.501, sig.level=.001, power=0.90) |
| ## => n = 10451937 |
| try( |
| power.prop.test(n=30, p1=0.90, p2=NULL, power=0.8) |
| ) # a warning (which may become an error) |
| ## Reason: |
| power.prop.test( p1=0.90, p2= 1.0, power=0.8) ##-> n = 73.37 |
| } |
| \keyword{ htest } |