Likelihood-based Confidence Bound By Wu-Neale-2012

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.

Value

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

bound: A single number. The value of the bound located. NA is the search failed for various reasons.
diag: A list of diagnostic information.
call: The original call.

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

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.

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

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
#> Target Parameter:       m ~ x (group = 1, block = 1)
#> Position:               1
#> Which Bound:            Lower Bound
#> Method:                 Wu-Neale-2012
#> Confidence Level:       0.95
#> Achieved Level:         0.950000000054991
#> Standardized:           No
#> Likelihood-Based Bound: 0.8277
#> Wald Bound:             0.83177
#> Point Estimate:         1.67613
#> Ratio to Wald Bound:    1.00482
#> 
#> -- Check --
#> Level achieved?         Yes (Difference: 5.4991e-11; Tolerance: 5e-04)
#> Solution admissible?    Yes
#> Direction valid?        Yes
#> 
#> -- Optimization Information --
#> Solver Status:          4
#> Convergence Message:    NLOPT_XTOL_REACHED: Optimization stopped because xtol_rel or xtol_abs (above) was reached.
#> Iterations:             3
#> Termination Conditions:
#> 	xtol_rel: 1e-05
#> 	ftol_rel: 1e-05
#> 	maxeval:  500
#> 	maxtime: 300
#> 
#> -- Parameter Estimates --
#>             m~x     y~m     m~~m     y~~y    x~~x
#> Start   0.83177 0.53508 35.37699 40.11896 0.93513
#> Final   0.82770 0.53508 35.37711 40.11896 0.93513
#> Change -0.00407 0.00000  0.00011  0.00000 0.00000
#> 
#> Bound before check:     0.8277
#> Status Code:            0
#> Call: ci_bound_wn_i(i = 1, npar = 5, sem_out = fit_med, f_constr = fn_constr0, 
#>     which = "lbound")
#>

Likelihood-based Confidence Bound By Wu-Neale-2012

Usage

Arguments

Value

Details

Important Notice

Usage

Algorithm

Limitation(s)

References

See also

Examples