ci_bound_ur {semlbci}

Find a Likelihood-Based Confidence Bound By Root Finding

Description

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() using uniroot().

Usage

ci_bound_ur(
  sem_out,
  func,
  ...,
  level = 0.95,
  which = c("lbound", "ubound"),
  interval = NULL,
  progress = FALSE,
  method = "uniroot",
  lrt_method = "default",
  tol = 5e-04,
  root_target = c("chisq", "pvalue"),
  d = 5,
  uniroot_extendInt = switch(which, lbound = "downX", ubound = "upX"),
  uniroot_trace = 0,
  uniroot_maxiter = 1000,
  use_callr = TRUE,
  rs = NULL
)

gen_est_i(i, sem_out, standardized = FALSE)

Arguments

sem_out

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

func

A function that receives a lavaan object and returns a scalar. This function is to be used by gen_userp() and so there are special requirements on it. Alternatively, it can be the output of gen_est_i().

...

Optional arguments to be passed to func. Usually not used but included in case the function has such arguments.

level

The level of confidence of the confidence interval. Default is .95, or 95%.

which

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

interval

A numeric vector of two values, which is the initial interval to be searched. If NULL, the default, it will be determined internally using Wald or delta method confidence interval, if available.

progress

Whether progress will be reported on screen during the search. Default is FALSE.

method

The actual function to be used in the search. which can only be "uniroot", the default, for now. May include other function in the future.

lrt_method

The method used in lavaan::lavTestLRT(). Default is "default". It is automatically set to "satorra.2000" and cannot be overridden if a scaled test statistic is requested in sem_out.

tol

The tolerance used in uniroot(), default is .005.

root_target

Whether the chi-square difference ("chisq"), the default, or its p-value ("pvalue") is used as the function value in finding the root. Should have little impact on the results.

d

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

uniroot_extendInt

To be passed to the argument extendInt of uniroot(). Whether the interval should be extended if the root is not found. Default value depends on the bound to be searched. Refer to the help page of uniroot() for possible values.

uniroot_trace

To be passed to the argument trace of uniroot(). How much information is printed during the search. Default is 0, and no information is printed during the search. Refer to the help page of uniroot() for possible values.

uniroot_maxiter

The maximum number of iteration in the search. Default is 1000.

use_callr

Whether the callr package will be used to do the search in a separate R process. Default is TRUE. Should not set to FALSE if used in an interactive environment unless this is intentional.

rs

Optional. If set to a persistent R process created by callr, it will be used instead of starting a new one, and it will not be terminated on exit.

i

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

standardized

If TRUE, the standardized estimate is to be retrieved. Default is FALSE. Only support "std.all" for now.

Details

This function is called xby ci_bound_ur_i(). This function is exported because it is a stand-alone function that can be used directly for any function that receives a lavaan object and returns a scalar.

The function ci_bound_ur_i() is a wrapper of this function, with an interface similar to that of ci_bound_wn_i() and returns a cibound-class object. The user-parameter function is generated internally by ci_bound_wn_i().

This function, on the other hand, requires users to supply the function directly through the func argument. This provides the flexibility to find the bound for any function of the model parameter, even one that cannot be easily coded in lavaan model syntax.

Value

The function ci_bound_ur() returns a list with the following elements:

• bound: The bound found.

• optimize_out: THe output of the root finding function, uniroot() for now. (Called optimize_out because an earlier version of this function also uses optimize()).

• sem_out_bound: The lavaan model with the user-defined parameter fixed to the bound.

• lrt: The output of lavaan::lavTestLRT() comparing sem_out and sem_out_bound.

• bound_start: The Wald or delta method confidence bound returned when determining the interval internally.

• user_est: The estimate of the user-defined parameter when determining the interval internally.

The function gen_est_i() returns a special function can inspects the Model slot (and implied slot if necessary) of a modified lavaan object and return the parameter estimate. This function is to be used by ci_bound_ur() or gen_sem_out_userp().

Examples

library(lavaan)
data(simple_med)
dat <- simple_med
mod <-
"
m ~ x
y ~ m
"
fit_med <- lavaan::sem(mod, simple_med, fixed.x = FALSE)
parameterTable(fit_med)
# Create a function to get the second parameter
est_i <- gen_est_i(i = 2, sem_out = fit_med)
# Find the lower bound of the likelihood-based confidence interval
# of the second parameter.
# user_callr should be TRUE or omitted in read research.
# Remove interval in read research. It is added to speed up the example.
out1l <- ci_bound_ur(sem_out = fit_med,
                     func = est_i,
                     which = "lbound",
                     use_callr = FALSE,
                     interval = c(.39070, .39075))
out1l