ci_bound_ur_i: Likelihood-Based Confidence Bound By Root Finding

In semlbci: Likelihood-Based Confidence Interval in Structural Equation Models

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:

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

References

Wu, H., & Neale, M. C. (2012). Adjusted confidence intervals for a bounded parameter. Behavior Genetics, 42(6), 886-898. \Sexpr[results=rd]{tools:::Rd_expr_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

semlbci documentation built on June 22, 2024, 10:55 a.m.