Learn R Programming

metaSEM (version 2.0)

lavaan2RAM: Convert lavaan models to RAM models

Description

Automatically generated parameter labels that collide with another parameter are made unique with an _auto suffix and a warning.

Variable names and ordinary parameter labels must not contain periods. Rename consistently throughout the model and data, e.g., x.1 to x_1, and check that the new names are unique. Definition-variable references such as data.x_1 remain supported: only the column name following data. must be period-free. Group and cluster values may contain periods.

It converts models specified in lavaan model syntax to RAM models.

Usage

lavaan2RAM(
  model,
  obs.variables = NULL,
  A.notation = "ON",
  S.notation = "WITH",
  M.notation = "mean",
  A.start = 0.1,
  S.start = 0.5,
  M.start = 0,
  auto.var = TRUE,
  std.lv = TRUE,
  ngroups = 1,
  auto.cov.lv.x = FALSE,
  auto.cov.x = FALSE,
  auto.cov.y = FALSE,
  auto.fix.first = FALSE,
  auto.fix.single = FALSE,
  constraints = NULL,
  ...,
  auto = NULL
)

Value

A list of RAM specification with A, S, F, and M matrices. When ngroups > 1, a list of such lists (one per group) is returned instead, with class "RAM_multigroup". When model uses lavaan's two-level syntax (level: 1 / level: 2 blocks), a list with within and between

elements (each themselves a list of A, S, F, and M matrices) is returned instead, with class "RAM_twolevel". Level-1 (within) manifest variables that also appear at level 2 default to a fixed-at-zero mean (the overall intercept lives at the between level by convention), whereas within-only observed variables, which have no between component, default to a free level-1 mean, as in lavaan; level-2 (between) "shadow" variables backing a level-1 manifest variable default to a free mean, while genuine level-2-only latent factors default to fixed-at-zero, mirroring the usual latent-variable convention. Genuine level-2-only observed covariates (e.g. a real cluster-level covariate with its own data column, as opposed to a level-1 manifest variable's between-cluster component) are supported when their data values are constant within each cluster. Models with nested group: and level: blocks and ngroups > 1 return a list of two-level RAM objects with class "RAM_multigroup_twolevel".

Arguments

model

A character string of model using the lavaan model syntax.

obs.variables

A character vector of the observed variables. The observed variables in the RAM specification will follow the order specified in obs.variables. It is important to check whether the order of the observed variables matches the order in the dataset.

A.notation

A character string to be used in the A matrix if the labels are not included in the lavaan model. For example, the label will be "yONx" for regressing "y" on "x".

S.notation

A character string to be used in the S matrix if the labels are not included in the lavaan model. For example, the label will be "yWITHx" for the covariance between "y" with "x" and "yWITHy" for the (error) variance of "y".

M.notation

A character string to be used in the M matrix if the labels are not included in the lavaan model. For example, the label will be "ymean" for the mean of "y" if M.notation="mean".

A.start

A numeric value of starting value for the Amatrix when the starting values are not provided.

S.start

A numeric value of starting value for the Smatrix when the starting values are not provided.

M.start

A numeric value of starting value for the Mmatrix when the starting values are not provided.

auto.var

Logical. If TRUE, the residual variances and the variances of exogenous latent variables are included in the model and set free. See model.syntax.

std.lv

Logical. If TRUE (the default), the metric of each latent variable is determined by fixing their variances to 1.0. If FALSE, no marker loading is fixed automatically: fix a loading or variance in the model, or set auto.fix.first=TRUE. A warning is issued if no fixed nonzero loading or variance, or label constrained to a nonzero constant, is found for a factor; this heuristic is not a complete identification check. std.lv=TRUE fixes a latent variance at 1 unless the model explicitly fixes it to another value, and can override a free "~~" specification in model (e.g. "f ~~ c(vf1,vf2)*f" to free a factor's variance per group) with no error -- the label is simply discarded, since the parameter is fixed rather than estimated. Pass std.lv=FALSE whenever model identifies a latent variable's scale by fixing one of its loadings instead (e.g. "f =~ 1*y1" or "f =~ c(1,1)*y1" for a multiple-group model), which is incompatible with also fixing its variance. lavaan2RAM() warns when this happens (any parameter given an explicit label in model that ends up fixed rather than free), but the warning is general -- checking std.lv first is faster than working backward from it.

ngroups

Positive integer. The number of groups in the model. A numeric character value is accepted with a deprecation warning. See model.syntax. Parameters without an explicit label in model are free and distinct in each group by default (as in lavaan); use lavaan's c(label, label) syntax to constrain a parameter to be equal across groups. Has no effect (and is rejected with an error) on two-level (level:) models unless group: and level: blocks are nested -- see below. Groups are numbered in the order of their group: blocks, whatever their labels (e.g., group: B before group: A), because lavaan and sem pair them with the groups in the data by position. The block labels are stored in the "group.labels" attribute.

auto.cov.lv.x, auto.cov.x, auto.cov.y

Logical, default FALSE. Request lavaan's automatic covariances for exogenous latent variables, exogenous observed variables, and dependent variables, respectively.

auto.fix.first

Logical, default FALSE. Fix the first loading of each factor to one. With std.lv=TRUE this can impose an additional restriction because the latent variance is also fixed.

auto.fix.single

Logical, default FALSE. Fix the residual variance of a single indicator to zero.

constraints

Optional lavaan constraints using explicit parameter labels. Defined parameters and equality and inequality constraints may also be included in model; see the limitations below.

...

Reserved for detecting unsupported arguments. Arbitrary arguments are not passed to lavaanify; use exact argument names. In particular, orthogonal, warn, debug, effect.coding, group.equal, and correlation are not supported. Specify shared group parameters with explicit labels.

auto

Reserved to detect an unsupported argument; do not supply it. It is not lavaan's auto option.

Author

Mike W.-L. Cheung <[email protected]>

Details

Continuous RAM syntax supports regressions, loadings, variances, covariances, means, and the constraints described below. Ordinal thresholds, composites, exploratory factor blocks, scaling operators, and group weights are not supported and are rejected. The returned RAM describes a covariance model; correlation restrictions are handled by the fitting function (for example, cor.analysis in wls or osmasem2).

Automatically generated observed intercepts are free by default. For a free latent mean with one indicator, the indicator intercept defaults to zero for compatibility. With several indicators, specify an identifying intercept constraint; a warning is given when all are free. For two-level models the warning is checked separately at each level and does not impose an identifying constraint.

It uses the model.syntax to do the conversion. Experimental: functions of parameters (`:=` in lavaan) and constraints (`==`, `>`, and `<` in lavaan) will be converted to mxAlgebra and mxConstraint in OpenMx. As there are differences between lavaan and OpenMx, they may not work properly.

An inequality between a parameter and a constant, e.g., b > 0, 2 < c, or lower(0)*x, is converted to a bound on that parameter rather than to an mxConstraint. This includes parameters introduced only in equality expressions. The bounds are stored in the "lbound" and "ubound" attributes of the output (named lists keyed by parameter label) and are applied by sem, wls (and hence tssem2), osmasem, and osmasem2. osmasem ignores, with a warning, bounds on parameters that it computes rather than estimates (e.g., error variances of dependent variables), and its A.lbound and A.ubound arguments take precedence on the A matrix. Other inequalities, e.g., b > 2*a, remain mxConstraints, which OpenMx satisfies within its feasibility tolerance (see mxOption).

See Also

ramModel, Becker92, Becker09, Digman97, Hunter83, as.mxMatrix, checkRAM

Examples

Run this code
## Request an automatic residual covariance between dependent variables.
lavaan2RAM("y ~ x\nz ~ x", auto.cov.y=TRUE)
## Choose a marker-loading scale when the latent variance is not fixed.
lavaan2RAM("f =~ y1 + y2 + y3", std.lv=FALSE, auto.fix.first=TRUE)
## Parameter constraints use explicit labels.
lavaan2RAM("y ~ b*x", constraints="b == 0.5")

## Regression model on correlation matrix
model1 <- "## y is modelled by x1, x2, and x3
           y ~ b1*x1 + b2*x2 + b3*x3
           ## Fix the independent variables at 1
           x1 ~~ 1*x1
           x2 ~~ 1*x2
           x3 ~~ 1*x3
           ## Declare the correlations among the independent variables
           x1 ~~ x2
           x1 ~~ x3
           x2 ~~ x3
           ## Constraint
           b3 == b1 + b2
           ## Function of parameters
           fn1 := b1*b2^b3"

## Compare the arrangements of variables with and without
## specifying the obs.variables arguments. 
lavaan2RAM(model1, obs.variables=c("y", "x1", "x2", "x3"))

## Two-factor CFA model
model2 <- "f1 =~ x1 + x2 + x3
           f2 =~ x4 + x5 + x6
           ## Declare the correlation between f1 and f2
           ## and label it with cor_f1f2
           f1 ~~ cor_f1f2*f2"

lavaan2RAM(model2)

## Regression model with the mean structure
model3 <- "y ~ x
           ## Intercept of y
           y ~ 1
           ## Mean of x
           x ~ 1"

lavaan2RAM(model3)

## Multiple group regression model
## Different intercepts with a common slope
model4 <- "y ~ c(a1, a2)*1 + c(b, b)*x"

lavaan2RAM(model4, ngroups=2)

## Two-level random-intercept regression model
model5 <- "level: 1
             y ~ b1*x
             y ~~ residW*y
           level: 2
             y ~ 1
             y ~~ residB*y"

lavaan2RAM(model5)

Run the code above in your browser using DataLab