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,
  v0m. = 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
)

Value

1 or more mxPath()s

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.
v0m.: variance fixed at 0, mean free.
fixedAt: Equivalent to setting "free = FALSE, values = fixedAt"
freeAt: Equivalent to setting "free = TRUE, values = freeAt"
firstAt: First path is fixed at this value (free is ignored: warning if other than 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.

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

Examples

Run this code


# ==========================================
# = 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 var = 1 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

if (FALSE) {
# 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. for a RAM model                       =
# = def vars are instantiated as dummy latents with data on the "mean" = 
# ======================================================================
library(umx); libs("MASS") # for mvrnorm()
# 1. Create Data
N = 500 # size of each group
Sigma  = matrix(c(1,.5,.5,1),2,2) # cov (.5)
group1 = MASS::mvrnorm(N, c(1,2), Sigma)
group2 = MASS::mvrnorm(N, c(0,0), Sigma)
# rbind groups and name cols "x" and "y"
xy = rbind(group1, group2)
dimnames(xy)[2]= list(c("x", "y"))

# Create a definition variable for group status
groupID = rep(c(1,0), each = N) 
df = data.frame(xy, groupID = groupID)

# Make the model with a definition variable on means
m1 = umxRAM("Def Means", data = df,
	umxPath(v.m. = c("x","y")),
	umxPath("x", with = "y"),
 # create a unit latent called "def_groupID" with data "data.groupID"
	umxPath(defn = "groupID"),
 # Add it to the x and y means
	umxPath("def_groupID", to = c("x", "y"))
)
plot(m1)

}

Run the code above in your browser using DataLab