umx: xmuLabel – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

xmuLabel

xmuLabel: Add labels to a RAM model, matrix, or path

Description

xmuLabel adds labels to things, be it an: mxModel() (RAM or matrix based), an mxPath(), or an mxMatrix() This is a core function in umx: Adding labels to paths opens the door to umxEquate(), as well as omxSetParameters()

Usage

xmuLabel(
  obj,
  suffix = "",
  baseName = NA,
  setfree = FALSE,
  drop = 0,
  labelFixedCells = TRUE,
  jiggle = NA,
  boundDiag = NA,
  verbose = FALSE,
  overRideExisting = FALSE,
  name = NULL
)

Arguments

`obj`	An `mxModel()` (RAM or matrix based), `mxPath()`, or `mxMatrix()`
`suffix`	String to append to each label (might be used to distinguish, say male and female submodels in a model)
`baseName`	String to prepend to labels. Defaults to NA ("")
`setfree`	Whether to label only the free paths (defaults to FALSE)
`drop`	The value to fix "drop" paths to (defaults to 0)
`labelFixedCells`	= TRUE
`jiggle`	How much to jiggle values in a matrix or list of path values
`boundDiag`	Whether to bound the diagonal of a matrix
`verbose`	How much feedback to give the user (default = FALSE)
`overRideExisting`	= FALSE
`name`	Optional new name if given a model. Default (NULL) does not rename model.

Value

mxModel()

References

https://github.com/tbates/umx

Examples

# ==============================================================
# = Show how OpenMx models are not labeled, and then add labels =
# ==============================================================
require(umx)
data(demoOneFactor)
latents  = c("G")
manifests = names(demoOneFactor)
m1 = mxModel("One Factor", type = "RAM", 
	manifestVars = manifests, latentVars = latents, 
	mxPath(from = latents  , to = manifests),
	mxPath(from = manifests, arrows = 2),
	mxPath(from = latents  , arrows = 2, free = FALSE, values = 1.0),
	mxData(cov(demoOneFactor), type = "cov", numObs=500)
)

umxGetParameters(m1) # Default "matrix address" labels, i.e "One Factor.S[2,2]"
m1 = xmuLabel(m1)
umxGetParameters(m1, free = TRUE) # Informative labels: "G_to_x1", "x4_with_x4", etc.

# =======================================================================
# = Create a new model, with suffixes added to paths, and model renamed =
# =======================================================================
m2 = xmuLabel(m1, suffix= "_male", overRideExisting= TRUE, name = "male")
umxGetParameters(m2, free = TRUE) # suffixes added

# =============================
# = Example Labeling a matrix =
# =============================
a = xmuLabel(mxMatrix(name = "a", "Full", 3, 3, values = 1:9))
a$labels
a = xmuLabel(mxMatrix(name = "a", "Full", 3, 3, values = 1:9), baseName="bob")
a$labels
# note: labels with "data." in the name are left untouched!
a = mxMatrix(name = "a", "Full", 1,3, labels = c("data.a", "test", NA))
a$labels
xmuLabel(a, verbose = TRUE)
xmuLabel(a, verbose = TRUE, overRideExisting = FALSE)
xmuLabel(a, verbose = TRUE, overRideExisting = TRUE)

umx

Structural Equation Modeling and Twin Modeling in R

v4.10.10

GPL-3

Authors

Timothy C. Bates [aut, cre] (<https://orcid.org/0000-0002-1153-9007>), Gillespie Nathan [wit], Michael Zakharin [wit], Brenton Wiernik [ctb], Joshua N. Pritikin [ctb], Michael C. Neale [ctb], Hermine Maes [ctb]

Initial release

2021-11-30