ci_bound_wn_i {semlbci}R Documentation

Likelihood-based Confidence Bound By Wu-Neale-2012

Description

User the method proposed by Wu and Neale (2012) to find the lower or upper bound of the likelihood-based confidence interval (LBCI) for one parameter in a structural equation model fitted in lavaan::lavaan().

Usage

ci_bound_wn_i(
  i = NULL,
  npar = NULL,
  sem_out = NULL,
  f_constr = NULL,
  which = NULL,
  history = FALSE,
  perturbation_factor = 0.9,
  lb_var = -Inf,
  standardized = FALSE,
  wald_ci_start = !standardized,
  opts = list(),
  ciperc = 0.95,
  ci_limit_ratio_tol = 1.5,
  verbose = FALSE,
  sf = 1,
  sf2 = 0,
  p_tol = 5e-04,
  std_method = "internal",
  bounds = "none",
  xtol_rel_factor = 1,
  ftol_rel_factor = 1,
  lb_prop = 0.05,
  lb_se_k = 3,
  try_harder = 0,
  fit_lb = -Inf,
  fit_ub = +Inf,
  timeout = 300,
  ...
)

Arguments

i

The position of the target parameter as appeared in the parameter table of an lavaan object, generated by lavaan::parameterTable().

npar

The number of free parameters, including those constrained to be equal.

sem_out

The fit object. Currently supports lavaan::lavaan objects only.

f_constr

The constraint function generated by set_constraint().

which

Whether the lower bound or the upper bound is to be found. Must be "lbound" or "ubound".

history

Not used. Kept for backward compatibility.

perturbation_factor

A number multiplied to the parameter estimates in sem_out. Using the parameter estimates as starting values may lead to errors in the first few iterations. Default is .90. This argument is ignored if wald_ci_start is 'TRUE.

lb_var

The lower bound for free parameters that are variances. If equal to -Inf, the default, lb_prop and lb_se_k will be used to set the lower bounds for free variances. If it is a number, it will be used to set the lower bounds for all free variances.

standardized

If TRUE, the LBCI is for the requested estimate in the standardized solution. Default is FALSE.

wald_ci_start

If TRUE, there are no equality constraints in the model, and the target parameter is not a user-defined parameter, the Wald confidence bounds will be used as the starting value.

opts

Options to be passed to nloptr::nloptr(), the current optimizer. Default is list().

ciperc

The intended coverage probability for the confidence interval. Default is .95, and the bound for a 95% confidence interval will be sought.

ci_limit_ratio_tol

The tolerance for the ratio of a to b, where a is the distance between an LBCI limit and the point estimate, and the b is the distance between the original confidence limit (by default the Wald CI in lavaan::lavaan()) and the point estimate. If the ratio is larger than this value or smaller than the reciprocal of this value, a warning is set in the status code. Default is 1.5.

verbose

If TRUE, the function will store more diagnostic information in the attribute diag. Default is FALSE.

sf

A scaling factor. Used for robust confidence bounds. Default is 1. Computed by an internal function called by semlbci() when robust = "satorra.2000".

sf2

A shift factor. Used for robust confidence bounds. Default is 0. Computed by an internal function called by semlbci() when robust = "satorra.2000".

p_tol

Tolerance for checking the achieved level of confidence. If the absolute difference between the achieved level and ciperc is greater than this amount, a warning is set in the status code and the bound is set to NA. Default is 5e-4.

std_method

The method used to find the standardized solution. If equal to "lavaan", lavaan::standardizedSolution() will be used. If equal to "internal", an internal function will be used. The "lavaan" method should work in all situations, but the "internal" method is usually much faster. Default is "internal".

bounds

Default is "" and this function will set the lower bounds to lb_var for variances. Other valid values are those accepted by lavaan::lavaan(). Ignored for now.

xtol_rel_factor

Multiply the default xtol_rel by a number, usually a positive number equal to or less than 1, to change the default termination criterion. Default is 1.

ftol_rel_factor

Multiply the default ftol_rel by a number, usually a positive number equal to or less than 1, to change the default termination criterion. Default is 1.

lb_prop

Used by an internal function to set the lower bound for free variances. Default is .05, setting the lower bound to .05 * estimate. Used only if the lower bound set by lb_se_k is negative.

lb_se_k

Used by an internal function to set the lower bound for free variances. Default is 3, the estimate minus 3 standard error. If negative, the lower bound is set using lb_prop.

try_harder

If error occurred in the optimization, how many more times to try. In each new attempt, the starting values will be randomly jittered. Default is 0.

fit_lb

The vector of lower bounds of parameters. Default is -Inf, setting the lower bounds to -Inf for all parameters except for free variances which are controlled by lb_var.

fit_ub

The vector of upper bounds of parameters. Default is +Inf, setting the lower bounds to +Inf for all parameters.

timeout

The approximate maximum time for the search, in second. Default is 300 seconds (5 minutes).

...

Optional arguments. Not used.

Details

Important Notice

This function is not supposed to be used directly by users in typical scenarios. Its interface is user-unfriendly because it should be used through semlbci(). It is exported such that interested users can examine how a confidence bound is found, or use it for experiments or simulations.

Usage

This function is the lowest level function used by semlbci(). semlbci() calls this function once for each bound of each parameter. To use it, set_constraint() needs to be called first to create the equality constraint required by the algorithm proposed by Wu and Neale (2012).

Algorithm

This function implements the algorithm presented in Wu and Neale (2012; see also Pek & Wu, 2015, Equation 12) that estimates all free parameters in the optimization.

Limitation(s)

This function does not yet implement the method by Wu and Neale (2012) for an estimate close to an attainable bound.

Value

A cibound-class object which is a list with three elements:

A detailed and organized output can be printed by the default print method (print.cibound()).

References

Pek, J., & Wu, H. (2015). Profile likelihood-based confidence intervals and regions for structural equation models. Psychometrika, 80(4), 1123-1145. doi:10.1007/s11336-015-9461-1

Wu, H., & Neale, M. C. (2012). Adjusted confidence intervals for a bounded parameter. Behavior Genetics, 42(6), 886-898. doi:10.1007/s10519-012-9560-z

See Also

print.cibound(), semlbci(), ci_i_one()

Examples


data(simple_med)
dat <- simple_med

mod <-
"
m ~ x
y ~ m
"

fit_med <- lavaan::sem(mod, simple_med, fixed.x = FALSE)

fn_constr0 <- set_constraint(fit_med)

out1l <- ci_bound_wn_i(i = 1,
                       npar = 5,
                       sem_out = fit_med,
                       f_constr = fn_constr0,
                       which = "lbound")
out1l
[Package semlbci version 0.11.2 Index]