pwrCurve: Simulate and visualize simultaneous power curves

In joelleforestier/SimuSim: Simultaneous Power Analysis for a Set of Statistical Tests

Description

Simulate and visualize individual and simultaneous power at a range of sample sizes of a set of statistical tests. Simultaneous power simulations are conducted using pwrMultivars or pwrMultimodels. A detailed walkthrough and set of vignettes for this and other SimulPower functions is available here.

Usage

pwrCurve(method = NULL, min = NULL, max = NULL,
increment = 20, thresholds = c(80, 90, 95), es_units = NULL,
es1 = NULL, es2 = NULL, es3...es10 = 0,
iv1iv2_cov...iv9iv10_cov = 0,
null_effect = 0, iterations = 1000, alpha = .05,
bonferroni = FALSE, seed = 1, iv1iv2_cov...iv9iv10_cov = 0)

Arguments

method	Specify which SimulPower function you would like to use to computer simultaneous power. Accepts either "pwrMultivars" or "pwrMultimodels". This argument has no default.
min	Set the minimum sample size for which you would like to estimate simultaneous power. Accepts any positive number. This argument has no default.
max	Set the maximum sample size for which you would like to estimate simultaneous power. Accepts any positive number. This argument has no default.
increment	Set the increments by which you would like the sample size to increase between power analyses. Accepts any positive whole number. Default = 20.
thresholds	Set the power thresholds for which you would like sample size estimates printed. Accepts either any single number between 0 and 100 or a vector of numbers between 0 and 100. Default = c(80, 90, 95).
es_units	Set the units in which you are specifying your effect sizes. Accepts "d" for Cohen's d, "r" for correlation coefficients, and "r2" for percent of variance accounted for. This argument has no default.
null_effect	For which, if any, of your predictors or models are you computing "null power?" If you want to compute "power" to NOT detect an effect, use this argument to specify which effects are predicted nulls by setting this argument equal to the number(s) corresponding to the predictors you hypothesize to be null. Accepts either a single whole number between 1 and the number of predictors you have specified or a vector of numbers between 1 and the the number of predictors you have specified. Default = no null effects.
iterations	How many times you would like to run your model in random samples drawn from your population? One model will be run in each random sample. Accepts any whole number greater than 0. Default = 1000.
alpha	Set your alpha level. This is the threshold below which p-values will be considered significant. Accepts any number greater than 0 and less than 1. Default = 0.05.
bonferroni	Apply a bonferroni correction? This is suggested if you intend on interpreting the results of multiple tests individually, but not if you intend on assessing a single research question by triangulating across multiple tests (Le Forestier, Page-Gould, & Chasteen, Forthcoming). Accepts TRUE or FALSE. Default = FALSE.
seed	Set a seed to make your results reproducible. Accepts any number. Default = 1.
es1...es10	The effect size, expressed in units specified in the es_units argument, for the relationship between each predictor and the dependent variable.You should always specify these in order, beginning with es1, and not skipping any. Accepts any number. These arguments have no defaults.
iv1iv2_cov...iv9iv10_cov	The relationships between each set of predictors, specified in correlation coefficients. Specifying relationships between predictors is optional unless your predictors, together, account for more than 100% of the variance in your DV, in which case you must specify relationships between your predictors to make that possible. Accepts any number between -1 and 1. Default = 0.
dv1dv2_cov...dv9dv10_cov	The relationships between each set of dependent variables, specified in correlation coefficients. Specifying relationships between DVs is optional. Accepts any number between -1 and 1. Default = 0.
iv1dv2_cov...iv9dv10_cov	The relationships between each set of predictors and dependent variables from separate models, specified in correlation coefficients. Specifying relationships between separate models' predictors and DVs is optional. Accepts any number between -1 and 1. Default = 0.

Details

The pwrCurve function is the first step in the suggested SimulPower workflow. Start here to visualize the approximate simultaneous power space occupied by your set of tests, then use either pwrMultivars or pwrMultimodels with lrager numbers of iterations for final power calculations with more stable estimates.

When you use this function (and we hope you do!), please cite the package:

Le Forestier, J. M. (2020). SimulPower: Simultaneous power analysis for a set of statistical tests. https://doi.org/10.31219/osf.io/w96uk

and/or cite the accompanying paper:

Le Forestier, J. M., Page-Gould, E., & Chasteen, A. L. (Forthcoming). Statistical power for a set of tests.

Value

A plot of power curves and a set of sample size estimates for default or user-defined power thresholds.

A dataframe containing a power estiamte, expressed as a decimal, for each of the effects individually, and for all the effects simultaneously.

Author(s)

Joel Le Forestier ([e-mail])

References

Le Forestier, J. M., Page-Gould, E., & Chasteen, A. (Forthcoming). Statistical power for a set of tests.

Examples

# An example using pwrMultivars

pwrCurve(method = "pwrMultivars", min = 200, max = 500,
es_units = "d", es1 = .35, es2 = .45, es3 = .50)

# An example using pwrMultimodels

pwrCurve(method = "pwrMultimodels", min = 100, max = 400, increment = 40,
es_units = "r2", es1 = .05, es2 = .06, es3 = .08, es4 = .06, es5 = .08, es6 = .07, es7 = .04)

joelleforestier/SimuSim documentation built on Aug. 5, 2021, 11:49 p.m.