The R Project SVN R

Rev

Rev 68948 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 68948 Rev 73869
Line 1... Line 1...
1 
% File src/library/stats/man/power.prop.test.Rd
 1 
% File src/library/stats/man/power.prop.test.Rd
2 
% Part of the R package, https://www.R-project.org
 2 
% Part of the R package, https://www.R-project.org
3 
% Copyright (C) 1995-2014 R Core Team
 3 
% Copyright (C) 1995-2017 R Core Team
4 
% Distributed under GPL 2 or later
 4 
% Distributed under GPL 2 or later
5 
 
 5 
 
6 
\name{power.prop.test}
 6 
\name{power.prop.test}
7 
\alias{power.prop.test}
 7 
\alias{power.prop.test}
8 
\encoding{UTF-8}
 8 
\encoding{UTF-8}
Line 29... Line 29...
29 
    providing (at least) four significant digits.}
 29 
    providing (at least) four significant digits.}
30 
}
 30 
}
31 
\details{
 31 
\details{
32 
  Exactly one of the parameters \code{n}, \code{p1}, \code{p2},
 32 
  Exactly one of the parameters \code{n}, \code{p1}, \code{p2},
33 
  \code{power}, and \code{sig.level} must be passed as NULL, and that
 33 
  \code{power}, and \code{sig.level} must be passed as NULL, and that
34 
  parameter is determined from the others. Notice that \code{sig.level}
 34 
  parameter is determined from the others.  Notice that \code{sig.level}
35 
  has a non-NULL default so NULL must be explicitly passed if you want
 35 
  has a non-NULL default so \code{NULL} must be explicitly passed if you
36 
  it  computed.
 36 
  want it computed.
37 
 
 37 
 
38 
  If \code{strict = TRUE} is used, the power will include the probability of
 38 
  If \code{strict = TRUE} is used, the power will include the probability of
39 
  rejection in the opposite direction of the true effect, in the two-sided
 39 
  rejection in the opposite direction of the true effect, in the two-sided
40 
  case. Without this the power will be half the significance level if the
 40 
  case.  Without this the power will be half the significance level if the
41 
  true difference is zero.
 41 
  true difference is zero.
- 
 
 42 
 
- 
 
 43 
  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)}
- 
 
 44 
  there is no proportion \code{p2} between \code{p1 = 0.9} and 1, as
- 
 
 45 
  you'd need a sample size of at least \eqn{n = 74} to yield the
- 
 
 46 
  desired power for \eqn{(p1,p2) = (0.9, 1)}.
- 
 
 47 
 
- 
 
 48 
  For these impossible conditions, currently a warning
- 
 
 49 
  (\code{\link{warning}}) is signalled which may become an error
- 
 
 50 
  (\code{\link{stop}}) in the future.
42 
}
 51 
}
43 
\value{
 52 
\value{
44 
  Object of class \code{"power.htest"}, a list of the arguments
 53 
  Object of class \code{"power.htest"}, a list of the arguments
45 
  (including the computed one) augmented with \code{method} and
 54 
  (including the computed one) augmented with \code{method} and
46 
  \code{note} elements.
 55 
  \code{note} elements.
47 
}
 56 
}
48 
\author{Peter Dalgaard.  Based on previous work by Claus
 57 
\author{Peter Dalgaard.  Based on previous work by Claus
49 
  \enc{Ekstrøm}{Ekstroem}}
 58 
  \enc{Ekstrøm}{Ekstroem}}
50 
 
 59 
 
51 
\note{
 60 
\note{
52 
  \code{uniroot} is used to solve power equation for unknowns, so
 61 
  \code{\link{uniroot}} is used to solve power equation for unknowns, so
53 
  you may see errors from it, notably about inability to bracket the
 62 
  you may see errors from it, notably about inability to bracket the
54 
  root when invalid arguments are given.  If one of them is computed
 63 
  root when invalid arguments are given.   If one of \code{p1} and
55 
  \code{p1 < p2} will hold, although this is not enforced when both are
 64 
  \code{p2} is computed, then \eqn{p1 < p2} is assumed and will hold,
56 
  specified.
 65 
  but if you specify both, \eqn{p2 \le p1}{p2 <= p1} is allowed.
57 
}
 66 
}
58 
 
 67 
 
59 
\seealso{\code{\link{prop.test}}, \code{\link{uniroot}}}
 68 
\seealso{\code{\link{prop.test}}, \code{\link{uniroot}}}
60 
 
 69 
 
61 
\examples{
 70 
\examples{
Line 64... Line 73...
64 
power.prop.test(n = 50, p1 = .5, power = .90)    ## =>    p2 = 0.8026
 73 
power.prop.test(n = 50, p1 = .5, power = .90)    ## =>    p2 = 0.8026
65 
power.prop.test(n = 50, p1 = .5, p2 = 0.9, power = .90, sig.level=NULL)
 74 
power.prop.test(n = 50, p1 = .5, p2 = 0.9, power = .90, sig.level=NULL)
66 
                                                 ## => sig.l = 0.00131
 75 
                                                 ## => sig.l = 0.00131
67 
power.prop.test(p1 = .5, p2 = 0.501, sig.level=.001, power=0.90)
 76 
power.prop.test(p1 = .5, p2 = 0.501, sig.level=.001, power=0.90)
68 
                                                 ## => n = 10451937
 77 
                                                 ## => n = 10451937
- 
 
 78 
try(
- 
 
 79 
 power.prop.test(n=30, p1=0.90, p2=NULL, power=0.8)
- 
 
 80 
) # a warning  (which may become an error)
- 
 
 81 
## Reason:
- 
 
 82 
power.prop.test(      p1=0.90, p2= 1.0, power=0.8) ##-> n = 73.37
69 
}
 83 
}
70 
\keyword{ htest }
 84 
\keyword{ htest }