ci_bound_ur_i {semlbci}R Documentation

Likelihood-Based Confidence Bound By Root Finding

Description

Using root finding 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_ur_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,
  d = 5,
  ...
)

Arguments

i

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

npar

Ignored by this function. Included consistency in the interface.

sem_out

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

f_constr

Ignored by this function. Included consistency in the interface.

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

Ignored by this function. Included consistency in the interface.

lb_var

Ignored by this function. Included consistency in the interface.

standardized

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

wald_ci_start

Ignored by this function. Included consistency in the interface.

opts

Options to be passed to stats::uniroot(). 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

Ignored by this function. Included consistency in the interface.

sf2

Ignored by this function. Included consistency in the interface.

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

Ignored by this function. Included consistency in the interface.

xtol_rel_factor

Ignored by this function. Included consistency in the interface.

ftol_rel_factor

Ignored by this function. Included consistency in the interface.

lb_prop

Ignored by this function. Included consistency in the interface.

lb_se_k

Ignored by this function. Included consistency in the interface.

d

A value used to determine the width of the interval in the initial search. Larger this value, narrow the interval. Default is 5. Used by ci_bound_ur().

...

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.

For consistency in the interface, most of the arguments in ci_bound_wn_i() are also included in this function, even those not used internally.

Algorithm

This function, unlike ci_bound_wn_i(), use a simple root finding algorithm. Basically, it tries fixing the target parameter to different values until the likelihood ratio test p-value, or the corresponding chi-square difference, is equal to the value corresponding to the desired level of confidence. (Internally, the difference between the p-value and the target p-value, that for the chi-square difference, is the function value.)

For finding the bound, this algorithm can be inefficient compared to the one proposed by Wu and Neale (2012). The difference can be less than one second versus 10 seconds. It is included as a backup algorithm for parameters which are difficult for the method by Wu and Neale.

Internally, it uses uniroot() to find the root.

Limitation(s)

This function does not handle an estimate close to an attainable bound using the method proposed by Wu and Neale (2012). Use it for such parameters with cautions.

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

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(); see ci_bound_wn_i() on the version for the method by Wu and Neale (2012).

Examples


library(lavaan)
data(simple_med)
dat <- simple_med
mod <-
"
m ~ x
y ~ m
"
fit_med <- sem(mod, simple_med, fixed.x = FALSE)
# Remove `opts` in real cases.
# The options are added just to speed up the example
out1l <- ci_bound_ur_i(i = 1,
                       sem_out = fit_med,
                       which = "lbound",
                       opts = list(use_callr = FALSE,
                                   interval = c(0.8277, 0.8278)))
out1l
[Package semlbci version 0.11.2 Index]