Package 'semlrtp' reference manual

Title:	Likelihood Ratio Test P-Values for Structural Equation Models
Description:	Computes likelihood ratio test (LRT) p-values for free parameters in a structural equation model. Currently supports models fitted by the 'lavaan' package by Rosseel (2012) <doi:10.18637/jss.v048.i02>.
Authors:	Shu Fai Cheung [aut, cre] , Mark Hok Chio Lai [aut]
Maintainer:	Shu Fai Cheung <shufai.cheung@gmail.com>
License:	GPL (>= 3)
Version:	0.1.1.2
Built:	2025-03-08 02:14:19 UTC
Source:	https://github.com/sfcheung/semlrtp

Sample Dataset For Test (16 Items and 2 Groups)

Description

A 16-variable dataset with 336 cases.

Usage

data_sem16
data_sem16

Format

A data frame with 336 rows and 16 variables:

x1: Indicator. Numeric.
x2: Indicator. Numeric.
x3: Indicator. Numeric.
x4: Indicator. Numeric.
x5: Indicator. Numeric.
x6: Indicator. Numeric.
x7: Indicator. Numeric.
x8: Indicator. Numeric.
x9: Indicator. Numeric.
x10: Indicator. Numeric.
x11: Indicator. Numeric.
x12: Indicator. Numeric.
x13: Indicator. Numeric.
x14: Indicator. Numeric.
x15: Indicator. Numeric.
x16: Indicator. Numeric.
group: Group with two values, "alpha" and "gamma". Character.

Examples

library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3 + x4
f2 =~ x5 + x6 + x7 + x8
f3 =~ x9 + x10 + x11 + x12
f4 =~ x13 + x14 + x15 + x16
f3 ~ f2 + f1
f4 ~ f3
"
fit <- sem(mod, data_sem16)
summary(fit)
library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3 + x4
f2 =~ x5 + x6 + x7 + x8
f3 =~ x9 + x10 + x11 + x12
f4 =~ x13 + x14 + x15 + x16
f3 ~ f2 + f1
f4 ~ f3
"
fit <- sem(mod, data_sem16)
summary(fit)

Fix a Free Parameter To Zero And Fit a Model Again

Description

It fixes a designated free parameter in a lavaan object to zero and refit the model.

Usage

fix_to_zero(fit, par_id, store_fit = FALSE, se_keep_bootstrap = FALSE)
fix_to_zero(fit, par_id, store_fit = FALSE, se_keep_bootstrap = FALSE)

Arguments

`fit`	A `lavaan`-class object.
`par_id`	An integer. The row number of the free parameter in the parameter table of `fit` to be fixed.
`store_fit`	Logical. If `TRUE`, `fit` will be stored in the output. Default is `FALSE`.
`se_keep_bootstrap`	Logical. If `TRUE` and `fit` used bootstrapping standard error (with `se = "bootstrap"`), bootstrapping will also be use in fitting the restricted model. If `FALSE`, the default, then `se` will be set to `"standard"` if it is `"bootstrap"` in `fit`, to speed up the computation.

Details

It modifies the parameter table of a lavaan-class object and then fits the model again.

Users should usually call lrtp() directly instead of calling this function. It is exported for developers.

Value

A fix_to_zero-class object, which is a list with these elements:

fit0 is the lavaan output of the refitted object. NA if the fit failed for some reasons. To be considered an acceptable solution, the optimization must converge, the solution passes lavaan's post check, the variance-covariance matrix of estimates successfully computed, and the increase in the model degree of freedom equal to the expected change.
fit1 is the original lavaan output if store_fit is TRUE. It is NULL if store_fit is FALSE, the default.
par_id is the row number of the designated free parameter in the parameter table.
call is the original call to this function.
ptable0 is the parameter table with the designated parameter fixed to zero. It can be used for diagnostic purpose if the fit failed.
fit0_error is the error message in refitting the model (ptable0), if any. If no error, it is NA.
vcov_ok is TRUE if the variance-covariance matrix of the estimates can be computed without error nor warning. FALSE otherwise.
vcov_msg is the message generated when using lavaan::lavInspect() to get the variance-covariance matrix of the parameter estimates of the refitted model. If TRUE, then no error nor warning. Can be used for diagnostic purposes.
converged: Whether refitting the modified model (ptable0) converged.
post_check_passed: Whether the solution of the modified model (ptable0) passed lavaan's post check.
post_check_msg: If the solution failed lavaan's post check, it stores the warning message. If the solution passes the check, it is NA.
fit_not_ok: If the fit failed for some reasons, the fit object, if available, is stored in this element rather than in fit0. such that the fit object can be retrieved for diagnostic purposed if necessary.
df_diff_one: Whether the difference in model degrees of freedom between the modified model and the original model is one. If a variance is fitted to zero, related covariance(s) is/are also fitted to zero and so the difference in model degrees of freedom can be legitimately greater than one.
se_force_standard: Whether se was forced to be "standard" even if it is "bootstrap" in fit. If FALSE, then either se is not "bootstrap" in fit or it was not changed in fitting the restricted model.

Author(s)

Shu Fai Cheung https://orcid.org/0000-0002-9871-9448

Examples

library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
"
fit <- sem(mod, data_sem16)
# Fix the factor covariance to zero
out <- fix_to_zero(fit, par_id = 15)
summary(out$fit0)

library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
"
fit <- sem(mod, data_sem16)
# Fix the factor covariance to zero
out <- fix_to_zero(fit, par_id = 15)
summary(out$fit0)

Fix a Free Parameter to Zero and Do an LR Test

Description

Fix the designated free parameter to zero and do a likelihood ratio test.

Usage

lrt(
  fit,
  par_id,
  store_fit = FALSE,
  group = NULL,
  se_keep_bootstrap = FALSE,
  LRT_method = "default",
  scaled.shifted = TRUE,
  fallback_method = "satorra.2000"
)
lrt(
  fit,
  par_id,
  store_fit = FALSE,
  group = NULL,
  se_keep_bootstrap = FALSE,
  LRT_method = "default",
  scaled.shifted = TRUE,
  fallback_method = "satorra.2000"
)

Arguments

`fit`	A `lavaan`-class object.
`par_id`	It can be an integer. or a string. If it is an integer, it should be the row number of the free parameter in the parameter table of `fit` to be fixed to zero. If it is a string, it must be a valid `lavaan` model syntax for a parameter, or the label of a labelled parameter.
`store_fit`	Logical. If `TRUE`, `fit` will be stored in the output. Default is `FALSE`.
`group`	If a model syntax is used in `par_id` and the model is a multigroup model, this should be either the group label or the group number of the parameter.
`se_keep_bootstrap`	Logical. If `TRUE` and `fit` used bootstrapping standard error (with `se = "bootstrap"`), bootstrapping will also be use in fitting the restricted model. If `FALSE`, the default, then `se` will be set to `"standard"` if it is `"bootstrap"` in `fit`, to speed up the computation.
`LRT_method`	String. Passed to the `method` argument of `lavaan::lavTestLRT()`. Default is `"default"`, and let `lavaan::lavTestLRT()` decide the method based on `fit`.
`scaled.shifted`	Logical. Used when the method used in `lavaan::lavTestLRT()` is `"satorra.2000"`. Default is `TRUE` and a scaled and shifted test statistic is used, the same default of `lavaan::lavTestLRT()`.
`fallback_method`	The default method of `lavaan::lavTestLRT()`, `"satorra.bentler.2001"`, may sometimes fail. If failed, this function will call `lavaan::lavTestLRT()` again using `fallback_method`. which is `"satorra.2000"` by default.

Details

It fixes the designated free parameter in a lavaan output, refit the model, and do a likelihood ratio test comparing this model with the original model.

The model to be fixed is generated by fix_to_zero().

If the parameter to be fixed is a variance, related covariance(s), if any, will also be fixed to zero.

Users should usually call lrtp() directly instead of calling this function. It is exported for developers.

Value

A lrt-class object, which is a list with the following elements:

lrt: The output of lavaan::lavTestLRT(). If there is an error message or warning, it is set to NA.
par_id: The row number of the designated free parameter.
par_label: The label of the designated free parameter, generated by lavaan::lav_partable_labels().
fit1: The original lavaan output, if store_fit is TRUE. NA if store_fit is FALSE, the default.
fix_to_zero: The output of fit_to_zero().
call: The call to this function.
lrt_status: Integer. If 0, then there is no error nor warning in the likelihood ratio test and lavaan::lavTestLRT() returns a table (data.frame) of the test. If -1, then something is wrong, e.g., an error or warning occurred when doing the likelihood ratio test.
lrt_msg: If something went wrong when doing the likelihood ratio test, this is the error or warning message when calling lavaan::lavTestLRT(). If no error nor warning, this is NA.

Author(s)

Shu Fai Cheung https://orcid.org/0000-0002-9871-9448

Examples

library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
"
fit <- sem(mod, data_sem16)
# Fix the factor covariance to zero
out <- lrt(fit, par_id = 15)
out$lrt
parameterEstimates(fit)[15, ]
parameterEstimates(out$fix_to_zero$fit0)[15, ]

# Can use model syntax for par_id

out <- lrt(fit, par_id = "f1 =~ x3")
out$lrt

library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
"
fit <- sem(mod, data_sem16)
# Fix the factor covariance to zero
out <- lrt(fit, par_id = 15)
out$lrt
parameterEstimates(fit)[15, ]
parameterEstimates(out$fix_to_zero$fit0)[15, ]

# Can use model syntax for par_id

out <- lrt(fit, par_id = "f1 =~ x3")
out$lrt

Likelihood Ratio Test P-Values

Description

Compute the likelihood ratio test (LRT) p-values for free parameters in a lavaan output.

Usage

lrtp(
  fit,
  op = c("~", "~~"),
  no_variances = TRUE,
  no_error_variances = TRUE,
  no_error_covariances = TRUE,
  se_keep_bootstrap = FALSE,
  LRT_method = "default",
  scaled.shifted = TRUE,
  fallback_method = "satorra.2000",
  progress = TRUE,
  parallel = FALSE,
  ncores = parallel::detectCores(logical = FALSE) - 1,
  load_balancing = TRUE,
  ...
)
lrtp(
  fit,
  op = c("~", "~~"),
  no_variances = TRUE,
  no_error_variances = TRUE,
  no_error_covariances = TRUE,
  se_keep_bootstrap = FALSE,
  LRT_method = "default",
  scaled.shifted = TRUE,
  fallback_method = "satorra.2000",
  progress = TRUE,
  parallel = FALSE,
  ncores = parallel::detectCores(logical = FALSE) - 1,
  load_balancing = TRUE,
  ...
)

Arguments

`fit`	A `lavaan`-class object.
`op`	A character vector of `lavaan` model syntax operators. Free parameters of these operators will be included, unless excluded by other arguments. Default is `c("~", "~~")`.
`no_variances`	Logical. If `TRUE`, the default, then all free variances are excluded. (Error variances are handled by `no_error_variances`.)
`no_error_variances`	Logical, If `TRUE`, the default, then all free error variances are excluded.
`no_error_covariances`	Logical. If `TRUE`, the default, then all free error covariances are excluded.
`se_keep_bootstrap`	Logical. If `TRUE` and `fit` used bootstrapping standard error (with `se = "bootstrap"`), bootstrapping will also be use in fitting the restricted model. If `FALSE`, the default, then `se` will be set to `"standard"` if it is `"bootstrap"` in `fit`, to speed up the computation.
`LRT_method`	String. Passed to the `method` argument of `lavaan::lavTestLRT()`. Default is `"default"`, and let `lavaan::lavTestLRT()` decide the method based on `fit`.
`scaled.shifted`	Logical. Used when the method used in `lavaan::lavTestLRT()` is `"satorra.2000"`. Default is `TRUE` and a scaled and shifted test statistic is used, the same default of `lavaan::lavTestLRT()`.
`fallback_method`	The default method of `lavaan::lavTestLRT()`, `"satorra.bentler.2001"`, may sometimes fail. If failed, this function will call `lavaan::lavTestLRT()` again using `fallback_method`. which is `"satorra.2000"` by default.
`progress`	Logical. If `TRUE`, the default, a progress bar will be displayed to show the progress (using the `pbapply` package).
`parallel`	Logical. If `TRUE`, parallel processing will be used to compute the LRT p-values for selected parameters. Default is `FALSE`. Set it to `TRUE` if the number of selected parameters is large.
`ncores`	Integer. The number of CPU cores to use if `parallel` is `TRUE`. Default is the number of physical cores (determined by `parallel::detectCores()`) minus 1.
`load_balancing`	Logical. If `TRUE`, the default, and `parallel` is `TRUE`, then load balancing will be used. May shorten the total processing time if the time to compute LRT p-values vary a lot across parameters.
`...`	Optional arguments to be passed to `lavaan::parameterEstimates()`.

Details

It finds free parameters in a lavaan-class object, computes the likelihood ratio test (LRT) p-value for each of them when fixed to zero, and returns a parameter estimates table with the LRT p-values included.

By default, it only computes LRT p-values for regression paths and covariances, except for error covariances. This default can be overridden using arguments such as op, no_variances, no_error_variances, and no_error_covariances.

Technical Details

It first identify the parameters to be processed, and then call lrt() on each of them. Please refer to https://sfcheung.github.io/semlrtp/articles/internal_workflow.html for the internal workflow.

Value

An lrt-class object, which is a data-frame-like object similar to the output of lavaan::parameterEstimates(), with a column LRTp for the LRT p-values, as well as other columns such as the chi-square difference in the test. it has a print method, print.lrtp().

Author(s)

Shu Fai Cheung https://orcid.org/0000-0002-9871-9448

Examples


library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
f3 =~ x7 + x8 + x9
f4 =~ x10 + x11 + x12
f2 ~~ f1
f3 ~ f1 + f2
f4 ~ f3
"
fit <- sem(mod, data_sem16)
lrtp(fit)
lrtp(fit, op = "~")

library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
f3 =~ x7 + x8 + x9
f4 =~ x10 + x11 + x12
f2 ~~ f1
f3 ~ f1 + f2
f4 ~ f3
"
fit <- sem(mod, data_sem16)
lrtp(fit)
lrtp(fit, op = "~")

Print an 'lrt'- Class Object

Description

Print the content of an lrt-class object.

Usage

## S3 method for class 'lrt'
print(x, digits = 3, ...)
## S3 method for class 'lrt'
print(x, digits = 3, ...)

Arguments

`x`	An `lrt`-class object.
`digits`	Integer. The number of decimal places to print. Default is 3.
`...`	Optional arguments. Not used.

Details

It is the print method for the output of lrt().

Value

x is returned invisibly. Called for its side effect.

Author(s)

Shu Fai Cheung https://orcid.org/0000-0002-9871-9448

Examples


library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
"
fit <- sem(mod, data_sem16)

out <- lrt(fit, par_id = "f1 ~~ f2")
out

library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
"
fit <- sem(mod, data_sem16)

out <- lrt(fit, par_id = "f1 ~~ f2")
out

Print an 'lrtp'- Class Object

Description

Print the content of an lrtp-class object.

Usage

## S3 method for class 'lrtp'
print(
  x,
  digits = 3,
  lrtp_only = TRUE,
  wald_stats = FALSE,
  output = c("text", "data.frame", "table"),
  ...
)
## S3 method for class 'lrtp'
print(
  x,
  digits = 3,
  lrtp_only = TRUE,
  wald_stats = FALSE,
  output = c("text", "data.frame", "table"),
  ...
)

Arguments

`x`	An `lrtp`-class object.
`digits`	Integer. The number of decimal places to print. Default is 3.
`lrtp_only`	Logical. If `TRUE`, the default, only parameters with LRT p-values will be printed.
`wald_stats`	Logical. If `TRUE`, the usual Wald statistics (e.g., z statistics, p-values, CIs) are printed. `FALSE` by default, assuming that users prefer using LRT statistics when using `lrtp()`.
`output`	The format of the printout. If `"text"`, then the style in the `summary()` of the `lavaan`-class object is used. If `"data.frame"` or `"table"`, then the data frame format of `lavaan::parameterEstimates()` is used.
`...`	Optional arguments. Not used.

Details

The print method for the output of lrtp().

Additional diagnostic information will be printed if one or more likelihood tests encounter some errors or warnings.

Value

x is returned invisibly. Called for its side effect.

Author(s)

Shu Fai Cheung https://orcid.org/0000-0002-9871-9448

Examples


library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
"
fit <- sem(mod, data_sem16)

out <- lrtp(fit)
out
print(out, lrtp_only = FALSE)

library(lavaan)
data(data_sem16)
mod <-
"
f1 =~ x1 + x2 + x3
f2 =~ x4 + x5 + x6
"
fit <- sem(mod, data_sem16)

out <- lrtp(fit)
out
print(out, lrtp_only = FALSE)

Package 'semlrtp'

Help Index

Sample Dataset For Test (16 Items and 2 Groups)

Description

Usage

Format

Examples

Fix a Free Parameter To Zero And Fit a Model Again

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Fix a Free Parameter to Zero and Do an LR Test

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Likelihood Ratio Test P-Values

Description

Usage

Arguments

Details

Technical Details

Value

Author(s)

See Also

Examples

Print an 'lrt'- Class Object

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Print an 'lrtp'- Class Object

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples