`lavInspect()` with `what = "coef"` does not return what mentioned in the help page

[sfcheung]

According to the help page, with what = "coef", lavInspect() returns this:

Numeric. The estimated parameter vector.

However, what it actually returns is the model matrices with parameter estimates, identical to what it returns with what = "est":

library(lavaan)
#> This is lavaan 0.6-16
#> lavaan is FREE software! Please report any bugs.
HS.model <- ' visual  =~ x1 + x2 + x3
              textual =~ x4 + x5 + x6
              speed   =~ x7 + x8 + x9 '
fit <- cfa(HS.model, data = HolzingerSwineford1939)
lavInspect(fit, "coef")
#> $lambda
#>    visual textul speed
#> x1  1.000  0.000 0.000
#> x2  0.554  0.000 0.000
#> x3  0.729  0.000 0.000
#> x4  0.000  1.000 0.000
#> x5  0.000  1.113 0.000
#> x6  0.000  0.926 0.000
#> x7  0.000  0.000 1.000
#> x8  0.000  0.000 1.180
#> x9  0.000  0.000 1.082
#> 
#> $theta
#>       x1    x2    x3    x4    x5    x6    x7    x8    x9
#> x1 0.549                                                
#> x2 0.000 1.134                                          
#> x3 0.000 0.000 0.844                                    
#> x4 0.000 0.000 0.000 0.371                              
#> x5 0.000 0.000 0.000 0.000 0.446                        
#> x6 0.000 0.000 0.000 0.000 0.000 0.356                  
#> x7 0.000 0.000 0.000 0.000 0.000 0.000 0.799            
#> x8 0.000 0.000 0.000 0.000 0.000 0.000 0.000 0.488      
#> x9 0.000 0.000 0.000 0.000 0.000 0.000 0.000 0.000 0.566
#> 
#> $psi
#>         visual textul speed
#> visual   0.809             
#> textual  0.408  0.979      
#> speed    0.262  0.173 0.384

^{Created on 2023-07-26 with reprex v2.0.2}

This appears to be an intentional behavior:

lavaan/R/lav_object_inspect.R

Lines 372 to 379 in 6f047c8

	} else if(what == "coef") {
	# this breaks simsem and semTools -- 0.6-1
	#lav_object_inspect_coef(object, type = "free",
	# add.labels = add.labels, add.class = add.class)
	lav_object_inspect_modelmatrices(object, what = "est",
	type = "free", add.labels = add.labels, add.class = add.class,
	list.by.group = list.by.group,
	drop.list.single.group = drop.list.single.group)

Based on the comment, I believe it is the help page that should be amended. what = "coef" was originally intended to work as described in the help page, giving what coef() gives. However, I guess it was changed to what what = "est" gives for compatibility reasons.

Or should a new value, say "coef_vector" or something like that, can be added such that lavInspect() with what = "coef.vector" can be used to give the vector of estimates, as mentioned in the help page?

For now, the only way to access lav_object_inspect_coef() without using ::: is to call coef(). I believe "coef" exists in lavInspect() for a reason, even though users can call coef().

[sfcheung]

Another idea came to me.

How about removing "coef" from the help page, though it will still work? For others who have been using "coef", they know what it does and so nothing will be broken. We can then replace "coef" by, say, "optim.x" to return object@optim.x, the parameters actually used in the optimization, which may be different from the output of coef() (e.g., when simple equality constraints are present).

This is consistent with the placement of the argument, which is under the section Optimizer information. So, naturally, users expect it returns things related to the optimization. It is new and so it won't break any other packages or script. Even if what = "coef" works as described, returning what coef() returns, its placement under Optimizer information sounds strange.

[yrosseel]

You were quite right: lavInspect(fit, "coef") was supposed to work as described in the man page, but it broke semtools/simsem, and that is why the behavior is now inconsistent with the man page.
Following your suggestion, I have simply removed "coef" from the man page of lavInspect/lavTech. The coef() function is equally convenient. Alternatively, lavInspect(fit, "optim")$x can also be used.