semPower.powerLav: semPower.powerLav

In semPower: Power Analyses for SEM

semPower.powerLav

Description

Perform a power analysis given lavaan model strings defining the H0 and the H1 model based on either a lavaan model string defining the population model or the population covariance matrix Sigma and the population means mu. This requires the lavaan package.

Usage

semPower.powerLav(
  type,
  modelPop = NULL,
  modelH0 = NULL,
  modelH1 = NULL,
  fitH1model = TRUE,
  Sigma = NULL,
  mu = NULL,
  fittingFunction = "ML",
  simulatedPower = FALSE,
  lavOptions = NULL,
  lavOptionsH1 = lavOptions,
  ...
)

Arguments

type	type of power analysis, one of 'a-priori', 'post-hoc', 'compromise'.
modelPop	lavaan model string defining the true model. Can be omitted when Sigma is set.
modelH0	lavaan model string defining the (incorrect) analysis model.
modelH1	lavaan model string defining the comparison model. If omitted, the saturated model is the comparison model.
fitH1model	whether to fit the H1 model. If FALSE, the H1 model is assumed to show the same fit as the saturated model, and only the delta df are computed.
Sigma	can be used instead of modelPop: population covariance matrix. A list for multiple group models.
mu	can be used instead of modelPop: vector of population means. Can be omitted for no meanstructure. A list for multiple group models.
fittingFunction	one of 'ML' (default), 'WLS', 'DWLS', 'ULS'. Defines the fitting function used to obtain SigmaHat in analytical power analyses. This also implies a certain discrepancy function used to obtain Fmin.
simulatedPower	whether to perform a simulated (TRUE, rather than analytical, FALSE) power analysis. See simulate() for additional options.
lavOptions	a list of additional options passed to lavaan, e. g., list(estimator = 'mlm') to request robust ML estimation. Mostly useful in conjunction with simulatedPower.
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.
...	mandatory further parameters related to the specific type of power analysis requested, see semPower.aPriori(), semPower.postHoc(), and semPower.compromise(). See details.

Details

Generic function to perform a power analysis based on a true population covariance matrix Sigma and a model implied covariance matrix SigmaHat (and optionally the associated mean vectors), where SigmaHat (and muHat) is determined by fitting a respective H0 model using lavaan, and Sigma (and mu) can also be provided through a corresponding lavaan model string.

All semPower convenience functions internally call this function.

Beyond the arguments explicitly contained in the function call, additional arguments are required specifying the requested type of power analysis:

• alpha: The alpha error probability. Required for type = 'a-priori' and type = 'post-hoc'.

• Either beta or power: The beta error probability and the statistical power (1 - beta), respectively. Only for type = 'a-priori'.

• N: The sample size. Always required for type = 'post-hoc' and type = 'compromise'. For type = 'a-priori' and multiple group analysis, N is a list of group weights.

• abratio: The ratio of alpha to beta. Only for type = 'compromise'.

If a simulated power analysis (simulatedPower = TRUE) is requested, optional arguments can be provided as a list to simOptions:

• nReplications: The targeted number of simulation runs. Defaults to 250, but larger numbers greatly improve accuracy at the expense of increased computation time.

• minConvergenceRate: The minimum convergence rate required, defaults to .5. The maximum actual simulation runs are increased by a factor of 1/minConvergenceRate.

• type: specifies whether the data should be generated from a population assuming multivariate normality ('normal'; the default), or based on an approach generating non-normal data ('IG', 'mnonr', 'RC', or 'VM'). The approaches generating non-normal data require additional arguments detailed below.

• missingVars: vector specifying the variables containing missing data (defaults to NULL).

• missingVarProp: can be used instead of missingVars: The proportion of variables containing missing data (defaults to zero).

• missingProp: The proportion of missingness for variables containing missing data (defaults to zero), either a single value or a vector giving the probabilities for each variable.

• missingMechanism: The missing data mechanism, one of MCAR (the default), MAR, or NMAR.

• nCores: The number of cores to use for parallel processing. Defaults to 1 (= no parallel processing). This requires the doSNOW package.

type = 'IG' implements the independent generator approach (IG, Foldnes & Olsson, 2016) approach specifying third and fourth moments of the marginals, and thus requires that skewness (skewness) and excess kurtosis (kurtosis) for each variable are provided as vectors. This requires the covsim package.

type = 'mnonr' implements the approach suggested by Qu, Liu, & Zhang (2020) and requires provision of Mardia's multivariate skewness (skewness) and kurtosis (kurtosis), where skewness must be non-negative and kurtosis must be at least 1.641 skewness + p (p + 0.774), where p is the number of variables. This requires the mnonr package.

type = 'RK' implements the approach suggested by Ruscio & Kaczetow (2008) and requires provision of the population distributions of each variable (distributions). distributions must be a list (if all variables shall be based on the same population distribution) or a list of lists. Each component must specify the population distribution (e.g. rchisq) and additional arguments (list(df = 2)).

type = 'VM' implements the third-order polynomial method (Vale & Maurelli, 1983) specifying third and fourth moments of the marginals, and thus requires that skewness (skewness) and excess kurtosis (kurtosis) for each variable are provided as vectors. This requires the semTools package.

Value

a list. Use the summary method to obtain formatted results. Beyond the results of the power analysis and a number of effect size measures, the list contains the following components:

Sigma	the population covariance matrix. A list for multiple group models.
mu	the population mean vector or NULL when no meanstructure is involved. A list for multiple group models.
SigmaHat	the H0 model implied covariance matrix. A list for multiple group models.
muHat	the H0 model implied mean vector or NULL when no meanstructure is involved. A list for multiple group models.
modelH0	lavaan H0 model string.
modelH1	lavaan H1 model string or NULL when the comparison refers to the saturated model.
simRes	detailed simulation results when a simulated power analysis (simulatedPower = TRUE) was performed.

See Also

semPower.aPriori() semPower.postHoc() semPower.compromise()

Examples

## Not run: 
# set up two CFA factors with a true correlation of .2
mPop <- '
  f1 =~ .5*x1 + .6*x2 + .4*x3
  f2 =~ .7*x4 + .8*x5 + .3*x6
  x1 ~~ .75*x1
  x2 ~~ .64*x2
  x3 ~~ .84*x3
  x4 ~~ .51*x4
  x5 ~~ .36*x5
  x6 ~~ .91*x6
  f1 ~~ 1*f1
  f2 ~~ 1*f2
  f1 ~~ .2*f2
'
# define the H0 analysis model (restricting the factor correlation to zero) 
mH0 <- '
  f1 =~ x1 + x2 + x3
  f2 =~ x4 + x5 + x6
  f1 ~~ 0*f2
'
# determine N to reject the H0 that the correlation is zero 
# with a power of 95% on alpha = .05
powerLav <- semPower.powerLav(type = 'a-priori', 
                              modelPop = mPop, modelH0 = mH0,
                              alpha = .05, beta = .05)
summary(powerLav)

# same as above, but also define an H1 comparison model 
mH1 <- '
  f1 =~ x1 + x2 + x3
  f2 =~ x4 + x5 + x6
  f1 ~~ f2
'
powerLav <- semPower.powerLav(type = 'a-priori', 
                              modelPop = mPop, modelH0 = mH0, modelH1 = mH1,
                              alpha = .05, beta = .05)

# same as above, but use covariance matrix input instead of modelPop
gen <- semPower.genSigma(Phi = .2, 
                         loadings = list(c(.5, .6, .4), c(.7, .8, .3)))
Sigma <- gen$Sigma
powerLav <- semPower.powerLav(type = 'a-priori', 
                              Sigma = Sigma, modelH0 = mH0,
                              alpha = .05, beta = .05)

# note all of the above is identical to the output provided by the semPower.powerCFA function
powerCFA <- semPower.powerCFA(type = 'a-priori',
                              comparison = 'saturated',
                              Phi = .2, 
                              loadings = list(c(.5, .6, .4), c(.7, .8, .3)), 
                              alpha = .05, beta = .05)

# same as above, but perform simulated power analysis
# with 250 replications using a robust ML test-statistic
set.seed(300121)
powerLav <- semPower.powerLav(type = 'a-priori', 
                              Sigma = Sigma, modelH0 = mH0,
                              alpha = .05, beta = .05, 
                              simulatedPower = TRUE,
                              simOptions = list(nReplications = 250)
                              lavOptions = list(estimator = 'MLM'))

## End(Not run)

semPower documentation built on Sept. 30, 2024, 9:24 a.m.