Package 'pwrss'

Description

Conversion from a correlation to a z-value (Fisher's z-transformation)

Usage

cor.to.z(rho, verbose = 1)

Arguments

Value

Examples

cor.to.z(rho = 0.1)
cor.to.z(rho = 0.5)
cor.to.z(rho = 0.9)
cor.to.z(rho = 0.99)

Description

Conversion from a correlation Difference to Cohen's q

Usage

cors.to.q(rho1, rho2, verbose = 1)

Arguments

Value

Examples

cors.to.q(rho2 = 0.5712027, rho1 = 0.50)
cors.to.q(rho2 = 0.6907068, rho1 = 0.50)
cors.to.q(rho2 = 0.7815365, rho1 = 0.50)

Description

Helper function to convert Cohen's d to common language effect size (or vice versa). The result is the probability of superiority for independent samples. It can be interpreted as the probability that a randomly selected observation from Group 1 exceeds a randomly selected observation from Group 2. The rationale is the same for paired-samples and one-sample designs, but the interpretation differs: For paired samples, it can be interpreted as the probability that the difference score (i.e., the score under Condition 1 minus the score under Condition 2) is greater than zero for a randomly selected individual. For a one-sample design, it can be interpreted as the probability that a randomly selected observation is greater than the reference value (e.g., 0).

Usage

d.to.cles(d, design = c("independent", "paired", "one.sample"), verbose = 1)

Arguments

Value

Examples

d.to.cles(0.20) # small
d.to.cles(0.50) # medium
d.to.cles(0.80) # large

cles.to.d(0.5562315)
cles.to.d(0.6381632)
cles.to.d(0.7141962)

Description

Conversion from Eta-squared to Cohen's f

Usage

etasq.to.f(eta.squared, verbose = 1)

Arguments

Value

References

Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd ed.). Lawrence Erlbaum Associates.

Examples

etasq.to.f(eta.squared = 0.01) # small
etasq.to.f(eta.squared = 0.06) # medium
etasq.to.f(eta.squared = 0.14) # large

Description

Conversion between Cohen's f and Eta-squared

Usage

f.to.etasq(f, verbose = 1)

Arguments

Value

References

Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd ed.). Lawrence Erlbaum Associates.

Examples

f.to.etasq(f = 0.10) # small
f.to.etasq(f = 0.25) # medium
f.to.etasq(f = 0.40) # large

Description

Helper function to convert between Cohen's f and R-squared.

Usage

f.to.rsq(f, r.squared.full = NULL, verbose = 0)

Arguments

Value

References

Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd ed.). Lawrence Erlbaum Associates.

Selya, A. S., Rose, J. S., Dierker, L. C., Hedeker, D., & Mermelstein, R. J. (2012). A practical guide to calculating Cohen's f2, a measure of local effect size, from PROC MIXED. Frontiers in Psychology, 3, Article 111. https://doi.org/10.3389/fpsyg.2012.00111

Examples

f.to.rsq(f = 0.14) # small
  f.to.rsq(f = 0.39) # medium
  f.to.rsq(f = 0.59) # large

Description

Helper function to construct the default contrast coefficients for various coding schemes.

Validated using lm() and aov() functions.

Usage

factorial.contrasts(
  factor.levels = c(3, 2),
  coding.scheme = rep("deviation", length(factor.levels)),
  base = factor.levels,
  intercept = FALSE,
  verbose = 1
)

Arguments

Details

Note that R has a partial matching feature which allows you to specify shortened versions of arguments, such as factor instead of factor.levels, or such as cod or coding instead of coding.scheme.

Value

Examples

###################################################
############### dummy coding scheme ###############
####################################################

# one factor w/ 3 levels
contrast.object <- factorial.contrasts(factor.levels = 3,
                                       coding = "treatment")
# model matrix
contrast.object$model.matrix

# contrast matrix
contrast.object$contrast.matrix

#######################################################
###############  deviation coding scheme ##############
#######################################################

# especially useful for factorial designs
# two factors w/ 2 and 3 levels, respectively
contrast.object <- factorial.contrasts(factor.levels = c(2, 3),
                                       coding = "sum")

# model matrix
contrast.object$model.matrix

# contrast matrix
contrast.object$contrast.matrix


######################################################
###############  Helmert coding scheme ###############
######################################################

# one factor w/ 3 levels
contrast.object <- factorial.contrasts(factor.levels = 3,
                                       coding = "helmert")

# model matrix
contrast.object$model.matrix

# contrast matrix
contrast.object$contrast.matrix

#########################################################
###############  polynomial coding scheme ###############
#########################################################

# one factor w/ 3 levels
contrast.object <- factorial.contrasts(factor.levels = 3,
                                       coding = "poly")

# model matrix
contrast.object$model.matrix

# contrast matrix
contrast.object$contrast.matrix

Description

Inflate Sample Size for Attrition

Usage

inflate.sample(n, rate = 0.05, ceil.n = TRUE, verbose = 1)

Arguments

Value

inflated sample size.

Examples

inflate.sample(n = 100, rate = 0.05)

Description

Helper function to converts joint probabilities to marginal probabilities for the McNemar test applied to paired binary data.

Usage

joint.probs.2x2(prob1, prob2, rho = 0.5, verbose = 1)

Arguments

Value

References

Zhang, S., Cao, J., and Ahn, C. (2017). Inference and sample size calculation for clinical trials with incomplete observations of paired binary outcomes. Statistics in Medicine, 36(4), 581-591. https://doi.org/10.1002/sim.7168

Examples

# example data for a matched case-control design
# subject  case     control
# <int>    <dbl>    <dbl>
#   1        1        1
#   2        0        1
#   3        1        0
#   4        0        1
#   5        1        1
#   ...     ...      ...
#   100      0        0

# example summary stats
# prob1 = mean(case) which is 0.55
# prob2 = mean(control) which is 0.45
# rho = cor(case, control) which is 0.4141414


# example data for a before-after design
# subject  before   after
# <int>    <dbl>    <dbl>
#   1        1        1
#   2        0        1
#   3        1        0
#   4        0        1
#   5        1        1
#   ...     ...      ...
#   100      0        0

# example summary stats
# prob1 = mean(after) which is 0.55
# prob2 = mean(before) which is 0.45
# rho = cor(after, before) which is 0.4141414

# convert to a 2 x 2 frequency table
freqs <- matrix(c(30, 10, 20, 40), nrow = 2, ncol = 2)
colnames(freqs) <- c("control_1", "control_0")
rownames(freqs) <- c("case_1", "case_0")
freqs

# convert to a 2 x 2 proportion table
props <- freqs / sum(freqs)
props

# discordant pairs (0 and 1, or 1 and 0) in 'props' matrix
# are the sample estimates of prob01 and prob10


# we may not have 2 x 2 joint probs
# convert marginal probs to joint probs using summary stats
jp <- joint.probs.2x2(prob1 = 0.55, # mean of case (or after)
                          prob2 = 0.45, # mean of matched control (or before)
                          # correlation b/w matched case-control / before-after
                          rho = 0.4141414)

# required sample size for exact test
# assuming prob01 and prob10 are population parameters
power.exact.mcnemar(prob01 = jp$prob01,
                    prob10 = jp$prob10,
                    power = 0.80, alpha = 0.05,
                    method = "exact")

# convert joint probs to marginal probs and calc phi coefficient (rho)
# these values can be used in other procedures
marginal.probs.2x2(prob11 = 0.35, # mean of case (or after)
                    prob10 = 0.20, # mean of matched control (or before)
                    prob01 = 0.10,
                    prob00 = 0.35)

Description

Helper function to converts marginal probabilities to joint probabilities for the McNemar test applied to paired binary data.

Usage

marginal.probs.2x2(prob11, prob10, prob01, prob00, verbose = 1)

Arguments

Value

References

Zhang, S., Cao, J., and Ahn, C. (2017). Inference and sample size calculation for clinical trials with incomplete observations of paired binary outcomes. Statistics in Medicine, 36(4), 581-591. https://doi.org/10.1002/sim.7168

Examples

# example data for a matched case-control design
# subject  case     control
# <int>    <dbl>    <dbl>
#   1        1        1
#   2        0        1
#   3        1        0
#   4        0        1
#   5        1        1
#   ...     ...      ...
#   100      0        0

# example summary stats
# prob1 = mean(case) which is 0.55
# prob2 = mean(control) which is 0.45
# rho = cor(case, control) which is 0.4141414


# example data for a before-after design
# subject  before   after
# <int>    <dbl>    <dbl>
#   1        1        1
#   2        0        1
#   3        1        0
#   4        0        1
#   5        1        1
#   ...     ...      ...
#   100      0        0

# example summary stats
# prob1 = mean(after) which is 0.55
# prob2 = mean(before) which is 0.45
# rho = cor(after, before) which is 0.4141414

# convert to a 2 x 2 frequency table
freqs <- matrix(c(30, 10, 20, 40), nrow = 2, ncol = 2)
colnames(freqs) <- c("control_1", "control_0")
rownames(freqs) <- c("case_1", "case_0")
freqs

# convert to a 2 x 2 proportion table
props <- freqs / sum(freqs)
props

# discordant pairs (0 and 1, or 1 and 0) in 'props' matrix
# are the sample estimates of prob01 and prob10


# we may not have 2 x 2 joint probs
# convert marginal probs to joint probs using summary stats
jp <- joint.probs.2x2(prob1 = 0.55, # mean of case (or after)
                          prob2 = 0.45, # mean of matched control (or before)
                          # correlation b/w matched case-control / before-after
                          rho = 0.4141414)

# required sample size for exact test
# assuming prob01 and prob10 are population parameters
power.exact.mcnemar(prob01 = jp$prob01,
                    prob10 = jp$prob10,
                    power = 0.80, alpha = 0.05,
                    method = "exact")

# convert joint probs to marginal probs and calc phi coefficient (rho)
# these values can be used in other procedures
marginal.probs.2x2(prob11 = 0.35, # mean of case (or after)
                    prob10 = 0.20, # mean of matched control (or before)
                    prob01 = 0.10,
                    prob00 = 0.35)

Description

Helper function to convert means and standard deviations to Cohen's d.

Usage

means.to.d(
  mu1,
  mu2 = 0,
  sd1 = 1,
  sd2 = 1,
  n.ratio = 1,
  n2 = 10000000000,
  paired = FALSE,
  rho.paired = 0.5,
  verbose = 1
)

Arguments

Value

Examples

# means and standard deviations from independent samples
means.to.d(mu1 = 20, mu2 = 17.5,
           sd1 = 5, sd2 = 15,
           n2 = 30, n.ratio = 1)

# means and standard deviations from paired samples
means.to.d(mu1 = 20, mu2 = 17.5,
           sd1 = 5, sd2 = 15,
           n2 = 30, n.ratio = 1,
           paired = TRUE,
           rho.paired = 0.50)

Description

Calculates Cohen's f or Eta-squared for one-way ANOVA/ANCOVA. Set k.cov = 0 for one-way ANOVA (without any pretest or covariate adjustment). Set k.cov > 0 in combination with r.squared > 0 for one-way ANCOVA (with pretest or covariate adjustment).

Usage

means.to.etasq(
  mu.vector,
  sd.vector,
  n.vector,
  k.covariates = 0,
  r.squared = 0,
  factor.levels = NULL,
  verbose = 1
)

Arguments

Details

Note that R has a partial matching feature which allows you to specify shortened versions of arguments, such as mu or mu.vec instead of mu.vector, or such as k or k.cov instead of k.covariates.

Value

References

Keppel, G., & Wickens, T. D. (2004). Design and analysis: A researcher's handbook (4th ed.). Pearson.

Examples

means.to.etasq(mu.vector = c(0.50, 0), # marginal means
               sd.vector = c(1, 1), # unadjusted standard deviation
               n.vector = c(33, 33), # sample size (will be calculated)
               k.cov = 1, # number of covariates
               r.squared = 0.50)

Description

Calculates power or find Probability (Non-Centrality) for the generic binomial test with (optional) Type 1 and Type 2 error plots.

Usage

power.binom.test(
  power = NULL,
  size = NULL,
  prob = NULL,
  null.prob = 0.5,
  req.sign = "+",
  alpha = 0.05,
  alternative = c("two.sided", "one.sided", "two.one.sided"),
  plot = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Value

Examples

# one-sided
power.binom.test(size = 200, prob = 0.6, null.prob = 0.5, alpha = 0.05,
                 alternative = "one.sided")
power.binom.test(power = 0.80, size = 200, req.sign = "+", null.prob = 0.5,
                 alpha = 0.05, alternative = "one.sided")

# two-sided
power.binom.test(size = 200, prob = 0.4, null.prob = 0.5, alpha = 0.05,
                 alternative = "two.sided")
power.binom.test(power = 0.80, size = 200, req.sign = "+", null.prob = 0.5,
                 alpha = 0.05, alternative = "two.sided")

# equivalence
power.binom.test(size = 200, prob = 0.5, null.prob = c(0.4, 0.6),
                 alpha = 0.05, alternative = "two.one.sided")
power.binom.test(power = 0.80, size = 200, req.sign = "0",
                 null.prob = c(0.4, 0.6), alpha = 0.05,
                 alternative = "two.one.sided")

Description

Calculates power, sample size or effect size (only one can be NULL at a time) for Chi-square goodness-of-fit or independence tests.

Usage

power.chisq.gof(
  w = NULL,
  null.w = 0,
  df,
  n = NULL,
  power = NULL,
  alpha = 0.05,
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

• NB: The pwrss.chisq.gofit() function is deprecated. However, it will remain available as a wrapper for the power.chisq.gof() function during a transition period.

Value

References

Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd ed.). Lawrence Erlbaum Associates.

Examples

# ---------------------------------------------------------#
# Example 1: Cohen's W                                     #
# goodness-of-fit test for 1 x k or k x 1 table            #
# How many subjects are needed to claim that               #
# girls choose STEM related majors less than males?       #
# ---------------------------------------------------------#

## Option 1: Use cell probabilities
## from https://www.aauw.org/resources/research/the-stem-gap/
## 28 percent of the  workforce in STEM field is women
prob.vector <- c(0.28, 0.72)
null.prob.vector <- c(0.50, 0.50)
probs.to.w(prob.vector, null.prob.vector)

power.chisq.gof(w = 0.44, df = 1, power = 0.80, alpha = 0.05)


# ---------------------------------------------------------#
# Example 2: Phi Coefficient (or Cramer's V or Cohen's W)  #
# test of independence for 2 x 2 contingency tables        #
# How many subjects are needed to claim that               #
# girls are underdiagnosed with ADHD?                      #
# ---------------------------------------------------------#

## from http://archive.today/E2hqM
## 5.6 percent of girls and 13.2 percent of boys are diagnosed with ADHD
prob.matrix <- rbind(c(0.056, 0.132),
                     c(0.944, 0.868))
colnames(prob.matrix) <- c("Girl", "Boy")
rownames(prob.matrix) <- c("ADHD", "No ADHD")
prob.matrix

probs.to.w(prob.matrix)

power.chisq.gof(w = 0.1302134, df = 1, power = 0.80, alpha = 0.05)


# --------------------------------------------------------#
# Example 3: Cramer's V (or Cohen's W)                    #
# test of independence for j x k contingency tables       #
# How many subjects are needed to detect the relationship #
# between depression severity and gender?                 #
# --------------------------------------------------------#

## from https://doi.org/10.1016/j.jad.2019.11.121
prob.matrix <- cbind(c(0.6759, 0.1559, 0.1281, 0.0323, 0.0078),
                     c(0.6771, 0.1519, 0.1368, 0.0241, 0.0101))
rownames(prob.matrix) <- c("Normal", "Mild", "Moderate",
                           "Severe", "Extremely Severe")
colnames(prob.matrix) <- c("Female", "Male")
prob.matrix

probs.to.w(prob.matrix)

power.chisq.gof(w = 0.03022008, df = 4, power = 0.80, alpha = 0.05)

Description

Determines power, the non-centrality parameter (NCP) for the generic chi-square test with (optional) Type 1 and Type 2 error plots.

Usage

power.chisq.test(
  power = NULL,
  ncp = NULL,
  null.ncp = 0,
  df = NULL,
  alpha = 0.05,
  plot = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Value

Examples

# power is defined as the probability of observing a test statistics greater
# than the critical value
power.chisq.test(ncp = 20, df = 100, alpha = 0.05)
power.chisq.test(power = 0.80, df = 100, alpha = 0.05)
power.chisq.test(power = 0.80, ncp = 20, alpha = 0.05)

Description

Calculates power or sample size for Fisher's exact test on independent binary outcomes. Approximate and exact methods are available.

Validated using the PASS documentation and G*Power.

Usage

power.exact.fisher(
  prob1 = NULL,
  prob2 = NULL,
  req.sign = "+",
  n.ratio = 1,
  n2 = NULL,
  power = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided"),
  method = c("exact", "approximate"),
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Value

References

Bennett, B. M., & Hsu, P. (1960). On the power function of the exact test for the 2 x 2 contingency table. Biometrika, 47(3/4), 393-398. https://doi.org/10.2307/2333309

Fisher, R. A. (1935). The logic of inductive inference. Journal of the Royal Statistical Society, 98(1), 39-82. https://doi.org/10.2307/2342435

Examples

# example data for a randomized controlled trial
# subject  group    success
# <int>    <dbl>      <dbl>
#   1        1          1
#   2        0          1
#   3        1          0
#   4        0          1
#   5        1          1
#   ...     ...        ...
#   100      0          0

# prob1 = mean(success | group = 1)
# prob2 = mean(success | group = 0)

# post-hoc exact power
power.exact.fisher(prob1 = 0.60, prob2 = 0.40, n2 = 50)

# we may have 2 x 2 joint probs such as
# -------------------------------------
#             | group (1) | group (0) |
# -------------------------------------
# success (1) |  0.24    |   0.36     |
# -------------------------------------
# success (0) |  0.16    |   0.24     |
# -------------------------------------

# convert joint probs to marginal probs
marginal.probs.2x2(prob11 = 0.24, prob10 = 0.36,
                   prob01 = 0.16, prob00 = 0.24)

Description

Calculates power or sample size for McNemar's test on paired binary outcomes. Approximate and exact methods are available (check references for details).

Validated using the PASS documentation and G*Power.

Usage

power.exact.mcnemar(
  prob10 = NULL,
  prob01 = NULL,
  req.sign = "+",
  n.paired = NULL,
  power = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided"),
  method = c("exact", "approximate"),
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Value

References

Bennett, B. M., & Underwood, R. E. (1970). 283. Note: On McNemar's Test for the 2 * 2 Table and Its Power Function. Biometrics, 26(2), 339-343. https://doi.org/10.2307/2529083

Connor, R. J. (1987). Sample size for testing differences in proportions for the paired-sample design. Biometrics, 43(1), 207-211. https://doi.org/10.2307/2531961

Duffy, S. W. (1984). Asymptotic and exact power for the McNemar test and its analogue with R controls per case. Biometrics, 40(4) 1005-1015. https://doi.org/10.2307/2531151

McNemar, Q. (1947). Note on the sampling error of the difference between correlated proportions or percentages. Psychometrika, 12(2), 153-157. https://doi.org/10.1007/BF02295996

Miettinen, O. S. (1968). The matched pairs design in the case of all-or-none responses. Biometrics, 24(2), 339-352. https://doi.org/10.2307/2528039

Examples

# example data for a matched case-control design
# subject  case     control
# <int>    <dbl>    <dbl>
#   1        1        1
#   2        0        1
#   3        1        0
#   4        0        1
#   5        1        1
#   ...     ...      ...
#   100      0        0

# example data for a before-after design
# subject  before   after
# <int>    <dbl>    <dbl>
#   1        1        1
#   2        0        1
#   3        1        0
#   4        0        1
#   5        1        1
#   ...     ...      ...
#   100      0        0

# convert to a 2 x 2 frequency table
freqs <- matrix(c(30, 10, 20, 40), nrow = 2, ncol = 2)
colnames(freqs) <- c("control_1", "control_0")
rownames(freqs) <- c("case_1", "case_0")
freqs

# convert to a 2 x 2 proportion table
props <- freqs / sum(freqs)
props

# discordant pairs (0 and 1, or 1 and 0) in 'props' matrix
# are the sample estimates of prob01 and prob10

# post-hoc exact power
power.exact.mcnemar(prob10 = 0.20, prob01 = 0.10,
                    n.paired = 100, alpha = 0.05,
                    alternative = "two.sided", method = "exact")

# required sample size for exact test
# assuming prob01 and prob10 are population parameters
power.exact.mcnemar(prob10 = 0.20, prob01 = 0.10,
                    power = 0.80, alpha = 0.05,
                    alternative = "two.sided", method = "exact")

# we may not have 2 x 2 joint probs
# convert marginal probs to joint probs
joint.probs.2x2(prob1 = 0.55, # mean of case group (or after)
                prob2 = 0.45, # mean of matched control group (or before)
                # correlation between matched case-control or before-after
                rho = 0.4141414
)

Description

Calculates power, sample size, or minimum detectable correlation (only one can be NULL at a time) to test a (Pearson) correlation against a constant using exact method described in Barabesi and Greco (2002).

Formulas are validated using G*Power.

Usage

power.exact.onecor(
  rho = NULL,
  req.sign = "+",
  null.rho = 0,
  n = NULL,
  n.max = 10000,
  power = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided"),
  verbose = 1,
  utf = FALSE
)

Arguments

Value

References

Barabesi, L., & Greco, L. (2002). A Note on the Exact Computation of the Student t, Snedecor F and Sample Correlation Coefficient Distribution Functions. Journal of the Royal Statistical Society. Series D (The Statistician), 51(1), 105–110. https://www.jstor.org/stable/3650394

Examples

# expected correlation is 0.20 and it is different from 0
# it could be 0.20 as well as -0.20
power.exact.onecor(rho = 0.20,
                   power = 0.80,
                   alpha = 0.05,
                   alternative = "two.sided")

# expected correlation is 0.20 and it is greater than 0
power.exact.onecor(rho = 0.20,
                   power = 0.80,
                   alpha = 0.05,
                   alternative = "one.sided")

Description

Calculates power, sample size or effect size (only one can be NULL at a time) for test of a proportion against a constant using the exact method.

Formulas are validated using PASS documentation.

Usage

power.exact.oneprop(
  prob = NULL,
  req.sign = "+",
  null.prob = 0.5,
  n = NULL,
  power = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided", "two.one.sided"),
  verbose = 1,
  utf = FALSE
)

Arguments

Value

References

Bulus, M., & Polat, C. (2023). pwrss R paketi ile istatistiksel guc analizi [Statistical power analysis with pwrss R package]. Ahi Evran Universitesi Kirsehir Egitim Fakultesi Dergisi, 24(3), 2207-2328. https://doi.org/10.29299/kefad.1209913

Examples

# power'
power.exact.oneprop(prob = 0.45, null.prob = 0.50,
                    alpha = 0.05, n = 500,
                    alternative = "one.sided")

# sample size
power.exact.oneprop(prob = 0.45, null.prob = 0.50,
                    alpha = 0.05, power = 0.80,
                    alternative = "one.sided")

Description

Calculates power or sample size (only one can be NULL at a time) for two proportions using the exact method. The function is a wrapper for power.exact.mcnemar (if paired == TRUE), or power.exact.fisher (if paired == FALSE)

Validated via G*Power and PASS documentation.

Usage

power.exact.twoprops(
  prob1 = NULL,
  prob2 = NULL,
  req.sign = "+",
  n.ratio = 1,
  n2 = NULL,
  power = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided"),
  paired = FALSE,
  rho.paired = 0.5,
  method = c("exact", "approximate"),
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Value

References

Bulus, M., & Polat, C. (2023). pwrss R paketi ile istatistiksel guc analizi [Statistical power analysis with pwrss R package]. Ahi Evran Universitesi Kirsehir Egitim Fakultesi Dergisi, 24(3), 2207-2328. https://doi.org/10.29299/kefad.1209913

Examples

# power
  power.exact.twoprops(prob1 = 0.70, prob2 = 0.60,
                       alpha = 0.05, n2 = 500,
                       alternative = "one.sided")

  power.exact.twoprops(prob1 = 0.70, prob2 = 0.60,
                       alpha = 0.05, n2 = 500,
                       alternative = "one.sided",
                       paired = TRUE)

  # sample size
  power.exact.twoprops(prob1 = 0.70, prob2 = 0.60,
                       alpha = 0.05, power = 0.80,
                       alternative = "one.sided")

  power.exact.twoprops(prob1 = 0.70, prob2 = 0.60,
                       alpha = 0.05, power = 0.80,
                       alternative = "one.sided",
                       paired = TRUE)

Description

Calculates power, sample size or effect size for one-way, two-way, or three-way ANOVA/ANCOVA. Set k.covariates = 0 for ANOVA, and k.covariates > 0 for ANCOVA. Note that in the latter, the effect size (eta.squared should be obtained from the relevant ANCOVA model, which is already adjusted for the explanatory power of covariates (thus, an additional R-squared argument is not required as an input).

Formulas are validated using G*Power and tables in the PASS documentation.

Usage

power.f.ancova(
  eta.squared = NULL,
  null.eta.squared = 0,
  factor.levels = 2,
  target.effect = NULL,
  k.covariates = 0,
  n.total = NULL,
  power = NULL,
  alpha = 0.05,
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

Note that R has a partial matching feature which allows you to specify shortened versions of arguments, such as mu or mu.vec instead of mu.vector, or such as k or k.covariates instead of k.covariates.

Value

References

Bulus, M., & Polat, C. (2023). pwrss R paketi ile istatistiksel guc analizi [Statistical power analysis with pwrss R package]. Ahi Evran Universitesi Kirsehir Egitim Fakultesi Dergisi, 24(3), 2207-2328. https://doi.org/10.29299/kefad.1209913

Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd ed.). Lawrence Erlbaum Associates.

Examples

#############################################
#              one-way ANOVA                #
#############################################

# Cohen's d = 0.50 between treatment and control
# translating into eta-squared = 0.059

# estimate sample size using ANOVA approach
power.f.ancova(eta.squared = 0.059,
               factor.levels = 2,
               power = .80, alpha = 0.05)

# estimate sample size using regression approach(F-Test)
power.f.regression(r.squared = 0.059,
                   k.total = 1,
                   power = 0.80, alpha = 0.05)

# estimate sample size using regression approach (t-Test)
p <- 0.50 # proportion of sample in treatment (allocation rate)
power.t.regression(beta = 0.50, r.squared = 0,
                   k.total = 1,
                   sd.predictor = sqrt(p * (1 - p)),
                   power = 0.80, alpha = 0.05)

# estimate sample size using t test approach
power.t.student(d = 0.50, power = 0.80, alpha = 0.05)

#############################################
#              two-way ANOVA                #
#############################################

# a researcher is expecting a partial eta-squared = 0.03
# for interaction of treatment (Factor A) with
# gender consisting of two levels (Factor B)

power.f.ancova(eta.squared = 0.03,
               factor.levels = c(2,2),
               power = 0.80, alpha = 0.05)

# estimate sample size using regression approach (F test)
# one dummy for treatment, one dummy for gender, and their interaction (k = 3)
# partial eta-squared is equivalent to the increase in R-squared by adding
# only the interaction term (m = 1)
power.f.regression(r.squared = 0.03,
                   k.total = 3, k.test = 1,
                   power = 0.80, alpha = 0.05)

#############################################
#              one-way ANCOVA               #
#############################################

# a researcher is expecting an adjusted difference of
# Cohen's d = 0.45 between treatment and control after
# controllling for the pretest (k.covariates = 1)
# translating into eta-squared = 0.048

power.f.ancova(eta.squared = 0.048,
               factor.levels = 2,
               k.covariates = 1,
               power = .80, alpha = 0.05)

#############################################
#              two-way ANCOVA               #
#############################################

# a researcher is expecting an adjusted partial eta-squared = 0.02
# for interaction of treatment (Factor A) with
# gender consisting of two levels (Factor B)

power.f.ancova(eta.squared = 0.02,
               factor.levels = c(2,2),
               k.covariates = 1,
               power = .80, alpha = 0.05)

Description

Calculates power, sample size or effect size for one-way ANOVA/ANCOVA. Set k.covariates = 0 for one-way ANOVA (without any pretest or covariate adjustment). Set k.covariates > 0 in combination with r.squared > 0 for one-way ANCOVA (with pretest or covariate adjustment).

Formulas are validated using the PASS documentation.

Usage

power.f.ancova.keppel(
  mu.vector,
  sd.vector,
  n.vector = NULL,
  p.vector = NULL,
  factor.levels = NULL,
  r.squared = 0,
  k.covariates = 0,
  power = NULL,
  alpha = 0.05,
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

Note that R has a partial matching feature which allows you to specify shortened versions of arguments, such as mu or mu.vec instead of mu.vector, or such as k or k.cov instead of k.covariates.

Value

References

Keppel, G., & Wickens, T. D. (2004). Design and analysis: A researcher's handbook (4th ed.). Pearson.

Examples

# required sample size to detect a mean difference of
# Cohen's d = 0.50 for a one-way two-group design
power.f.ancova.keppel(mu.vector = c(0.50, 0), # marginal means
                      sd.vector = c(1, 1), # unadjusted standard deviations
                      n.vector = NULL, # sample size (will be calculated)
                      p.vector = c(0.50, 0.50), # balanced allocation
                      k.covariates = 1, # number of covariates
                      r.squared = 0.50, # explanatory power of covariates
                      alpha = 0.05, # Type 1 error rate
                      power = .80)

# effect size approach
power.f.ancova(eta.squared = 0.111, # effect size that is already adjusted for covariates
               factor.levels = 2, # one-way ANCOVA with two levels (groups)
               k.covariates = 1, # number of covariates
               alpha = 0.05, # Type 1 error rate
               power = .80)

# regression approach
p <- 0.50
power.t.regression(beta = 0.50,
                   sd.predictor = sqrt(p * (1 - p)),
                   sd.outcome = 1,
                   k.total = 1,
                   r.squared = 0.50,
                   n = NULL, power = 0.80)

Description

Calculates power, sample size or effect size for one-, two-, three-way ANCOVA. For factorial designs, use the argument factor.levels but note that unique combination of levels (cells in this case) should follow a specific order for the test of interaction. The order of marginal means and standard deviations is printed as a warning message.

Formulas are validated using examples and tables in Shieh (2020).

Usage

power.f.ancova.shieh(
  mu.vector,
  sd.vector,
  n.vector = NULL,
  p.vector = NULL,
  factor.levels = NULL,
  r.squared = 0,
  k.covariates = 1,
  contrast.matrix = NULL,
  power = NULL,
  alpha = 0.05,
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

Note that R has a partial matching feature which allows you to specify shortened versions of arguments, such as mu or mu.vec instead of mu.vector, or such as k or k.cov instead of k.covariates.

Value

References

Shieh, G. (2020). Power analysis and sample size planning in ANCOVA designs. Psychometrika, 85(1), 101-120. https://doi.org/10.1007/s11336-019-09692-3

Examples

###################################################################
##########################  main effect  ##########################
###################################################################

# power for one-way ANCOVA (two levels or groups)
power.f.ancova.shieh(mu.vector = c(0.20, 0), # marginal means
                     sd.vector = c(1, 1), # unadjusted standard deviations
                     n.vector = c(150, 150), # sample sizes
                     r.squared = 0.50, # proportion of variance explained by covariates
                     k.covariates = 1, # number of covariates
                     alpha = 0.05)


# sample size for one-way ANCOVA (two levels or groups)
power.f.ancova.shieh(mu.vector = c(0.20, 0), # marginal means
                     sd.vector = c(1, 1), # unadjusted standard deviations
                     p.vector = c(0.50, 0.50), # allocation, should sum to 1
                     r.squared = 0.50,
                     k.covariates = 1,
                     alpha = 0.05,
                     power = 0.80)

###################################################################
#######################  interaction effect  ######################
###################################################################

# sample size for two-way ANCOVA (2 x 2)
power.f.ancova.shieh(mu.vector = c(0.20, 0.25, 0.15, 0.05), # marginal means
                     sd.vector = c(1, 1, 1, 1), # unadjusted standard deviations
                     p.vector = c(0.25, 0.25, 0.25, 0.25), # allocation, should sum to 1
                     factor.levels = c(2, 2), # 2 by 2 factorial design
                     r.squared = 0.50,
                     k.covariates = 1,
                     alpha = 0.05,
                     power = 0.80)
# Elements of `mu.vector`, `sd.vector`, `n.vector` or `p.vector` should follow this specific order:
#  A1:B1  A1:B2  A2:B1  A2:B2

###################################################################
#######################  planned contrasts  #######################
###################################################################

#########################
## dummy coding scheme ##
#########################

contrast.object <- factorial.contrasts(factor.levels = 3, # one factor w/ 3 levels
                                       coding = "treatment") # use dummy coding scheme

# get contrast matrix from the contrast object
contrast.matrix <- contrast.object$contrast.matrix

# calculate sample size given design characteristics
ancova.design <- power.f.ancova.shieh(mu.vector = c(0.15, 0.30, 0.20), # marginal means
                                      sd.vector = c(1, 1, 1), # unadjusted standard deviations
                                      p.vector = c(1/3, 1/3, 1/3), # allocation, should sum to 1
                                      contrast.matrix = contrast.matrix,
                                      r.squared = 0.50,
                                      k.covariates = 1,
                                      alpha = 0.05,
                                      power = 0.80)

# power of planned contrasts, adjusted for alpha level
power.t.contrasts(ancova.design, adjust.alpha = "fdr")

###########################
## Helmert coding scheme ##
###########################

contrast.object <- factorial.contrasts(factor.levels = 3, # one factor w/ 4 levels
                                       coding = "helmert") # use helmert coding scheme

# get contrast matrix from the contrast object
contrast.matrix <- contrast.object$contrast.matrix

# calculate sample size given design characteristics
ancova.design <- power.f.ancova.shieh(mu.vector = c(0.15, 0.30, 0.20), # marginal means
                                      sd.vector = c(1, 1, 1), # unadjusted standard deviations
                                      p.vector = c(1/3, 1/3, 1/3), # allocation, should sum to 1
                                      contrast.matrix = contrast.matrix,
                                      r.squared = 0.50,
                                      k.covariates = 1,
                                      alpha = 0.05,
                                      power = 0.80)

# power of planned contrasts
power.t.contrasts(ancova.design)

##############################
## polynomial coding scheme ##
##############################

contrast.object <- factorial.contrasts(factor.levels = 3, # one factor w/ 4 levels
                                       coding = "poly") # use polynomial coding scheme

# get contrast matrix from the contrast object
contrast.matrix <- contrast.object$contrast.matrix

# calculate sample size given design characteristics
ancova.design <- power.f.ancova.shieh(mu.vector = c(0.15, 0.30, 0.20), # marginal means
                                      sd.vector = c(1, 1, 1), # unadjusted standard deviations
                                      p.vector = c(1/3, 1/3, 1/3), # allocation, should sum to 1
                                      contrast.matrix = contrast.matrix,
                                      r.squared = 0.50,
                                      k.covariates = 1,
                                      alpha = 0.05,
                                      power = 0.80)

# power of the planned contrasts
power.t.contrasts(ancova.design)

######################
## custom contrasts ##
######################

# custom contrasts
contrast.matrix <- rbind(
  cbind(A1 = 1, A2 = -0.50, A3 = -0.50),
  cbind(A1 = 0.50, A2 = 0.50, A3 = -1)
)
# labels are not required for custom contrasts,
# but they make it easier to understand power.t.contrasts() output

# calculate sample size given design characteristics
ancova.design <- power.f.ancova.shieh(mu.vector = c(0.15, 0.30, 0.20), # marginal means
                                      sd.vector = c(1, 1, 1), # unadjusted standard deviations
                                      p.vector = c(1/3, 1/3, 1/3), # allocation, should sum to 1
                                      contrast.matrix = contrast.matrix,
                                      r.squared = 0.50,
                                      k.covariates = 1,
                                      alpha = 0.05,
                                      power = 0.80)

# power of the planned contrasts
power.t.contrasts(ancova.design)

Description

Calculates power, sample size or effect size for mixed-effects ANOVA design with two factors (between and within). When there is only one group observed over time, this design is often referred to as repeated-measures ANOVA.

Formulas are validated using G*Power and tables in the PASS documentation.

Usage

power.f.mixed.anova(
  eta.squared = NULL,
  null.eta.squared = 0,
  factor.levels = c(2, 2),
  factor.type = c("between", "within"),
  rho.within = 0.5,
  epsilon = 1,
  n.total = NULL,
  power = NULL,
  alpha = 0.05,
  effect = c("between", "within", "interaction"),
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

• NB: The pwrss.f.rmanova() function is deprecated and will no longer be supported, but it will remain available as a wrapper for the power.f.mixed.anova() function during a transition period.

Value

References

Bulus, M., & Polat, C. (2023). pwrss R paketi ile istatistiksel guc analizi [Statistical power analysis with pwrss R package]. Ahi Evran Universitesi Kirsehir Egitim Fakultesi Dergisi, 24(3), 2207-2328. https://doi.org/10.29299/kefad.1209913

Examples

######################################################
# pretest-post-test design with treatment group only  #
######################################################

# a researcher is expecting a difference of Cohen's d = 0.30
# between post-test and pretest score translating into
# Eta-squared = 0.022

# adjust effect size for correlation with 'rho.within'
power.f.mixed.anova(eta.squared = 0.022,
                    factor.levels = c(1, 2), # 1 between 2 within
                    rho.within = 0.50,
                    effect = "within",
                    power = 0.80, alpha = 0.05)

# if effect size is already adjusted for correlation
# use 'rho.within = NA'
power.f.mixed.anova(eta.squared = 0.08255,
                    factor.levels = c(1, 2), # 1 between 2 within
                    rho.within = NA,
                    effect = "within",
                    power = 0.80, alpha = 0.05)

##########################################################
# post-test only design with treatment and control groups #
##########################################################

# a researcher is expecting a difference of Cohen's d = 0.50
# on the post-test score between treatment and control groups
# translating into Eta-squared = 0.059
power.f.mixed.anova(eta.squared = 0.059,
                    factor.levels = c(2, 1),  # 2 between 1 within
                    effect = "between",
                    power = 0.80, alpha = 0.05)


#############################################################
# pretest-post-test design with treatment and control groups #
#############################################################

# a researcher is expecting a difference of Cohen's d = 0.40
# on the post-test score between treatment and control groups
# after controlling for the pretest translating into
# partial Eta-squared = 0.038
power.f.mixed.anova(eta.squared = 0.038,
                    factor.levels = c(2, 2),  # 2 between 2 within
                    rho.within = 0.50,
                    effect = "between",
                    power = 0.80, alpha = 0.05)

# a researcher is expecting an interaction effect
# (between groups and time) of Eta-squared = 0.01
power.f.mixed.anova(eta.squared = 0.01,
                    factor.levels = c(2, 2),  # 2 between 2 within
                    rho.within = 0.50,
                    effect = "interaction",
                    power = 0.80, alpha = 0.05)

# a researcher is expecting an interaction effect
# (between groups and time) of Eta-squared = 0.01
power.f.mixed.anova(eta.squared = 0.01,
                    factor.levels = c(2, 2),  # 2 between 2 within
                    rho.within = 0.50,
                    effect = "within",
                    power = 0.80, alpha = 0.05)

Description

Calculates power or sample size (only one can be NULL at a time) to test R-squared deviation from 0 (zero) in linear regression or to test R-squared change between two linear regression models. The test of R-squared change is often used to evaluate incremental contribution of a set of predictors in hierarchical linear regression.

Formulas are validated using Monte Carlo simulation, G*Power, and tables in the PASS documentation.

Usage

power.f.regression(
  r.squared.change = NULL,
  margin = 0,
  k.total,
  k.tested = k.total,
  n = NULL,
  power = NULL,
  alpha = 0.05,
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

• NB: The pwrss.f.regression function and its alias pwrss.f.reg() are deprecated, but they will remain available as a wrapper for the power.f.regression() function during a transition period.

Value

References

Bulus, M., & Polat, C. (2023). pwrss R paketi ile istatistiksel guc analizi [Statistical power analysis with pwrss R package]. Ahi Evran Universitesi Kirsehir Egitim Fakultesi Dergisi, 24(3), 2207-2328. https://doi.org/10.29299/kefad.1209913

Cohen, J. (1988). Statistical power analysis for the behavioral sciences (2nd ed.). Lawrence Erlbaum Associates.

Examples

# in the outcome (R-squared = 0.15).
power.f.regression(r.squared = 0.15,
                   k.total = 3, # total number of predictors
                   power = 0.80)

# adding two more variables will increase R-squared
# from 0.15 (with 3 predictors) to 0.25 (with 3 + 2 predictors)
power.f.regression(r.squared.change = 0.10, # R-squared change
                   k.total = 5, # total number of predictors
                   k.tested = 2, # predictors to be tested
                   power = 0.80)

Description

Determines the power or the non-centrality parameter for the generic F-Test with (optional) Type 1 and Type 2 error plots.

Usage

power.f.test(
  power = NULL,
  ncp = NULL,
  null.ncp = 0,
  df1,
  df2,
  alpha = 0.05,
  plot = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Value

Examples

# power is defined as the probability of observing a test statistics greater
# than the critical value
power.f.test(ncp = 1, df1 = 4, df2 = 100, alpha = 0.05)
power.f.test(power = 0.80, df1 = 4, df2 = 100, alpha = 0.05)

Description

Determines the power, the non-centrality parameter, or the degrees of freedom for the lambda-prime distribution with (optional) Type 1 and Type 2 error plots.

Usage

power.lp.test(
  power = NULL,
  ncp = NULL,
  req.sign = "+",
  null.ncp = 0,
  df = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided", "two.one.sided"),
  plot = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Value

Examples

# two-sided
# power defined as the probability of observing test statistics greater
# than the positive critical value OR less than the negative critical value
power.lp.test(ncp = 1.96, df = 100, alpha = 0.05, alternative = "two.sided")
power.lp.test(power = 0.80, df = 100, alpha = 0.05, alternative = "two.sided")

# one-sided
# power is defined as the probability of observing a test statistic greater
# than the critical value
power.lp.test(ncp = 1.96, df = 100, alpha = 0.05, alternative = "one.sided")
power.lp.test(power = 0.80, df = 100, alpha = 0.05, alternative = "one.sided")

# equivalence
# power is defined as the probability of observing a test statistic greater
# than the upper critical value (for the lower bound) AND less than the
# lower critical value (for the upper bound)
power.lp.test(ncp = 0, null.ncp = c(-2, 2), df = 100, alpha = 0.05,
              alternative = "two.one.sided")
power.lp.test(power = 0.80, req.sign = "0", null.ncp = c(-2, 2),
              df = 100, alpha = 0.05, alternative = "two.one.sided")

# minimal effect testing
# power is defined as the probability of observing a test statistic greater
# than the upper critical value (for the upper bound) OR less than the lower
# critical value (for the lower bound).
power.lp.test(ncp = 2, null.ncp = c(-1, 1), df = 100, alpha = 0.05,
              alternative = "two.one.sided")
power.lp.test(power = 0.80, req.sign = "+", null.ncp = c(-1, 1),
              df = 100, alpha = 0.05, alternative = "two.one.sided")

Description

Calculates power, sample size or effect size (only one can be NULL at a time) for non-parametric rank-based tests. The following tests and designs are available:

• Wilcoxon Signed-Rank Test (One Sample)

• Wilcoxon Rank-Sum or Mann-Whitney U Test (Independent Samples)

• Wilcoxon Matched-Pairs Signed-Rank Test (Paired Samples)

Formulas are validated using GPower and tables in the PASS documentation. However, we adopt the rounding convention used by GPower.

Usage

power.np.wilcoxon(
  d = NULL,
  null.d = 0,
  margin = 0,
  n.ratio = 1,
  n2 = NULL,
  power = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided", "two.one.sided"),
  design = c("independent", "paired", "one.sample"),
  distribution = c("normal", "uniform", "double.exponential", "laplace", "logistic"),
  method = c("guenther", "noether"),
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

• Use means.to.d() to convert raw means and standard deviations to Cohen's d, and d.to.cles() to convert Cohen's d to the probability of superiority. Note that this interpretation is appropriate only when the underlying distribution is approximately normal and the two groups have similar population variances.

• NB: pwrss.np.2means() function is depreciated and no longer supported. pwrss.np.2groups() will remain available for some time.

• Note that R has a partial matching feature which allows you to specify shortened versions of arguments, such as alt instead of alternative, or dist instead of distribution.

Value

References

Al-Sunduqchi, M. S. (1990). Determining the appropriate sample size for inferences based on the Wilcoxon statistics [Unpublished doctoral dissertation]. University of Wyoming - Laramie

Chow, S. C., Shao, J., Wang, H., and Lokhnygina, Y. (2018). Sample size calculations in clinical research (3rd ed.). Taylor & Francis/CRC.

Lehmann, E. (1975). Nonparameterics: Statistical methods based on ranks. McGraw-Hill.

Noether, G. E. (1987). Sample size determination for some common nonparametric tests. Journal of the American Statistical Association, 82(1), 645-647.

Ruscio, J. (2008). A probability-based measure of effect size: Robustness to base rates and other factors. Psychological Methods, 13(1), 19-30.

Ruscio, J., & Mullen, T. (2012). Confidence intervals for the probability of superiority effect size measure and the area under a receiver operating characteristic curve. Multivariate Behavioral Research, 47(2), 201-223.

Zhao, Y.D., Rahardja, D., & Qu, Y. (2008). Sample size calculation for the Wilcoxon-Mann-Whitney test adjusting for ties. Statistics in Medicine, 27(3), 462-468.

Examples

# see `?pwrss::power.t.student` for further examples

# Mann-Whitney U or Wilcoxon rank-sum test
# (a.k.a Wilcoxon-Mann-Whitney test) for independent samples

## difference between group 1 and group 2 is not equal to zero
## estimated difference is Cohen'd = 0.25
power.np.wilcoxon(d = 0.25,
                power = 0.80)

## difference between group 1 and group 2 is greater than zero
## estimated difference is Cohen'd = 0.25
power.np.wilcoxon(d = 0.25,
                power = 0.80,
                alternative = "one.sided")

## mean of group 1 is practically not smaller than mean of group 2
## estimated difference is Cohen'd = 0.10 and can be as small as -0.05
power.np.wilcoxon(d = 0.10,
                margin = -0.05,
                power = 0.80,
                alternative = "one.sided")

## mean of group 1 is practically greater than mean of group 2
## estimated difference is Cohen'd = 0.10 and can be as small as 0.05
power.np.wilcoxon(d = 0.10,
                margin = 0.05,
                power = 0.80,
                alternative = "one.sided")

## mean of group 1 is practically same as mean of group 2
## estimated difference is Cohen'd = 0
## and can be as small as -0.05 and as high as 0.05
power.np.wilcoxon(d = 0,
                margin = c(-0.05, 0.05),
                power = 0.80,
                alternative = "two.one.sided")


# Wilcoxon signed-rank test for matched pairs (dependent samples)

## difference between time 1 and time 2 is not equal to zero
## estimated difference between time 1 and time 2 is Cohen'd = -0.25
power.np.wilcoxon(d = -0.25,
                power = 0.80,
                design = "paired")

## difference between time 1 and time 2 is greater than zero
## estimated difference between time 1 and time 2 is Cohen'd = -0.25
power.np.wilcoxon(d = -0.25,
                power = 0.80,
                design = "paired",
                alternative = "one.sided")

## mean of time 1 is practically not smaller than mean of time 2
## estimated difference is Cohen'd = -0.10 and can be as small as 0.05
power.np.wilcoxon(d = -0.10,
                margin = 0.05,
                power = 0.80,
                design = "paired",
                alternative = "one.sided")

## mean of time 1 is practically greater than mean of time 2
## estimated difference is Cohen'd = -0.10 and can be as small as -0.05
power.np.wilcoxon(d = -0.10,
                margin = -0.05,
                power = 0.80,
                design = "paired",
                alternative = "one.sided")

## mean of time 1 is practically same as mean of time 2
## estimated difference is Cohen'd = 0
## and can be as small as -0.05 and as high as 0.05
power.np.wilcoxon(d = 0,
                margin = c(-0.05, 0.05),
                power = 0.80,
                design = "paired",
                alternative = "two.one.sided")

Description

Calculates power or sample size for a single one-, two-, three-Way ANCOVA contrast.

Formulas are validated using examples and tables in Shieh (2017).

Usage

power.t.contrast(
  mu.vector,
  sd.vector,
  n.vector = NULL,
  p.vector = NULL,
  contrast.vector,
  r.squared = 0,
  k.covariates = 1,
  power = NULL,
  alpha = 0.05,
  tukey.kramer = FALSE,
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

Note that R has a partial matching feature which allows you to specify shortened versions of arguments, such as mu or mu.vec instead of mu.vector, or such as k or k.cov instead of k.covariates.

Value

References

Shieh, G. (2017). Power and sample size calculations for contrast analysis in ANCOVA. Multivariate Behavioral Research, 52(1), 1-11. https://doi.org/10.1080/00273171.2016.1219841

Examples

# dummy coding example (uses the first contrast from a three-level- / two-contrasts-design)
contrast.object <- factorial.contrasts(factor.levels = 3, coding = "treatment", verbose = 0)
contrast.vector <- contrast.object[["contrast.matrix"]][1, ]
power.t.contrast(mu.vector = c(0.15, 0.30, 0.20),
                 sd.vector = c(1,    1,    1),
                 p.vector  = c(1/3,  1/3,  1/3),
                 r.squared = 0.50, k.covariates = 1,
                 contrast.vector = contrast.vector,
                 power = 0.80, alpha = 0.05)

Description

Calculates power or sample size for one-, two-, three-Way ANCOVA contrasts and multiple comparisons. The power.t.contrasts() function permits to test multiple contrasts (multiple comparisons) and also allows adjustment to alpha due to multiple testing. Furthermore, power.t.contrasts() accepts an object returned from the power.f.ancova.shieh() function for convenience. Beware that, in this case, all other arguments are ignored except alpha and adjust.alpha.

Formulas are validated using examples and tables in Shieh (2017).

Usage

power.t.contrasts(
  x = NULL,
  mu.vector = NULL,
  sd.vector = NULL,
  n.vector = NULL,
  p.vector = NULL,
  r.squared = 0,
  k.covariates = 1,
  contrast.matrix = NULL,
  power = NULL,
  alpha = 0.05,
  adjust.alpha = c("none", "tukey", "bonferroni", "holm", "hochberg", "hommel", "BH",
    "BY", "fdr"),
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

Note that R has a partial matching feature which allows you to specify shortened versions of arguments, such as mu or mu.vec instead of mu.vector, or such as k or k.cov instead of k.covariates.

Value

References

Shieh, G. (2017). Power and sample size calculations for contrast analysis in ANCOVA. Multivariate Behavioral Research, 52(1), 1-11. https://doi.org/10.1080/00273171.2016.1219841

Examples

# see `?pwrss::power.f.ancova.shieh` for further examples

# dummy coding example
contrast.object <- factorial.contrasts(factor.levels = 3, coding = "treatment", verbose = 0)
contrast.matrix <- contrast.object[["contrast.matrix"]]
power.t.contrasts(mu.vector = c(0.15, 0.30, 0.20),
                  sd.vector = c(1,    1,    1),
                  p.vector  = c(1/3,  1/3,  1/3),
                  r.squared = 0.50, k.covariates = 1,
                  contrast.matrix = contrast.matrix,
                  power = 0.80,
                  alpha = 0.05, adjust.alpha = "holm")

Description

Calculates power, sample size or effect size (only one can be NULL at a time) to test a single coefficient in multiple linear regression. By default, the predictor is assumed to be continuous. However, one can calculate power, sample size or effect size for a binary predictor (such as treatment and control groups in an experimental design) by specifying sd.predictor = sqrt(p * (1 - p)) where p is the proportion of subjects in one of the groups. The sample size in each group would be n * p and n * (1 - p).

Minimal effect and equivalence tests are implemented in line with Hodges and Lehmann (1954), Kim and Robinson (2019), Phillips (1990), and Dupont and Plummer (1998).

Formulas are validated using Monte Carlo simulation, G*Power, tables in the PASS documentation, and tables in Bulus (2021).

Usage

power.t.regression(
  beta = NULL,
  null.beta = 0,
  margin = 0,
  sd.predictor = 1,
  sd.outcome = 1,
  r.squared = NULL,
  k.total = 1,
  n = NULL,
  power = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided", "two.one.sided"),
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)

Arguments

Details

• When it is requested to calculate the effect size (by giving both their parameters n and power), r.squared must be empty and beta can be empty (NULL). By default, a linear regression with one predictor is assumed. If beta, sd.predictor and sd.outcome are given (i.e., in cases where it is not requested to calculate the effect size), r.squared is calculated as follows: r.squared = (beta * sd.predictor / sd.outcome) ^ 2. If the given beta results in an r.squared below this value, a warning will be issued. To calculate beta from r.squared, the following formula can be used: beta = (sqrt(r.squared) * sd.outcome / sd.predictor).

• To consider other covariates in the model provide a value greater than the default value for r.squared (see above) along with the argument k.total > 1. However, in such case, the above formula for calculating beta can not be used.

• power.t.regression(), pwrss.t.regression(), power.t.reg() and pwrss.t.reg() are the same functions.

• NB: The pwrss.z.regression() function and its alias pwrss.z.reg() are deprecated, but they will remain available as a wrapper for the power.t.regression() function during a transition period.

Value

References

Bulus, M. (2021). Sample size determination and optimal design of randomized / non-equivalent pretest-post-test control-group designs. Adiyaman University Journal of Educational Sciences, 11(1), 48-69. https://doi.org/10.17984/adyuebd.941434

Hodges Jr, J. L., & Lehmann, E. L. (1954). Testing the approximate validity of statistical hypotheses. Journal of the Royal Statistical Society Series B: Statistical Methodology, 16(2), 261-268. https://doi.org/10.1111/j.2517-6161.1954.tb00169.x

Kim, J. H., & Robinson, A. P. (2019). Interval-based hypothesis testing and its applications to economics and finance. Econometrics, 7(2), 21. https://doi.org/10.1111/10.3390/econometrics7020021

Phillips, K. F. (1990). Power of the two one-sided tests procedure in bioequivalence. Journal of Pharmacokinetics and Biopharmaceutics, 18(2), 137-144. https://doi.org/10.1007/bf01063556

Dupont, W. D., and Plummer, W. D. (1998). Power and sample size calculations for studies involving linear regression. Controlled Clinical Trials, 19(6), 589-601. https://doi.org/10.1007/10.1016/s0197-2456(98)00037-3

Examples

# continuous predictor x (and 4 covariates)
power.t.regression(beta = 0.20,
            k.total = 5,
            r.squared = 0.30,
            power = 0.80)

# binary predictor x (and 4 covariates)
p <- 0.50 # proportion of subjects in one group
power.t.regression(beta = 0.20,
            sd.predictor = sqrt(p * (1 - p)),
            k.total = 5,
            r.squared = 0.30,
            power = 0.80)

# non-inferiority test with binary predictor x (and 4 covariates)
p <- 0.50 # proportion of subjects in one group
power.t.regression(beta = 0.20, # Cohen's d
            margin = -0.05, # non-inferiority margin in Cohen's d unit
            alternative = "one.sided",
            sd.predictor = sqrt(p*(1-p)),
            k.total = 5,
            r.squared = 0.30,
            power = 0.80)

# superiority test with binary predictor x (and 4 covariates)
p <- 0.50 # proportion of subjects in one group
power.t.regression(beta = 0.20, # Cohen's d
            margin = 0.05, # superiority margin in Cohen's d unit
            alternative = "one.sided",
            sd.predictor = sqrt(p * (1 - p)),
            k.total = 5,
            r.squared = 0.30,
            power = 0.80)

# equivalence test with binary predictor x (and 4 covariates)
p <- 0.50 # proportion of subjects in one group
power.t.regression(beta = 0, # Cohen's d
            margin = c(-0.05, 0.05), # equivalence bounds in Cohen's d unit
            alternative = "two.one.sided",
            sd.predictor = sqrt(p * (1 - p)),
            k.total = 5,
            r.squared = 0.30,
            power = 0.80)

Description

Calculates power, sample size or effect size (only one can be NULL at a time) for Student's t-Test.

In contrast to previous versions, users can now specify whether their claims will be based on raw score mean difference with P-values or standardized mean difference with confidence intervals. While results typically differ by only a few units, these distinctions can be particularly consequential in studies with small sample sizes or high-risk interventions.

Formulas are validated using Monte Carlo simulations (see Bulus, 2024), G*Power, and tables in the PASS documentation. One key difference between PASS and pwrss lies in how they handle non-inferiority and superiority tests-that is, one-sided tests defined by a negligible effect margin (implemented as of this version). PASS shifts the test statistic so that the null hypothesis assumes a zero effect, treating the negligible margin as part of the alternative hypothesis. As a result, the test statistic is evaluated against a central distribution. In contrast, pwrss treats the negligible effect as the true null value, and the test statistic is evaluated under a non-central distribution. This leads to slight differences up to third decimal place. To get the same results, reflect the margin in null.d and specify margin = 0.

Equivalence tests are implemented in line with Bulus and Polat (2023), Chow et al. (2018) and Lakens (2017).

Usage

power.t.student(
  d = NULL,
  null.d = 0,
  margin = 0,
  n2 = NULL,
  n.ratio = 1,
  power = NULL,
  alpha = 0.05,
  alternative = c("two.sided", "one.sided", "two.one.sided"),
  design = c("independent", "paired", "one.sample"),
  claim.basis = c("md.pval", "smd.ci"),
  ceil.n = TRUE,
  verbose = 1,
  utf = FALSE
)