semPower.aPriori {semPower}

semPower.aPriori

Description

Performs an a-priori power analysis, i. e., determines the required sample size given alpha, beta (or power: 1 - beta), df, and a measure of effect.

Usage

semPower.aPriori(
  effect = NULL,
  effect.measure = NULL,
  alpha,
  beta = NULL,
  power = NULL,
  N = NULL,
  df = NULL,
  p = NULL,
  SigmaHat = NULL,
  Sigma = NULL,
  muHat = NULL,
  mu = NULL,
  fittingFunction = "ML",
  simulatedPower = FALSE,
  modelH0 = NULL,
  modelH1 = NULL,
  simOptions = NULL,
  lavOptions = NULL,
  lavOptionsH1 = lavOptions,
  ...
)

Arguments

effect

effect size specifying the discrepancy between the null hypothesis (H0) and the alternative hypothesis (H1). A list for multiple group models; a vector of length 2 for effect-size differences. Can be NULL if Sigma and SigmaHat are set.

effect.measure

type of effect, one of "F0", "RMSEA", "Mc", "GFI", "AGFI". Can be NULL if Sigma and SigmaHat are set.

alpha

alpha error

beta

beta error; set either beta or power.

power

power (= 1 - beta); set either beta or power.

N

a list of sample weights for multiple group power analyses, e.g. list(1, 2) to make the second group twice as large as the first one.

df

the model degrees of freedom. See semPower.getDf() for a way to obtain the df of a specific model.

p

the number of observed variables, only required for effect.measure = "GFI" and effect.measure = "AGFI".

SigmaHat

can be used instead of effect and effect.measure: model implied covariance matrix (a list for multiple group models). Used in conjunction with Sigma to define the effect.

Sigma

can be used instead of effect and effect.measure: population covariance matrix (a list for multiple group models). Used in conjunction with SigmaHat to define effect.

muHat

can be used instead of effect and effect.measure: model implied mean vector. Used in conjunction with mu. If NULL, no meanstructure is involved.

mu

can be used instead of effect and effect.measure: observed (or population) mean vector. Use in conjunction with muHat. If NULL, no meanstructure is involved.

fittingFunction

one of 'ML' (default), 'WLS', 'DWLS', 'ULS'. Defines the discrepancy function used to obtain Fmin.

simulatedPower

whether to perform a simulated (TRUE, rather than analytical, FALSE) power analysis. Only available if Sigma and modelH0 are defined.

modelH0

for simulated power: lavaan model string defining the (incorrect) analysis model.

modelH1

for simulated power: lavaan model string defining the comparison model. If omitted, the saturated model is the comparison model.

simOptions

a list of additional options specifying simulation details, see simulate() for details.

lavOptions

a list of additional options passed to lavaan, e. g., list(estimator = 'mlm') to request robust ML estimation.

lavOptionsH1

alternative options passed to lavaan that are only used for the H1 model. If NULL, identical to lavOptions. Probably only useful for multigroup models.

...

other parameters related to plots, notably plotShow, plotShowLabels, and plotLinewidth.

Value

Returns a list. Use summary() to obtain formatted results.

See Also

semPower.postHoc() semPower.compromise()

Examples

## Not run: 
# determine the required sample size to reject a model showing misspecifications 
# amounting to RMSEA >= .05 on 200 df with a power of 95 % on alpha = .05   
ap <- semPower.aPriori(effect = .05, effect.measure = "RMSEA", 
                       alpha = .05, beta = .05, df = 200)
summary(ap)

# use f0 as effect size metric
ap <- semPower.aPriori(effect = .15, effect.measure = "F0", 
                       alpha = .05, power = .80, df = 200)
summary(ap)

# power analysis for to detect the difference between a model (with df = 200) exhibiting RMSEA = .05
# and a model (with df = 210) exhibiting RMSEA = .06.
ap <- semPower.aPriori(effect = c(.05, .06), effect.measure = "RMSEA", 
                       alpha = .05, power = .80, df = c(200, 210))
summary(ap)

# power analysis based on SigmaHat and Sigma (nonsense example)
ap <- semPower.aPriori(alpha = .05, beta = .05, df = 5, 
                       SigmaHat = diag(4), Sigma = cov(matrix(rnorm(4*1000),  ncol=4)))
summary(ap)

# multiple group example
ap <- semPower.aPriori(effect = list(.05, .10), effect.measure = "F0", 
                       alpha = .05, power = .80, df = 100, 
                       N = list(1, 1))
summary(ap)

# simulated power analysis (nonsense example)
ap <- semPower.aPriori(alpha = .05, beta = .05, df = 200, 
                       SigmaHat = list(diag(4), diag(4)), 
                       Sigma = list(cov(matrix(rnorm(4*1000), ncol=4)), 
                               cov(matrix(rnorm(4*1000), ncol=4))),
                       simulatedPower = TRUE, nReplications = 100)
summary(ap)

## End(Not run)