View source: R/convenienceFunctions.R
semPower.powerCLPM | R Documentation |
Convenience function for performing power analysis on effects in a cross-lagged panel model (CLPM). This requires the lavaan package.
semPower.powerCLPM(
type,
comparison = "restricted",
nWaves = NULL,
autoregEffects = NULL,
crossedEffects = NULL,
rXY = NULL,
waveEqual = NULL,
nullEffect = NULL,
nullWhich = NULL,
nullWhichGroups = NULL,
standardized = TRUE,
standardizedResidualCovariances = TRUE,
metricInvariance = TRUE,
autocorResiduals = TRUE,
...
)
type |
type of power analysis, one of |
comparison |
comparison model, one of |
nWaves |
number of waves, must be >= 2. |
autoregEffects |
vector of the autoregressive effects of X and Y (constant across waves), or a list of vectors of autoregressive effects for X and Y from wave to wave, e.g. |
crossedEffects |
vector of crossed effects of X on Y |
rXY |
vector of (residual-)correlations between X and Y for each wave. If |
waveEqual |
parameters that are assumed to be equal across waves in both the H0 and the H1 model. Valid are |
nullEffect |
defines the hypothesis of interest. Valid are the same arguments as in |
nullWhich |
used in conjunction with |
nullWhichGroups |
for hypothesis involving cross-groups comparisons, vector indicating the groups for which equality constrains should be applied, e.g. |
standardized |
whether all parameters should be treated as standardized ( |
standardizedResidualCovariances |
whether the residual covariances provided in |
metricInvariance |
whether metric invariance over waves is assumed ( |
autocorResiduals |
whether the residuals of the indicators of latent variables are autocorrelated over waves ( |
... |
mandatory further parameters related to the specific type of power analysis requested, see |
This function performs a power analysis to reject various hypotheses arising
in crossed-lagged panel models (CLPM). In a standard CLPM implemented here,
two variables X and Y are repeatedly assessed at two or more different time points (nWaves
), yielding
autoregressive effects (stabilities; X1 -> X2 and Y1 -> Y2),
synchronous effects (X1 <-> Y1, X2 <-> Y2), and cross-lagged effects (X1 -> Y2 and Y1 -> X2).
CLPM including more than two waves are typically implemented assuming that the parameters are constant across waves (waveEqual
), and usually omit lag-2 effects (e.g., X1 -> Y3).
CLPM based on latent factors usually assume at least metric invariance of the factors over waves (metricInvariance
).
Relevant hypotheses in arising in a CLPM are:
autoregX = 0
and autoregY = 0
: Tests the hypothesis that the autoregressive effect of X and Y, respectively, is zero.
crossedX = 0
and crossedY = 0
: Tests the hypothesis that the crossed effect of X on Y (crossedX
) and of Y on X (crossedY
), respectively, is zero.
autoregX = autoregY
: Tests the hypothesis that the autoregressive effect of X and Y are equal.
crossedX = crossedY
: Tests the hypothesis that the crossed effect of X on Y (crossedX
) and of Y on X (crossedY
) are equal.
autoregX
and autoregY
: Tests the hypothesis that the autoregressive effect of X and Y, respectively, is equal across waves.
crossedX
and crossedY
: Tests the hypothesis that the crossed effect of X on Y (crossedX
) and of Y on X (crossedY
), respectively, is equal across waves.
corXY
: Tests the hypothesis that the (residual-)correlations between X and Y are equal across waves.
autoregXA = autoregXB
and autoregYA = autoregYB
: Tests the hypothesis that the autoregressive effect of either X or Y are equal across groups.
crossedXA = crossedXB
and crossedYA = crossedYB
: Tests the hypothesis that the crossed effect of X on Y (crossedX
) or of Y on X (crossedY
), respectively, is equal across groups.
For hypotheses regarding the random-intercept CLPM, see semPower.powerRICLPM()
. For hypothesis in autoregressive models, see semPower.powerAutoreg()
.
Beyond the arguments explicitly contained in the function call, additional arguments are required specifying the factor model and the requested type of power analysis.
Additional arguments related to the definition of the factor model:
Lambda
: The factor loading matrix (with the number of columns equaling the number of factors).
loadings
: Can be used instead of Lambda
: Defines the primary loadings for each factor in a list structure, e. g. loadings = list(c(.5, .4, .6), c(.8, .6, .6, .4))
defines a two factor model with three indicators loading on the first factor by .5, , 4., and .6, and four indicators loading on the second factor by .8, .6, .6, and .4.
nIndicator
: Can be used instead of Lambda
: Used in conjunction with loadM
. Defines the number of indicators by factor, e. g., nIndicator = c(3, 4)
defines a two factor model with three and four indicators for the first and second factor, respectively. nIndicator
can also be a single number to define the same number of indicators for each factor.
loadM
: Can be used instead of Lambda
: Used in conjunction with nIndicator
. Defines the loading either for all indicators (if a single number is provided) or separately for each factor (if a vector is provided), e. g. loadM = c(.5, .6)
defines the loadings of the first factor to equal .5 and those of the second factor do equal .6.
So either Lambda
, or loadings
, or nIndicator
and loadM
need to be defined.
If the model contains observed variables only, use Lambda = diag(x)
where x
is the number of variables.
Note that the order of the factors is (X1, Y1, X2, Y2, ..., X_nWaves, Y_nWaves), i. e., the first factor is treated as the first measurement of X, the second as the first measurement of Y, the third as the second measurement of X, etc..
Additional arguments related to 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.
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 |
SigmaHat |
the H0 model implied covariance matrix. A list for multiple group models. |
muHat |
the H0 model implied mean vector or |
modelH0 |
|
modelH1 |
|
simRes |
detailed simulation results when a simulated power analysis ( |
semPower.genSigma()
semPower.aPriori()
semPower.postHoc()
semPower.compromise()
## Not run:
# Determine required N in a 2-wave CLPM
# to detect a crossed-effect of X (X1 -> Y2) of >= .2
# with a power of 95% on alpha = 5%, where
# X1 and X2 are measured by 5 indicators loading by .5 each, and
# Y1 and Y2 are measured by 3 indicators loading by .6 each, and
# there is no synchronous correlation between X and Y (rXY = NULL),
# the stability of X is .8,
# the stability of Y is .7, and
# the crossed-effect of Y (Y1 -> X2) is .1.
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
alpha = .05, beta = .05)
# show summary
summary(powerCLPM)
# optionally use lavaan to verify the model was set-up as intended
lavaan::sem(powerCLPM$modelH1, sample.cov = powerCLPM$Sigma,
sample.nobs = powerCLPM$requiredN,
sample.cov.rescale = FALSE)
lavaan::sem(powerCLPM$modelH0, sample.cov = powerCLPM$Sigma,
sample.nobs = powerCLPM$requiredN,
sample.cov.rescale = FALSE)
# same as above, but determine power with N = 500 on alpha = .05
powerCLPM <- semPower.powerCLPM(type = 'post-hoc',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
alpha = .05, N = 500)
# same as above, but determine the critical chi-square with N = 500 so that alpha = beta
powerCLPM <- semPower.powerCLPM(type = 'compromise',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
abratio = 1, N = 500)
# same as above, but compare to the saturated model
# (rather than to the less restricted model)
powerCLPM <- semPower.powerCLPM(type = 'compromise',
comparison = 'saturated',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
abratio = 1, N = 500)
# same as above, but assume only observed variables
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = 0',
Lambda = diag(4),
alpha = .05, beta = .05)
# same as above, but provide reduced loadings matrix to define that
# X1 and X2 are measured by 5 indicators each loading by .4, .5, .6, .5, .4
# Y1 and Y2 are measured by 3 indicators each loading by .8, .6, .7
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = 0',
loadings = list(
c(.4, .5, .6, .5, .4), # X1
c(.8, .6, .7), # Y1
c(.4, .5, .6, .5, .4), # X2
c(.8, .6, .7) # Y2
),
alpha = .05, beta = .05)
# same as above, but do not assume metric invariance across waves
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
metricInvariance = FALSE,
alpha = .05, beta = .05)
# same as above, but determine N to detect that the crossed-effect of Y (Y1 -> X2) is >= .1.
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedY = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
alpha = .05, beta = .05)
# same as above, but determine N to detect that the stability of X (X1 -> X2) is >= .8.
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'autoregX = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
alpha = .05, beta = .05)
# same as above, but determine N to detect that the stability of Y (Y1 -> Y2) is >= .7.
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'autoregY = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
alpha = .05, beta = .05)
# same as above, but determine N to detect that
# the crossed effect of X (X1 -> Y2) of .2 differs from
# the crossed effect of Y (Y1 -> X2) of .1
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = crossedY',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
alpha = .05, beta = .05)
# same as above, but determine N to detect that
# the autoregressive effect of X (X1 -> X2) of .8 differs from
# the autoregressive effect of Y (Y1 -> Y2) of .7
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'autoregX = autoregY',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
alpha = .05, beta = .05)
# same as above, but assume that the synchronous correlation between X and Y
# is .3 at the first wave, and the respective residual correlation is .2 at the second wave,
# and determine N to detect that synchronous residual correlation (at wave 2) is => .2.
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = c(.3, .2),
nullEffect = 'corXY = 0',
nIndicator = c(5, 3, 5, 3),
loadM = c(.5, .6, .5, .6),
alpha = .05, beta = .05)
# Determine required N in a 3-wave CLPM
# to detect a crossed-effect of X (X1 -> Y2 and X2 -> Y3) of >= .2
# with a power of 95% on alpha = 5%, where
# the crossed, autoregressive, and synchronous effects of X and Y are equal over waves,
# X1, X2, and X3 are measured by 5 indicators loading by .5 each, and
# Y1, Y2, and Y3 are measured by 3 indicators loading by .6 each, and
# the synchronous correlation between X and Y are .2 across all three waves, and
# the stability of X is .8 across all three waves,
# the stability of Y is .7 across all three waves, and
# the crossed-effect of Y (Y1 -> X2, and Y2 -> Y3) is .1.
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 3,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = c(.2, .2, .2),
waveEqual = c('autoregX', 'autoregY',
'crossedX', 'crossedY'),
nullEffect = 'crossedX = 0',
nIndicator = c(5, 3, 5, 3, 5, 3),
loadM = c(.5, .6, .5, .6, .5, .6),
alpha = .05, beta = .05)
# Determine required N in a 3-wave CLPM to detect that
# the crossed-effect of X in wave 1 (X1 -> Y2) of .20 is equal to the
# the crossed-effect of X in wave 2 (X2 -> Y3) of .10
# with a power of 95% on alpha = 5%, where
# the autoregressive effects of X and Y are equal over waves,
# X1, X2, and X3 are measured by 5 indicators loading by .5 each, and
# Y1, Y2, and Y3 are measured by 3 indicators loading by .6 each, and
# the synchronous correlation between X and Y are .2, .3, and .4 at the first,
# second, and third wave, and
# the stability of X is .8 across all three waves,
# the stability of Y is .7 across all three waves, and
# the crossed-effects of Y (Y1 -> X2, and Y2 -> X3) are both .1
# (but freely estimated for each wave).
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 3,
autoregEffects = c(.8, .7),
crossedEffects = list(
c(.20, .10), # X1 -> Y2, X2 -> Y3
c(.05, .10)), # Y1 -> X2, Y2 -> X3
rXY = c(.2, .3, .4),
nullEffect = 'crossedX',
waveEqual = c('autoregX', 'autoregY'),
nIndicator = c(5, 3, 5, 3, 5, 3),
loadM = c(.5, .6, .5, .6, .5, .6),
alpha = .05, beta = .05)
# same as above, but determine N to detect that
# the crossed-effect of X at wave 2 is >= .10.
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 3,
autoregEffects = c(.8, .7),
crossedEffects = list(
c(.20, .10), # X1 -> Y2, X2 -> Y3
c(.05, .10)), # Y1 -> X2, Y2 -> X3
rXY = c(.2, .3, .4),
nullEffect = 'crossedX',
nullWhich = 2,
waveEqual = c('autoregX', 'autoregY'),
nIndicator = c(5, 3, 5, 3, 5, 3),
loadM = c(.5, .6, .5, .6, .5, .6),
alpha = .05, beta = .05)
# same as above, but determine N to detect that
# the residual correlation between X and Y at wave 2 (of .3) differs from
# the residual correlation between X and Y at wave 3 (of .4)
# and define unstandardized parameters
powerCLPM <- semPower.powerCLPM(type = 'a-priori',
nWaves = 3,
autoregEffects = c(.8, .7),
crossedEffects = list(
c(.20, .10), # X1 -> Y2, X2 -> Y3
c(.05, .10)), # Y1 -> X2, Y2 -> X3
rXY = c(.2, .3, .4),
nullEffect = 'corXY',
waveEqual = c('autoregX', 'autoregY'),
standardized = FALSE,
nIndicator = c(5, 3, 5, 3, 5, 3),
loadM = c(.5, .6, .5, .6, .5, .6),
alpha = .05, beta = .05)
# multiple group example
# determine power in a 3-wave CLPM to detect that
# the autoregressive effect of X in group 1 (of .8) differs from the
# autoregressive effect of X in group 2 (of .6)
# with a 500 observations in both groups on alpha = 5%, where
# the autoregressive effects of X and Y are equal over waves (but not across groups),
# the cross-lagged effects of X and Y are equal over waves (and also across groups),
# X1, X2, and X3 are measured by 5 indicators loading by .5 each, and
# Y1, Y2, and Y3 are measured by 3 indicators loading by .4 each, and
# there are no synchronous correlation between X and Y.
powerCLPM <- semPower.powerCLPM(type = 'post-hoc', alpha = .05, N = list(500, 500),
nWaves = 3,
autoregEffects = list(
# group 1
list(c(.8, .8), # X1 -> X2, X2 -> X3
c(.7, .7)), # Y1 -> Y2, Y2 -> Y3
# group 2
list(c(.6, .6), # X1 -> X2, X2 -> X3
c(.7, .7)) # Y1 -> Y2, Y2 -> Y3
),
crossedEffects = c(.2, .1),
waveEqual = c('autoregX', 'autoregY', 'crossedX', 'crossedY'),
rXY = NULL,
nullEffect = 'autoregxa=autoregxb',
nIndicator = c(5, 3, 5, 3, 5, 3),
loadM = c(.5, .4, .5, .4, .5, .4))
# request a simulated post-hoc power analysis with 500 replications.
set.seed(300121)
powerCLPM <- semPower.powerCLPM(type = 'post-hoc',
nWaves = 2,
autoregEffects = c(.8, .7),
crossedEffects = c(.2, .1),
rXY = NULL,
nullEffect = 'crossedX = 0',
Lambda = diag(4),
alpha = .05, N = 500,
simulatedPower = TRUE,
simOptions = list(nReplications = 500))
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.