power_search: Search function to find N for desired power

In powerNLSEM: Simulation-Based Power Estimation (MSPE) for Nonlinear SEM

Search function to find N for desired power

Description

The function that initializes the search process. The powerNLSEM function actually is a wrapper function for power_search.

Usage

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()
)

Arguments

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 "adaptive" (synonyme is "smart"). Alternative is "bruteforce".
power_modeling_method	Power modeling method used to model significant parameter estimates. Default to "probit" indicating glm with probit link function with sqrt(n) as predictor. Alternative is "logit".
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 .05.
alpha_power_modeling	Type I-error rate for confidence band around predicted power rate. Used to ensure that the computed N keeps the desired power value (with the given Type I-error rate alpha_power_modeling divided by 2). If set to 1, no confidence band is used. Default to .05.
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 NULL.
N_start	Starting sample size for smart algorithm. Default to 10*nrow(lavModel[lavModel$op != "~1", ]) (10 times the number of parameters, excluding the mean structure, without the generation of e.g., factor scores or product indicators).
distRj	Indicator how the samples sizes should be used in the steps of the smart algorithm: "u" for many to few to many, "increasing" for increasing replications and "even" for evenly distributed replications across steps. Default to "u".
steps	Steps used in search_method = "smart", i.e., the smart algorithm. This is ignored if bruteforce is used. Default to 10.
nlb	Lower bound of N used in search. Default to 5*nrow(lavModel[lavModel$op != "~1", ]) (5 times the number of parameters, excluding the mean structure, in the model without the generation of e.g., factor scores or product indicators), however, some methods can deal with much smaller sample sizes so this can be adjusted. The rule of thumb of 5 times number of parameters is motivated by Wolf et al. (2013)
switchStep	Steps after which smart search method changes from exploration to exploitation. Default to round(steps/2). Exploration phase searches for the interval for N so that the resulting power is within [.15, .85] since the power curve is steepest at .5 and becomes less step towards plus/min Inf. Exploitation phase searches for an interval for N around the power_aim argument which shrinks from plus/minus .1 to .01. If swicthStep = Inf, then only exploration is used. If switchStep is used then the search process is reset at that point, which results in a new estimation in the bounds of the interval of N independent of the previous ones which might be restricted in change (see also argument( constrainRelChange).
FSmethod	Method to be used to extract factor scores. Default to "SL" for the Skrondal and Laake approach that uses regression ("regression") factor scores for the independendent variables and "Bartlett" factor scores for the dependent variables.
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 "onesided".
matchPI	Logical passed to semTools::indProd in order to compute the product indicators: Specify TRUE to use match-paired approach (Marsh, Wen, & Hau, 2004). If FALSE, the resulting products are all possible products. Default to TRUE. The observations are matched by order given when specifying the measurement model.
PIcentering	String indicating which method of centering should be used when constructing product indicators. String is converted to the arguments meanC, doubleMC, and residualMC, of the semTools::indProd function. Default to "doubleMC" for double mean centering the resulting products (Lin et. al., 2010). Use "meanC" for mean centering the main effect indicator before making the products or "residualC" for residual centering the products by the main effect indicators (Little, Bovaird, & Widaman, 2006). "none" or any other input than the previously described results in no centering (use with caution!).
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 FALSE. Being liberal is not adviced and should be checked for a single data set!
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 R) but results in biased estimates if the number of steps is too small. Default to TRUE.
seeds	Seeds for reproducibility.
pathLMS	path where (temporal) data and scripts for running LMS using Mplus are stored (using MplusAutomation). Default to NULL, then tempdir() is used.

Value

Returns a list that includes the results on model-implied simulation-based power estimation.

References

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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1177/0013164413495237")}

Irmer, J. P., Klein, A. G., & Schermelleh-Engel, K. (2024). Behavior Research Methods, 0(00), Advance Online Publication.

powerNLSEM documentation built on Sept. 27, 2024, 5:10 p.m.