% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/power.R
\name{mb_power}
\alias{mb_power}
\title{Power for a two-sample test}
\usage{
mb_power(
  n_per_group,
  effect_size = NULL,
  sd = 1,
  alpha = 0.05,
  sides = 2L,
  type = c("mean", "proportion"),
  p1 = NULL,
  p2 = NULL
)
}
\arguments{
\item{n_per_group}{Numeric. Sample size per arm.}

\item{effect_size}{Numeric. The standardised effect size:
Cohen's \code{d} for \code{type = "mean"}, or Cohen's \code{h} for
\code{type = "proportion"} (computed automatically if \code{p1} and \code{p2}
are supplied).}

\item{sd}{Numeric. Standard deviation, used only for \code{type = "mean"}. Default \code{1}, in which case \code{effect_size} is interpreted
in standard deviation units.}

\item{alpha}{Numeric in \verb{(0, 1)}. Significance level. Default
\code{0.05}.}

\item{sides}{Integer. \code{2} (two-sided, default) or \code{1} (one-sided).}

\item{type}{Character. \code{"mean"} (default) or \code{"proportion"}.}

\item{p1, p2}{Optional numeric in \verb{(0, 1)}. If both supplied (and
\code{type = "proportion"}), the function computes Cohen's \code{h} and
ignores \code{effect_size}.}
}
\value{
Numeric scalar in \verb{(0, 1)}: the power.
}
\description{
Computes statistical power for a two-sample test of equal-sized
arms, using the large-sample normal approximation. Supports tests
of two means (with a common standard deviation) or two
proportions (using Cohen's \code{h} arcsine effect size).
}
\details{
For two means, power is
\deqn{1 - \Phi(z_{1-\alpha/s} - d\sqrt{n/2}) + \Phi(-z_{1-\alpha/s} - d\sqrt{n/2})}
where \eqn{s} is \code{sides} and \eqn{d} is the standardised effect.
For two proportions, the effect uses the arcsine variance-stabilising
transform: \eqn{h = 2\arcsin\sqrt{p_1} - 2\arcsin\sqrt{p_2}}.

Approximation note: this implementation uses the large-sample
normal approximation. The standard alternative (used by
\pkg{pwr}::\code{\link[pwr]{pwr.t.test}}) uses the noncentral
t-distribution. For typical evaluation sample sizes
(\code{n_per_group >= 50}) the two agree to within 1-2 percentage
points of power; for \code{n_per_group < 30} the discrepancy is
larger and \pkg{pwr} should be preferred. magentabook ships
equivalence tests against \pkg{pwr} (see
\code{tests/testthat/test-pwr-equivalence.R}).
}
\examples{
mb_power(n_per_group = 200, effect_size = 0.3)
mb_power(n_per_group = 500, type = "proportion", p1 = 0.40, p2 = 0.50)
}
\references{
Cohen, J. (1988). Statistical Power Analysis for the
Behavioral Sciences (2nd ed.). Lawrence Erlbaum.

Champely, S. (2020). pwr: Basic Functions for Power Analysis.
R package version 1.3-0.
\url{https://CRAN.R-project.org/package=pwr}.

HM Treasury (2020). The Magenta Book: Central Government
Guidance on Evaluation. Chapter on impact evaluation, section
on power analysis.
\url{https://www.gov.uk/government/publications/the-magenta-book}.
}
\seealso{
\code{\link[=mb_mde]{mb_mde()}}, \code{\link[=mb_sample_size]{mb_sample_size()}}, \code{\link[=mb_cluster_design]{mb_cluster_design()}}.

Other power: 
\code{\link{mb_cluster_design}()},
\code{\link{mb_icc_reference}()},
\code{\link{mb_mde}()},
\code{\link{mb_sample_size}()},
\code{\link{mb_stepped_wedge}()}
}
\concept{power}
