umx (version 4.0.0)

umxPath: Easier (and powerful) specification of paths in SEM.

Description

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

It introduces the following new words to our vocabulary for describing paths: with, var, cov, means, v1m0, v0m0, v.m0, v.m., fixedAt, freeAt, firstAt, unique.bivariate, unique.pairs, fromEach, Cholesky, defn, forms.

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, you can say:

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

instead of mxPath(from = A, to = A, arrows = 2, free = FALSE, values = 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” and “unique.pairs” 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 creates A<->A, B<->B, and A->B, you would say:

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

To create paths A<->B, B<->C, and A<->C, you would say: umxPath(unique.bivariate = c('A',"B","C"))

umxPath(fromEach = c('A',"B","C")) Creates one-headed arrows on the all.bivariate pattern

Setting up a latent trait, you can scale with a fixed first path thus:

umxPath("A", to = c("B","C","D"), firstAt = 1)

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

To create Cholesky-pattern connections:

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

Usage

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

Arguments

from

One or more source variables e.g "A" or c("A","B")

to

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

with

2-headed path <--> from 'from' to 'with'.

var

Equivalent to setting 'from' and 'arrows' = 2. nb: from, to, and with must be left empty.

cov

Convenience to allow 2 variables to covary (equivalent to 'from' and 'with'). nb: leave from, to, etc. empty

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.

v.m0

variance free, mean 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)

unique.bivariate

equivalent to setting from, and "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)

fromEach

Like all.bivariate, but with one head arrows. 'to' can be set.

forms

Build a formative variable. 'from' variables form the latent. Latent variance is fixed at 0. Loading of path 1 is fixed at 1. unique.bivariate between 'from' variables.

Cholesky

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

defn

Implements a definition variable as a latent with zero variance & mean and labeled 'data.defVar'

connect

as in mxPath - nb: from and to must also be set.

arrows

as in mxPath - nb: from and to must also be set.

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 mxPath()s

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

• https://tbates.github.io

See Also

• mxPath()

Other Core Modeling Functions: umxAlgebra(), umxMatrix(), umxModify(), umxRAM(), umxRun(), umxSummary(), umxSuperModel(), umx

Examples

# NOT RUN {
# ==========================================
# = Examples of each path type, and option =
# ==========================================

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 = c("B","C"), 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(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(v0m0 = "W", label = c(NA, "data.W"))
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(defn = "mpg") # create latent called def_mpg, with 0 mean * var, and label = "data.mpg"
umxPath(fromEach = c('a','b'), to = c('c','d')) # a->c, a<->d, b<->c, b<->d
umxPath(unique.bivariate = c('a','b','c')) # bivariate paths a<->b, a<->c, b<->c etc.
umxPath(unique.pairs = letters[1:3]) # all distinct pairs: a<->a, a<->b, a<->c, b<->b, etc.
umxPath(Cholesky = c("A1","A2"), to = c("m1", "m2")) # Cholesky

# }
# NOT RUN {
# A worked example
data(demoOneFactor)
manifests = names(demoOneFactor)
m1 = umxRAM("One Factor", data = demoOneFactor, type= "cov",
	umxPath("G", to = manifests),
	umxPath(var = manifests),
	umxPath(var = "G", fixedAt = 1.0)
)
umxSummary(m1, std = TRUE)
require(umx)
#

# ====================
# = Cholesky example =
# ====================
# ======================================================================
# = 3-factor Cholesky (A component of a 5-variable 3-factor ACE model) =
# ======================================================================
latents   = paste0("A", 1:3)
manifests = names(demoOneFactor)
m1 = umxRAM("Chol", data = demoOneFactor, type = "cov",
	umxPath(Cholesky = latents, to = manifests),
	umxPath(var = manifests),
	umxPath(var = latents, fixedAt = 1)
)
plot(m1, splines= FALSE)

# =========================================================
# = Definition variable example.Not much use at present,  =
# = as def vars are not readily used in RAM models...     =
# = Working on something rational and intuitive.          =
# =========================================================
data(mtcars)
m1 = umxRAM("manifest", data = mtcars,
 umxPath(v.m. = "mpg"),
 umxPath(defn = "mpg")
)

# }
# NOT RUN {
# }