Title: | Simulation-Based Power Estimation (MSPE) for Nonlinear SEM |
---|---|
Description: | Model-implied simulation-based power estimation (MSPE) for nonlinear (and linear) SEM, path analysis and regression analysis. A theoretical framework is used to approximate the relation between power and sample size for given type I error rates and effect sizes. The package offers an adaptive search algorithm to find the optimal N for given effect sizes and type I error rates. Plots can be used to visualize the power relation to N for different parameters of interest (POI). Theoretical justifications are given in Irmer et al. (2024a) <doi:10.31219/osf.io/pe5bj> and detailed description are given in Irmer et al. (2024b) <doi:10.3758/s13428-024-02476-3>. |
Authors: | Julien Patrick Irmer [aut, cre, cph] |
Maintainer: | Julien Patrick Irmer <[email protected]> |
License: | GPL-3 |
Version: | 0.1.2 |
Built: | 2024-10-27 06:06:30 UTC |
Source: | https://github.com/jpirmer/powernlsem |
Factor Score Regression approach
FSR(lavModel_Analysis, data, FSmethod = "SL", data_transformations = NULL)
FSR(lavModel_Analysis, data, FSmethod = "SL", data_transformations = NULL)
lavModel_Analysis |
the lavModel_Analysis object |
data |
set to fit |
FSmethod |
Method to be used to extract factor scores. Default to |
data_transformations |
Data transformations |
Returns a data.frame
that includes parameter estimates estimated using FSR.
Similar to: Ng, J. C. K., & Chan, W. (2020). Latent moderation analysis: A factor score approach. Structural Equation Modeling: A Multidisciplinary Journal, 27(4), 629–648. doi:10.1080/10705511.2019.1664304.
Skrondal, A., & Laake, P. (2001). Regression among factor scores. Psychometrika, 66(4), 563-575. doi:10.1007/BF02296196
Latent moderated strctural equations by Klein and Moosbrugger (2000), the ML approach to nonlinear SEM
LMS( lavModel_Analysis, data, data_transformations = NULL, prefix = 1, pathLMS = tempdir(), algorithm = "INTEGRATION" )
LMS( lavModel_Analysis, data, data_transformations = NULL, prefix = 1, pathLMS = tempdir(), algorithm = "INTEGRATION" )
lavModel_Analysis |
the lavModel_Analysis object |
data |
set to fit |
data_transformations |
Object containing info on possible data transformations. |
prefix |
an arbitrary prefix for the data set. This prevents issues when using parallelization and Mplus. |
pathLMS |
path where (temporal) data and scripts for running LMS using Mplus are stored (using |
algorithm |
algorithm to use. Default to INTEGRATION. |
Returns a data.frame
that includes parameter estimates estimated using LMS.
Klein, A. G., & Moosbrugger, H. (2000). Maximum likelihood estimation of latent interaction effects with the LMS method. Psychometrika, 65(4), 457–474. doi:10.1007/BF02296338
plot powerNLSEM object
## S3 method for class 'powerNLSEM' plot( x, test = NULL, plot = "power_model", power_modeling_method = NULL, se = FALSE, power_aim = NULL, alpha = NULL, alpha_power_modeling = NULL, min_num_bins = 10, defaultgg = FALSE, ... )
## S3 method for class 'powerNLSEM' plot( x, test = NULL, plot = "power_model", power_modeling_method = NULL, se = FALSE, power_aim = NULL, alpha = NULL, alpha_power_modeling = NULL, min_num_bins = 10, defaultgg = FALSE, ... )
x |
object of class powerNLSEM |
test |
Should the parameter be tested with a directed hypothesis (onesided) or with an undirected hypothesis (twosided, also equivalent to Wald-Test for single parameter). Default to |
plot |
Character indicating what type of plot to create. Default to |
power_modeling_method |
Character indicating the power modeling method used. This is only relevant when |
se |
Logical indicating to use confidence intervals based on normal approximation using the standard errors. Default to |
power_aim |
Power level to be included into the plot with respective N. If |
alpha |
Alpha value used for confidence intervals, when |
alpha_power_modeling |
Type I-error rate for confidence band around predicted power rate. Used to ensure that the computed |
min_num_bins |
minimal number of bins used for aggregating results. Default to 10. |
defaultgg |
Logical to return default ggplot object. Default to |
... |
Additional arguments passed on to the plot function. |
Returns ggplot
object of the type specified in plot.
# write model in lavaan syntax model <- " # measurement models X =~ 1*x1 + 0.8*x2 + 0.7*x3 Y =~ 1*y1 + 0.85*y2 + 0.78*y3 Z =~ 1*z1 + 0.9*z2 + 0.6*z3 # structural models Y ~ 0.3*X + .2*Z + .2*X:Z # residual variances Y~~.7975*Y X~~1*X Z~~1*Z # covariances X~~0.5*Z # measurement error variances x1~~.1*x1 x2~~.2*x2 x3~~.3*x3 z1~~.2*z1 z2~~.3*z2 z3~~.4*z3 y1~~.5*y1 y2~~.4*y2 y3~~.3*y3 " # run model-implied simulation-based power estimation # for the effects: c("Y~X", "Y~Z", "Y~X:Z") Result_Power <- powerNLSEM(model = model, POI = c("Y~X", "Y~Z", "Y~X:Z"), method = "UPI", search_method = "adaptive", steps = 10, power_modeling_method = "probit", R = 1000, power_aim = .8, alpha = .05, alpha_power_modeling = .05, CORES = 1, seed = 2024) Result_Power plot(Result_Power)
# write model in lavaan syntax model <- " # measurement models X =~ 1*x1 + 0.8*x2 + 0.7*x3 Y =~ 1*y1 + 0.85*y2 + 0.78*y3 Z =~ 1*z1 + 0.9*z2 + 0.6*z3 # structural models Y ~ 0.3*X + .2*Z + .2*X:Z # residual variances Y~~.7975*Y X~~1*X Z~~1*Z # covariances X~~0.5*Z # measurement error variances x1~~.1*x1 x2~~.2*x2 x3~~.3*x3 z1~~.2*z1 z2~~.3*z2 z3~~.4*z3 y1~~.5*y1 y2~~.4*y2 y3~~.3*y3 " # run model-implied simulation-based power estimation # for the effects: c("Y~X", "Y~Z", "Y~X:Z") Result_Power <- powerNLSEM(model = model, POI = c("Y~X", "Y~Z", "Y~X:Z"), method = "UPI", search_method = "adaptive", steps = 10, power_modeling_method = "probit", R = 1000, power_aim = .8, alpha = .05, alpha_power_modeling = .05, CORES = 1, seed = 2024) Result_Power plot(Result_Power)
The function that initializes the search process. The powerNLSEM
function actually is a wrapper function for power_search
.
power_search( POI, method, lavModel, lavModel_Analysis, data_transformations, search_method, power_modeling_method, R = 1000, power_aim = 0.8, alpha = 0.05, alpha_power_modeling = 0.05, CORES, verbose, Ns = NULL, N_start = nrow(lavModel[lavModel$op != "~1", ]) * 10, distRj = "increasing", steps = 10, nlb = nrow(lavModel[lavModel$op != "~1", ]) * 5, switchStep = round(steps/2), FSmethod = "SL", test = "onesided", matchPI = TRUE, PIcentering = "doubleMC", liberalInspection = FALSE, constrainRelChange = TRUE, seeds, pathLMS = tempdir() )
power_search( POI, method, lavModel, lavModel_Analysis, data_transformations, search_method, power_modeling_method, R = 1000, power_aim = 0.8, alpha = 0.05, alpha_power_modeling = 0.05, CORES, verbose, Ns = NULL, N_start = nrow(lavModel[lavModel$op != "~1", ]) * 10, distRj = "increasing", steps = 10, nlb = nrow(lavModel[lavModel$op != "~1", ]) * 5, switchStep = round(steps/2), FSmethod = "SL", test = "onesided", matchPI = TRUE, PIcentering = "doubleMC", liberalInspection = FALSE, constrainRelChange = TRUE, seeds, pathLMS = tempdir() )
POI |
Parameter Of Interest as a vector of strings. Must be in lavaan-syntax without any spaces. Nonlinear effects should have the same ordering as in model. |
method |
Method used to fit to the data. Can be LMS or UPI. |
lavModel |
lavModel object describing the model. |
lavModel_Analysis |
lavModel object containg the parameters to be estimated. |
data_transformations |
Object containing info on data transformations. |
search_method |
String stating the search method. Default to |
power_modeling_method |
Power modeling method used to model significant parameter estimates. Default to |
R |
Total number of models to be fitted. Higher number results in higher precision and longer runtime. |
power_aim |
Minimal power value to approximate. Default to .8. |
alpha |
Type I-error rate for significance decision. Default to |
alpha_power_modeling |
Type I-error rate for confidence band around predicted power rate. Used to ensure that the computed |
CORES |
Number of cores used for parallelization. Default to number of available cores - 2. |
verbose |
Logical whether progress should be printed in console. Default to TRUE. |
Ns |
Sample sizes used in power estimation process. Default to |
N_start |
Starting sample size for smart algorithm. Default to |
distRj |
Indicator how the samples sizes should be used in the steps of the smart algorithm: |
steps |
Steps used in |
nlb |
Lower bound of N used in search. Default to |
switchStep |
Steps after which smart search method changes from exploration to exploitation. Default to |
FSmethod |
Method to be used to extract factor scores. Default to |
test |
Should the parameter be tested with a directed hypothesis (onesided) or with an undirected hypothesis (twosided, also equivalent to Wald-Test for single parameter). Default to |
matchPI |
Logical passed to |
PIcentering |
String indicating which method of centering should be used when constructing product indicators. String is converted to the arguments |
liberalInspection |
Logical whether the inspection of estimation truthworthiness should be very liberal (i.e., allowing for non-positive definite Hessians in standard error estimation or non-positive residual covariance matrices or latent covariance matrices). Default to |
constrainRelChange |
Logical whether the change in the bounds of the interval for N using the smart algorithm should be constrained. This prevents divergence (which is especially an issue for small effect sizes and small |
seeds |
Seeds for reproducibility. |
pathLMS |
path where (temporal) data and scripts for running LMS using Mplus are stored (using |
Returns a list
that includes the results on model-implied simulation-based power estimation.
Wolf, E. J., Harrington, K. M., Clark, S. L., & Miller, M. W. (2013). Sample Size Requirements for Structural Equation Models: An Evaluation of Power, Bias, and Solution Propriety. Educational and Psychological Measurement, 76(6), 913–934. doi:10.1177/0013164413495237
Irmer, J. P., Klein, A. G., & Schermelleh-Engel, K. (2024). Behavior Research Methods, 0(00), Advance Online Publication.
powerNLSEM function
powerNLSEM( model, POI, method, test = "onesided", power_modeling_method = "probit", search_method = "adaptive", R = 2000, power_aim = 0.8, alpha = 0.05, alpha_power_modeling = 0.05, CORES = max(c(parallel::detectCores() - 2, 1)), verbose = TRUE, seed = NULL, ... )
powerNLSEM( model, POI, method, test = "onesided", power_modeling_method = "probit", search_method = "adaptive", R = 2000, power_aim = 0.8, alpha = 0.05, alpha_power_modeling = 0.05, CORES = max(c(parallel::detectCores() - 2, 1)), verbose = TRUE, seed = NULL, ... )
model |
Model in lavaan syntax. See documentation for help and examples. |
POI |
Parameter Of Interest as a vector of strings. Must be in lavaan-syntax without any spaces. Nonlinear effects should have the same ordering as in model. |
method |
Method used to fit to the data. Implemented methods are |
test |
Should the parameter be tested with a directed hypothesis (onesided) or with an undirected hypothesis (twosided, also equivalent to Wald-Test for single parameter). Default to |
power_modeling_method |
Power modeling method used to model significant parameter estimates. Default to |
search_method |
String stating the search method. Default to |
R |
Total number of models to be fitted. Higher number results in higher precision and longer runtime. Default to 2000. |
power_aim |
Minimal power value to approximate. Default to |
alpha |
Type I-error rate for significance decision. Default to |
alpha_power_modeling |
Type I-error rate for confidence band around predicted power rate. Used to ensure that the computed |
CORES |
Number of cores used for parallelization. Default to number of available cores - 2. |
verbose |
Logical whether progress should be printed in console. Default to |
seed |
Seed for replicability. Default to |
... |
Additional arguments passed on to the search functions. |
Returns an list object of class powerNLSEM
.
Klein, A. G., & Moosbrugger, H. (2000). Maximum likelihood estimation of latent interaction effects with the LMS method. Psychometrika, 65(4), 457–474. doi:10.1007/BF02296338
Kelava, A., & Brandt, H. (2009). Estimation of nonlinear latent structural equation models using the extended unconstrained approach. Review of Psychology, 16(2), 123–132.
Lin, G. C., Wen, Z., Marsh, H. W., & Lin, H. S. (2010). Structural equation models of latent interactions: Clarification of orthogonalizing and double-mean-centering strategies. Structural Equation Modeling, 17(3), 374–391. doi:10.1080/10705511.2010.488999
Little, T. D., Bovaird, J. A., & Widaman, K. F. (2006). On the merits of orthogonalizing powered and product terms: Implications for modeling interactions among latent variables. Structural Equation Modeling, 13(4), 497–519. doi:10.1207/s15328007sem1304_1
Marsh, H. W., Wen, Z. & Hau, K. T. (2004). Structural equation models of latent interactions: Evaluation of alternative estimation strategies and indicator construction. Psychological Methods, 9(3), 275–300. doi:10.1037/1082-989X.9.3.275
Ng, J. C. K., & Chan, W. (2020). Latent moderation analysis: A factor score approach. Structural Equation Modeling: A Multidisciplinary Journal, 27(4), 629–648. doi:10.1080/10705511.2019.1664304.
Irmer, J. P., Klein, A. G., & Schermelleh-Engel, K. (2024a). A General Model-Implied Simulation-Based Power Estimation Method for Correctly and Misspecfied Models: Applications to Nonlinear and Linear Structural Equation Models. Behavior Research Methods. doi:10.31219/osf.io/pe5bj
Irmer, J. P., Klein, A. G., & Schermelleh-Engel, K. (2024b). Estimating Power in Complex Nonlinear Structural Equation Modeling Including Moderation Effects: The powerNLSEM R
-Package. Behavior Research Methods. doi:10.3758/s13428-024-02476-3
For further details for specific uses see corresponding functions: power_search()
for all inputs possible, UPI()
for specifics for the unconstrained product indicator approach, LMS()
for the latent moderated structural equations approach, FSR()
for factor score approaches, SR()
for scale regression approaches.
# write model in lavaan syntax model <- " # measurement models X =~ 1*x1 + 0.8*x2 + 0.7*x3 Y =~ 1*y1 + 0.85*y2 + 0.78*y3 Z =~ 1*z1 + 0.9*z2 + 0.6*z3 # structural models Y ~ 0.3*X + .2*Z + .2*X:Z # residual variances Y~~.7975*Y X~~1*X Z~~1*Z # covariances X~~0.5*Z # measurement error variances x1~~.1*x1 x2~~.2*x2 x3~~.3*x3 z1~~.2*z1 z2~~.3*z2 z3~~.4*z3 y1~~.5*y1 y2~~.4*y2 y3~~.3*y3 " # run model-implied simulation-based power estimation # for the effects: c("Y~X", "Y~Z", "Y~X:Z") Result_Power <- powerNLSEM(model = model, POI = c("Y~X", "Y~Z", "Y~X:Z"), method = "UPI", search_method = "adaptive", steps = 10, power_modeling_method = "probit", R = 1000, power_aim = .8, alpha = .05, alpha_power_modeling = .05, CORES = 1, seed = 2024) Result_Power
# write model in lavaan syntax model <- " # measurement models X =~ 1*x1 + 0.8*x2 + 0.7*x3 Y =~ 1*y1 + 0.85*y2 + 0.78*y3 Z =~ 1*z1 + 0.9*z2 + 0.6*z3 # structural models Y ~ 0.3*X + .2*Z + .2*X:Z # residual variances Y~~.7975*Y X~~1*X Z~~1*Z # covariances X~~0.5*Z # measurement error variances x1~~.1*x1 x2~~.2*x2 x3~~.3*x3 z1~~.2*z1 z2~~.3*z2 z3~~.4*z3 y1~~.5*y1 y2~~.4*y2 y3~~.3*y3 " # run model-implied simulation-based power estimation # for the effects: c("Y~X", "Y~Z", "Y~X:Z") Result_Power <- powerNLSEM(model = model, POI = c("Y~X", "Y~Z", "Y~X:Z"), method = "UPI", search_method = "adaptive", steps = 10, power_modeling_method = "probit", R = 1000, power_aim = .8, alpha = .05, alpha_power_modeling = .05, CORES = 1, seed = 2024) Result_Power
print powerNLSEM objects
## S3 method for class 'powerNLSEM' print(x, ...)
## S3 method for class 'powerNLSEM' print(x, ...)
x |
object of class powerNLSEM |
... |
Additional parameters for print |
powerNLSEM
object
print summary for powerNLSEM objects
## S3 method for class 'summary.powerNLSEM' print(x, ...)
## S3 method for class 'summary.powerNLSEM' print(x, ...)
x |
Prints the summary of a |
... |
Further arguments to use in |
Prints output of summmary of powerNLSEM
object into the console (objects of class summary.powerNLSEM
), but does not change object itself.
Reanalyse powerNLSEM object
reanalyse.powerNLSEM( out, test = NULL, powerLevels = NULL, power_modeling_method = NULL, alpha = NULL, alpha_power_modeling = NULL )
reanalyse.powerNLSEM( out, test = NULL, powerLevels = NULL, power_modeling_method = NULL, alpha = NULL, alpha_power_modeling = NULL )
out |
object of class powerNLSEM |
test |
Should the parameter be tested with a directed hypothesis (onesided) or with an undirected hypothesis (twosided, also equivalent to Wald-Test for single parameter). Default to |
powerLevels |
Power levels for which the desired sample sizes should be computed. Needs to be a vector. Default to |
power_modeling_method |
Character indicating the power modeling method used. Default to |
alpha |
Type I-error rate for significance decision. Default to |
alpha_power_modeling |
Type I-error rate for confidence band around predicted power rate. Used to ensure that the computed |
Returns list of desired sample sizes per effect for each powerLevel
. Nall
refers to the sample size required per power level for all coefficients. Npower
is a matrix containing the desired sample sizes per effect for every power level.
simulate data from lavModel object
simulateNLSEM( n, lavModel, appendLVs = FALSE, lavModel_attributes = NULL, matrices = NULL, seed = NULL )
simulateNLSEM( n, lavModel, appendLVs = FALSE, lavModel_attributes = NULL, matrices = NULL, seed = NULL )
n |
sample size |
lavModel |
lavModel object |
appendLVs |
logical whether latent variables should be observed. Default to |
lavModel_attributes |
attributes of the lavModel object. If |
matrices |
computed matrices for simulation. If |
seed |
a seed for reproducability. Default to |
Returns a data.frame
of a simulated NLSEM.
Scale Regression approach
SR(lavModel_Analysis, data, data_transformations = NULL)
SR(lavModel_Analysis, data, data_transformations = NULL)
lavModel_Analysis |
the lavModel_Analysis object |
data |
set to fit |
data_transformations |
Data transformations |
Returns a data.frame
that includes parameter estimates estimated using SR.
Summary function for powerNLSEM objects
## S3 method for class 'powerNLSEM' summary(object, test = NULL, alpha = NULL, ...)
## S3 method for class 'powerNLSEM' summary(object, test = NULL, alpha = NULL, ...)
object |
Result of powerNLSEM function estimating the MSPE. |
test |
Should the parameter be tested with a directed hypothesis (onesided) or with an undirected hypothesis (twosided, also equivalent to Wald-Test for single parameter). Default to |
alpha |
Type I-error rate for significance decision. Default to |
... |
Further arguments to use in |
summary of powerNLSEM object
# write model in lavaan syntax model <- " # measurement models X =~ 1*x1 + 0.8*x2 + 0.7*x3 Y =~ 1*y1 + 0.85*y2 + 0.78*y3 Z =~ 1*z1 + 0.9*z2 + 0.6*z3 # structural models Y ~ 0.3*X + .2*Z + .2*X:Z # residual variances Y~~.7975*Y X~~1*X Z~~1*Z # covariances X~~0.5*Z # measurement error variances x1~~.1*x1 x2~~.2*x2 x3~~.3*x3 z1~~.2*z1 z2~~.3*z2 z3~~.4*z3 y1~~.5*y1 y2~~.4*y2 y3~~.3*y3 " # run model-implied simulation-based power estimation # for the effects: c("Y~X", "Y~Z", "Y~X:Z") Result_Power <- powerNLSEM(model = model, POI = c("Y~X", "Y~Z", "Y~X:Z"), method = "UPI", search_method = "adaptive", steps = 10, power_modeling_method = "probit", R = 1000, power_aim = .8, alpha = .05, alpha_power_modeling = .05, CORES = 1, seed = 2024) Result_Power summary(Result_Power)
# write model in lavaan syntax model <- " # measurement models X =~ 1*x1 + 0.8*x2 + 0.7*x3 Y =~ 1*y1 + 0.85*y2 + 0.78*y3 Z =~ 1*z1 + 0.9*z2 + 0.6*z3 # structural models Y ~ 0.3*X + .2*Z + .2*X:Z # residual variances Y~~.7975*Y X~~1*X Z~~1*Z # covariances X~~0.5*Z # measurement error variances x1~~.1*x1 x2~~.2*x2 x3~~.3*x3 z1~~.2*z1 z2~~.3*z2 z3~~.4*z3 y1~~.5*y1 y2~~.4*y2 y3~~.3*y3 " # run model-implied simulation-based power estimation # for the effects: c("Y~X", "Y~Z", "Y~X:Z") Result_Power <- powerNLSEM(model = model, POI = c("Y~X", "Y~Z", "Y~X:Z"), method = "UPI", search_method = "adaptive", steps = 10, power_modeling_method = "probit", R = 1000, power_aim = .8, alpha = .05, alpha_power_modeling = .05, CORES = 1, seed = 2024) Result_Power summary(Result_Power)
Unconstrained Product Indicator approach by Marsh et al. (2004), with extensions by Kelava and Brandt (2009)
UPI( lavModel_Analysis, data, data_transformations = NULL, matchPI = TRUE, PIcentering = "doubleMC", liberalInspection = FALSE )
UPI( lavModel_Analysis, data, data_transformations = NULL, matchPI = TRUE, PIcentering = "doubleMC", liberalInspection = FALSE )
lavModel_Analysis |
the lavModel_Analysis object |
data |
set to fit |
data_transformations |
Data transformations |
matchPI |
Logical passed to |
PIcentering |
String indicating which method of centering should be used when constructing product indicators. String is converted to the arguments |
liberalInspection |
Logical whether the inspection of estimation truthworthiness should be very liberal (i.e., allowing for non-positive definite Hessians in standard error estimation or non-positive residual covariance matrices or latent covariance matrices). Default to |
Returns a data.frame
that includes parameter estimates estimated using UPI.
Kelava, A., & Brandt, H. (2009). Estimation of nonlinear latent structural equation models using the extended unconstrained approach. Review of Psychology, 16(2), 123–132.
Lin, G. C., Wen, Z., Marsh, H. W., & Lin, H. S. (2010). Structural equation models of latent interactions: Clarification of orthogonalizing and double-mean-centering strategies. Structural Equation Modeling, 17(3), 374–391. doi:10.1080/10705511.2010.488999
Little, T. D., Bovaird, J. A., & Widaman, K. F. (2006). On the merits of orthogonalizing powered and product terms: Implications for modeling interactions among latent variables. Structural Equation Modeling, 13(4), 497–519. doi:10.1207/s15328007sem1304_1
Marsh, H. W., Wen, Z. & Hau, K. T. (2004). Structural equation models of latent interactions: Evaluation of alternative estimation strategies and indicator construction. Psychological Methods, 9(3), 275–300. doi:10.1037/1082-989X.9.3.275
Marsh, H. W., Wen, Z., Hau, K. T., Little, T. D., Bovaird, J. A., & Widaman, K. F. (2007). Unconstrained Structural Equation Models of Latent Interactions: Contrasting Residual- and Mean-Centered Approaches. Structural Equation Modeling: A Multidisciplinary Journal, 14(4), 570-580. doi:10.1080/10705510701303921