umxLav2RAM: Convert lavaan string to a umxRAM model

Description

Takes a lavaan syntax string and creates the matching one or more umxRAM() models.

If data are provided, a umxRAM() model is returned.

If more than one group is found, a umxSuperModel() is returned.

This function is at the alpha quality stage, and should be expected to have bugs. Several features are not yet supported. Let me know if you would like them.

Usage

umxLav2RAM(
  model = NA,
  data = "auto",
  group = NULL,
  group.equal = NULL,
  name = NA,
  lavaanMode = c("sem", "lavaan"),
  std.lv = FALSE,
  suffix = "",
  comparison = TRUE,
  type = c("Auto", "FIML", "cov", "cor", "WLS", "DWLS", "ULS"),
  allContinuousMethod = c("cumulants", "marginals"),
  autoRun = getOption("umx_auto_run"),
  tryHard = c("no", "yes", "ordinal", "search"),
  verbose = FALSE,
  optimizer = NULL,
  std = FALSE,
  printTab = TRUE
)

Value

list of umxPath()s

Arguments

model: A lavaan syntax string, e.g. "A~~B"
data: Data to add to model (defaults to auto, which is just sketch mode)
group: = Column to use for multi-group (default = NULL)
group.equal: = what to equate across groups. Default (NULL) means no equates. See details for what we might implement in future.
name: Model name (can also add name in # commented first line)
lavaanMode: Auto-magical path settings for cfa/sem (default) or no-defaults ("lavaan")
std.lv: = FALSE Whether to set var of latents to 1 (default FALSE). nb. Toggles fix first.
suffix: String to append to each label (useful if model will be used in a multi-group model)
comparison: Compare the new model to the old (if updating an existing model: default = TRUE)
type: One of "Auto", "FIML", "cov", "cor", "WLS", "DWLS", "ULS"
allContinuousMethod: "cumulants" or "marginals". Used in all-continuous WLS data to determine if a means model needed.
autoRun: Whether to run the model (default), or just to create it and return without running.
tryHard: Default ('no') uses normal mxRun. "yes" uses mxTryHard. Other options: "ordinal", "search"
verbose: Whether to tell the user what latents and manifests were created etc. (Default = FALSE)
optimizer: optionally set the optimizer (default NULL does nothing)
std: Whether to print estimates. Defaults to FALSE ("raw"), TRUE = "std", for no parameter table use NULL.
printTab: = TRUE (more for debugging)

Details

Uses the defaults of lavaan::sem

int.ov.free = TRUE
int.lv.free = FALSE
auto.fix.first = TRUE (unless std.lv = TRUE)
auto.fix.single = TRUE
auto.var = TRUE
auto.cov.lv.x = TRUE
auto.th = TRUE
auto.delta = TRUE
auto.cov.y = TRUE
fixed.x = FALSE (not standard in lavaan::sem, but needed for RAM)

Lavaan is well documented. For quick reference, some common symbols in lavaan strings are:

lav	Mplus	sem	Action
A =~ B	A by B		A (Latent) is measured by B
A ~ B	A on B	A<- B	A "is regressed on" (<- ) B
A ~~ B	A with B	A<->B	A covaries with B
A ~ 1	[A]		A has mean
A := B			A is defined by B (see `OpenMx::mxAlgebra()`)
A == B			A is constrained == to B (see `OpenMx::mxConstraint()` )

	`=~`	lhs (Latent) is manifested by rhs
`~`	lhs "is regressed on" (<- ) rhs		`~~`
lhs covaries with rhs		`~ 1`	lhs has mean
	`:=`	lhs is defined by rhs (see `OpenMx::mxAlgebra()`)

Naming of multiple groups

When multiple groups are found the groups are named name_grouplevel White space is replaced with "_" and illegal characters are replaced with "x"

note: Options for group.equal. In future, we might implement (but have not as yet):

c("loadings"
"intercepts"
"means"
"regressions"
"residuals"
"covariances"

Examples

Run this code

if (FALSE) {

# auto-data, print table, return umxRAM model
m1 = umxLav2RAM("y ~ x", printTab= TRUE)

lav = "y ~ x1 + 2.4*x2 + x3"
tmp = umxLav2RAM(lav, data = "auto", printTab= FALSE)

# Add labels to parameters, e.g. "x3_loading" as a loading for x3->x1
tmp = umxLav2RAM("x1 ~ x3_loading*x3")
umx_print(tmp$A$labels)
# |   |x1       |x3         |
# |:--|:--------|:----------|
# |x1 |x1_to_x1 |x3_loading |
# |x3 |x1_to_x3 |x3_to_x3   |

# Fix values, e.g. x2 -> y fixed at 2.4
tmp = umxLav2RAM("y ~ x1 + 2.4*x2; s =~ 0*y11 + 1*y12 + 2*y13 + 3*y14")

tmp = umxLav2RAM("L =~ X1 + X2; L ~ Y")
plot(tmp, min=c("L", "Y"))

# Factor model showing auto-addition of correlations among exogenous latents
# and auto-residuals on manifests
data("HS.ability.data", package = "OpenMx")

cov(HS.ability.data[, c("visual"  , "cubes"   , "flags")])
cov(HS.ability.data[, c("paragrap", "sentence", "wordm")])
cov(HS.ability.data[, c("addition", "counting", "straight")])

HS = "spatial =~ visual   + cubes    + flags
      verbal  =~ paragrap + sentence + wordm
      speed   =~ addition + counting + straight"

m1 = umxRAM(HS, data = umx_scale(HS.ability.data))

# Multiple groups
m1 = umxRAM(HS, data = umx_scale(HS.ability.data), group = "school")

# More examples

lav = " # Moderated mediation
gnt ~ a*cb
INT ~ b1*gnt + b2*cn + b3*cngn + c*cb

indirect := a*b1
direct := c

ab3 := a * b3
loCN := a * b1 + ab3 * -0.5
hiCN := a * b1 + ab3 * 0.5
"
tmp = umxRAM(lav)
# plot showing ability to influence layout with max min same groupings
plot(tmp, max = c("cb", "cn", "cngn"), same = "gnt", min= "INT")

# Algebra: e.g. b1^2
m1 = umxRAM("x1~b1*x2; B1_sq := b1^2", data = demoOneFactor)
m1$B1_sq$result # = 0.47

# Model with constraints and labeled parameters
lav = "
y ~ b1*x1 + b2*x2 + b3*x3
# constraints
b1 == (b2 + b3)^2
b1 > exp(b2 + b3)"

tmp = umxLav2RAM(lav)

namedModel = " 	# my name
	y ~x"
m1 = umxRAM(namedModel) 

# Formative factor
# lavaanify("f5 <~ z1 + z2 + z3 + z4")
}