Find a Likelihood-Based Confidence Bound By Root Finding

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.

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

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.

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)
#>   id lhs op rhs user block group free ustart exo label plabel  start    est
#> 1  1   m  ~   x    1     1     1    1     NA   0         .p1.  1.676  1.676
#> 2  2   y  ~   m    1     1     1    2     NA   0         .p2.  0.535  0.535
#> 3  3   m ~~   m    0     1     1    3     NA   0         .p3. 34.710 34.710
#> 4  4   y ~~   y    0     1     1    4     NA   0         .p4. 40.119 40.119
#> 5  5   x ~~   x    0     1     1    5     NA   0         .p5.  0.935  0.935
#>      se
#> 1 0.431
#> 2 0.073
#> 3 3.471
#> 4 4.012
#> 5 0.094
# 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
#> $bound
#> [1] 0.39075
#> 
#> $optimize_out
#> $optimize_out$root
#> [1] 0.39075
#> 
#> $optimize_out$f.root
#> [1] -0.001045157
#> 
#> $optimize_out$iter
#> [1] 0
#> 
#> $optimize_out$init.it
#> [1] NA
#> 
#> $optimize_out$estim.prec
#> [1] 5e-05
#> 
#> 
#> $sem_out_bound
#> lavaan 0.6.17 ended normally after 39 iterations
#> 
#>   Estimator                                         ML
#>   Optimization method                           NLMINB
#>   Number of model parameters                         5
#>   Number of equality constraints                     1
#> 
#>   Number of observations                           200
#> 
#> Model Test User Model:
#>                                                       
#>   Test statistic                                14.389
#>   Degrees of freedom                                 2
#>   P-value (Chi-square)                           0.001
#> 
#> $lrt
#> 
#> Chi-Squared Difference Test
#> 
#>               Df    AIC    BIC  Chisq Chisq diff   RMSEA Df diff Pr(>Chisq)  
#> sem_out        1 3147.1 3163.6 10.549                                        
#> sem_out_final  2 3148.9 3162.1 14.389     3.8404 0.11917       1    0.05003 .
#> ---
#> Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
#> 
#> $bound_start
#> [1] NA
#> 
#> $user_est
#> [1] NA
#>