Help for package semlrtp

Title:

Likelihood Ratio Test P-Values for Structural Equation Models

Version:

0.1.1

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

License:

GPL (≥ 3)

Encoding:

UTF-8

RoxygenNote:

7.3.1

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0)

Config/testthat/edition:

Config/testthat/parallel:

true

Imports:

lavaan, utils, parallel, pbapply

VignetteBuilder:

knitr

URL:

https://sfcheung.github.io/semlrtp/

BugReports:

https://github.com/sfcheung/semlrtp/issues

Config/Needs/website:

rmarkdown

Depends:

R (≥ 4.0.0)

LazyData:

true

NeedsCompilation:

Packaged:

2024-06-19 13:40:40 UTC; shufa

Author:

Shu Fai Cheung

[aut, cre], Mark Hok Chio Lai

[aut]

Maintainer:

Shu Fai Cheung <shufai.cheung@gmail.com>

Repository:

CRAN

Date/Publication:

2024-06-20 16:10:02 UTC

Sample Dataset For Test (16 Items and 2 Groups)

Description

A 16-variable dataset with 336 cases.

Usage

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)

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)

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)

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"
)

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

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

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

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

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

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 = "~")

Print an 'lrt'- Class Object

Description

Print the content of an lrt-class object.

Usage

## 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

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"),
  ...
)

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)

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