Likelihood-Based Confidence Bound By Root Finding

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.

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.

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.

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

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
#> Target Parameter:       m ~ x (group = 1, block = 1)
#> Position:               1
#> Which Bound:            Lower Bound
#> Method:                 Root Finding
#> Confidence Level:       0.95
#> Achieved Level:         0.950000451126927
#> 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: 4.5113e-07; Tolerance: 5e-04)
#> Solution admissible?    Yes
#> Direction valid?        Yes
#> 
#> -- Optimization Information --
#> Solver Status:          NA
#> Convergence Message:    Nil
#> Iterations:             0
#> Termination Conditions:
#> 	Nil
#> 
#> -- Parameter Estimates --
#>           m~x     y~m     m~~m     y~~y    x~~x
#> Start      NA      NA       NA       NA      NA
#> Final  0.8277 0.53508 35.38344 40.11896 0.93514
#> Change     NA      NA       NA       NA      NA
#> 
#> Bound before check:     0.8277
#> Status Code:            0
#> Call: ci_bound_ur_i(i = 1, sem_out = fit_med, which = "lbound", opts = list(use_callr = FALSE, 
#>     interval = c(0.8277, 0.8278)), f_constr = "<not printed>")
#>

Likelihood-Based Confidence Bound By Root Finding

Usage

Arguments

Value

Details

Important Notice

Usage

Algorithm

Limitation(s)

References

See also

Examples