umx (version 1.4.0)

umxPath: umxPath: Flexible specification of sem paths

Description

The goal of this function is to enable quck-to-write, quick-to-read, flexible path descriptions for RAM models in OpenMx.

It introduces 11 new words to our vocabulary for describing paths: with, var, cov, unique.bivariate, Cholesky, means, v1m0, v.m., fixedAt, freeAt, firstAt.

The new preposition “with” means you no-longer need set arrows = 2 on covariances. Instead, you can say:

umxPath(A, with = B) instead of mxPath(from = A, to = B, arrows = 2).

Specify a variance for A with

umxPath(var = "A").

This is equivalent to mxPath(from = "A", to = "A", arrows = 2).

Of course you can use vectors anywhere:

umxPath(var = c('N','E', 'O'))

To specify a mean, you just say

umxPath(mean = "A"), which is equivalent to mxPath(from = "one", to = "A").

To fix a path at a value, instead of to mxPath(from = A, to = A, arrows = 2, free = FALSE, values = 1) you can say:

umxPath(var = "A", fixedAt = 1) .

The common task of creating a variable with variance fixed at 1 and mean at 0 is done thus:

umxPath(v1m0 = "A")

For free variance and means use:

umxPath(v.m. = "A")

umxPath exposes “unique.bivariate” so you don't have to remember how to fill in connect = in mxPath (you can still use connect if you wish).

So, to create paths A<->B, B<->C, and A<->C, you would say:

umxPath(unique.bivariate = c('A',"B","C"))

Setting up a latent trait, you can fix the loading of the first path with

mxPath(A, to = c(B,C,D), fixFirst = TRUE)

This is equivalent to mxPath(from = A, to = c(B,C,D), free = c(F, T, T), values = c(1, .5, .4)).

A new feature is the ability to create Cholesky-pattern connections:

umxPath(Cholesky = c("A1", "A2"), to c("var1", "var2"))

Finally, a feature, not implemented in this release, but intended for the future is John Fox "sem"-package style notation,

i.e., "A -> B; X <-> B; "

Usage

umxPath(from = NULL, to = NULL, with = NULL, var = NULL, cov = NULL, unique.bivariate = NULL, unique.pairs = NULL, forms = NULL, Cholesky = NULL, means = NULL, v1m0 = NULL, v.m. = NULL, v0m0 = NULL, fixedAt = NULL, freeAt = NULL, firstAt = NULL, connect = c("single", "all.pairs", "all.bivariate", "unique.pairs", "unique.bivariate"), defn = NULL, arrows = 1, free = TRUE, values = NA, labels = NA, lbound = NA, ubound = NA, hasMeans = NULL)

Arguments

from

either a source variable e.g "A" or c("A","B"), OR a sem-style path description, e.g. "A-> B" or "C <> B"

to

one or more target variables for one-headed paths, e.g "A" or c("A","B")

with

same as "to = vars, arrows = 2". nb: from, to= and var= must be left empty (their default)

var

equivalent to setting "from = vars, arrows = 2". nb: from, to, and with must be left empty (their default)

cov

equivalent to setting "from = X, to = Y, arrows = 2". nb: from, to, and with must be left empty (their default)

unique.bivariate

equivalent to setting "connect = "unique.bivariate", arrows = 2". nb: from, to, and with must be left empty (their default)

unique.pairs

equivalent to setting "connect = "unique.pairs", arrows = 2" (don't use from, to, or with)

forms

Paired with from, this will build a formative variable. from vars form the latent. Latent variance is fixed at 0. Loading of path 1 is fixed at 1. unique.bivariate among froms.

Cholesky

Treat Cholesky vars as latent and to as measured, and connect as in an ACE model.

means

equivalent to "from = 'one', to = x. nb: from, to, with and var must be left empty (their default).

v1m0

variance of 1 and mean of zero in one call.

v.m.

variance and mean, both free.

v0m0

variance and mean, both fixed at zero.

fixedAt

Equivalent to setting "free = FALSE, values = x" nb: free and values must be left empty (their default)

freeAt

Equivalent to setting "free = TRUE, values = x" nb: free and values must be left empty (their default)

firstAt

first value is fixed at this (values passed to free are ignored: warning if not a single TRUE)

connect

as in mxPath - nb: Only used when using from and to

defn

latent variable, var@0 mean fixed, with label-based as data source

arrows

as in mxPath - nb: Only used when using from and to

free

whether the value is free to be optimised

values

default value list

labels

labels for each path

lbound

lower bounds for each path value

ubound

upper bounds for each path value

hasMeans

Used in 'forms' case to know whether the data have means or not.

Value

- 1 or more mxPaths

Details

This function returns a standard mxPath, but gives new options for specifying the path. In addition to the normal “from” and “to”, it adds specialised parameters for variances (var), two headed paths (with) and means (mean). There are also new terms to describe fixing values: “fixedAt” and “fixFirst”.

Finally, (in future) it will allow sem-style “A->B” string specification.

References

- http://tbates.github.io

See Also

- mxPath

Other Model Building Functions: umxDiagnose, umxLabel, umxLatent, umxMatrix, umxModify, umxRAM2Ordinal, umxRAM, umxRun, umxThresholdMatrix, umxValues, umx_fix_first_loadings, umx_fix_latents, umx

Examples

require(umx)
# Some examples of paths with umxPath
umxPath("A", to = "B") # One-headed path from A to B
umxPath("A", to = "B", fixedAt = 1) # same, with value fixed @1
umxPath("A", to = c("B", "C"), fixedAt = 1:2) # same, with more than 1 value
umxPath("A", to = LETTERS[2:4], firstAt = 1) # Fix only the first path, others free
umxPath(var = "A") # Give a variance to A
umxPath(var = "A", fixedAt = 1) # Give a variance, fixed at 1
umxPath(var = LETTERS[1:5], fixedAt = 1)
umxPath(means = c("A","B")) # Create a means model for A: from = "one", to = "A"
umxPath(v1m0 = "A") # Give "A" variance and a mean, fixed at 1 and 0 respectively
umxPath(v.m. = "A") # Give "A" variance and a mean, leaving both free.
umxPath("A", with = "B") # using with: same as "to = B, arrows = 2"
umxPath("A", with = "B", fixedAt = .5) # 2-head path fixed at .5
umxPath("A", with = c("B", "C"), firstAt = 1) # first covariance fixed at 1
umxPath(cov = c("A", "B"))  # Covariance A <-> B
umxPath(unique.bivariate = letters[1:4]) # bivariate paths a<->b, a<->c, a<->d, b<->c etc.
umxPath(unique.pairs = letters[1:4]) # bivariate paths a<->b, a<->c, a<->d, b<->c etc.
umxPath(Cholesky = c("A1","A2"), to = c("m1", "m2")) # Cholesky
# A worked example
data(demoOneFactor)
latents  = c("G")
manifests = names(demoOneFactor)
myData = mxData(cov(demoOneFactor), type = "cov", numObs = 500)
m1 <- umxRAM("One Factor", data = myData,
	umxPath(latents, to = manifests),
	umxPath(var = manifests),
	umxPath(var = latents, fixedAt = 1.0)
)
umxSummary(m1, show = "std")

# ====================
# = Cholesky example =
# ====================
latents   = paste0("A", 1:3)
manifests = names(demoOneFactor)
myData = mxData(cov(demoOneFactor), type = "cov", numObs = 500)
m1 <- umxRAM("Chol", data = myData,
	umxPath(Cholesky = latents, to = manifests),
	umxPath(var = manifests),
	umxPath(var = latents, fixedAt = 1.0)
)
umxSummary(m1, show = "std")

# The following NOT YET implemented!!
# umxPath("A <-> B") # same path as above using a string
# umxPath("A -> B") # one-headed arrow with string syntax
# umxPath("A <> B; A <-- B") # This is ok too
# umxPath("A -> B; B>C; C --> D") # two paths. white space and hyphens not needed
# # manifests is a reserved word, as is latents.
# # It allows the string syntax to use the manifestVars variable
# umxPath("A -> manifests")