umx (version 4.9.0)

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

Description

This function is used to easily and compactly specify paths in models. In addition to 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. To give a couple of the most common, time-saving examples:

• umxPath("A", with = "B", fixedAt = 1)

• umxPath(var = c("A", "B"), fixedAt = 1)

• umxPath(v.m. = manifests)

• umxPath(v1m0 = latents)

• umxPath(v1m0 = latents)

• umxPath(means = manifests)

• umxPath(fromEach = c('A',"B","C"), to = c("y1","y2"))

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

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

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

umxPath introduces the following new words to your path-defining vocabulary: with, var, cov, means, v1m0, v0m0, v.m0, v.m, fixedAt, freeAt, firstAt, unique.bivariate, unique.pairs, fromEach, Cholesky, defn, forms.

with creates covariances (2-headed paths): umxPath(A, with = B)

Specify a variance for A with umxPath(var = "A").

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)

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 to create paths 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"))

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

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

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

To create Cholesky-pattern connections:

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

References

• https://tbates.github.io

See Also

• mxPath()

Other Core Model Building Functions: umxMatrix(), umxModify(), umxRAM(), 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 {
# }