umxModify: umxModify: Add, set, or drop model paths by label.
In tbates/umx: Structural Equation Modeling and Twin Modeling in R

umxModify

R Documentation

umxModify: Add, set, or drop model paths by label.

Description

umxModify allows you to modify, re-run and summarize an OpenMx::mxModel(), all in one line of script.

Usage

umxModify(
  lastFit,
  update = NULL,
  regex = FALSE,
  free = FALSE,
  value = 0,
  newlabels = NULL,
  freeToStart = NA,
  name = NULL,
  comparison = FALSE,
  autoRun = getOption("umx_auto_run"),
  tryHard = c("no", "yes", "ordinal", "search"),
  master = NULL,
  intervals = FALSE,
  verbose = FALSE
)

Arguments

`lastFit`	The `OpenMx::mxModel()` you wish to update and run.
`update`	What to update before re-running. Can be a list of labels, a regular expression (set regex = TRUE) or an object such as mxCI etc.
`regex`	Whether or not update is a regular expression (default FALSE). If you provide a string, it overrides the contents of update, and sets regex to TRUE.
`free`	The state to set "free" to for the parameters whose labels you specify (defaults to free = FALSE, i.e., fixed)
`value`	The value to set the parameters whose labels you specify too (defaults to 0)
`newlabels`	If not NULL, used as a replacement set of labels (can be regular expression). value and free are ignored!
`freeToStart`	Whether to update parameters based on their current free-state. free = c(TRUE, FALSE, NA), (defaults to NA - i.e, not checked)
`name`	The name for the new model
`comparison`	Whether to run umxCompare() on the new and old models.
`autoRun`	Whether to run the model (default), or just to create it and return without running.
`tryHard`	Default ('no') uses normal mxRun. "yes" uses mxTryHard. Other options: "ordinal", "search"
`master`	If you set master, then the update labels will be equated to these (i.e. replaced by them).
`intervals`	Whether to run confidence intervals (see `OpenMx::mxRun()`)
`verbose`	How much feedback to give

Details

You can add paths, or other model elements, set path values (default is 0), or replace labels. As an example, this one-liner drops a path labelled "Cs", and returns the updated model:

fit2 = umxModify(fit1, update = "Cs", name = "newModelName", comparison = TRUE)

Regular expressions are a powerful feature: they let you drop collections of paths by matching patterns for instance, this would match labels containing either "Cs" or "Cr":

fit2 = umxModify(fit1, regex = "C\[sr\]", name = "drop_Cs_and_Cr", comparison = TRUE)

You may find it easier to be more explicit. Like this:

fit2 = umxSetParameters(fit1, labels = c("Cs", "Cr"), values = 0, free = FALSE, name = "newName")
fit2 = mxRun(fit2)
summary(fit2)

Note: A (minor) limitation is that you cannot simultaneously set value to 0 AND relabel cells (because the default value is 0, so it is ignored when using newlabels).

Value

OpenMx::mxModel()

References

https://github.com/tbates/umx

Examples

## Not run: 
require(umx)
# First we'll just build a 1-factor model
umx_set_optimizer("SLSQP")
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)
)

# 1. Drop the path to x1 (also updating the name so it's
#    self-explanatory, and get a fit comparison
m2 = umxModify(m1, update = "G_to_x1", name = "drop_X1", comparison = TRUE)

# 2. Add the path back (setting free = TRUE)
m2 = umxModify(m1, update = "G_to_x1", free= TRUE, name = "addback_X1", comparison = TRUE)
# 3. Fix a value at a non-zero value
m3 = umxModify(m1, update = "G_to_x1", value = .35, name = "fix_G_x1_at_35", comp = TRUE)
# You can add objects to models. For instance this would add a path (overwriting the existing one)
# (thanks Johannes!)
m3 = umxModify(m1, umxPath("G", with = "x1"), name= "addedPath")

# Use regular expression to drop multiple paths: e.g. G to x3, x4, x5
m3 = umxModify(m1, regex = "^G_to_x[3-5]", name = "tried_hard", comp = TRUE, tryHard="yes")

# Same, but don't autoRun
m2 = umxModify(m1, regex  = "^G_to_x[3-5]", name = "no_G_to_x3_5", autoRun = FALSE) 

# Re-write a label
newLabel = "A_rose_by_any_other_name"
newModelName = "model_doth_smell_as_sweet"
m2 = umxModify(m1, update = "G_to_x1", newlabels= newLabel, name = newModelName, comparison = TRUE)
# Change labels in 2 places
labsToUpdate = c("G_to_x1", "G_to_x2")
newLabel = "G_to_1_or_2"
m2 = umxModify(m1, update = labsToUpdate, newlabels= newLabel, name = "equated", comparison = TRUE)

# Advanced!
# Regular expressions let you use pieces of the old names in creating new ones!
searchString = "G_to_x([0-9])"
newLabel = "loading_for_path\\1" # use value in regex group 1
m2 = umxModify(m1, regex = searchString, newlabels= newLabel, name = "grep", comparison = TRUE)

## End(Not run) # end dontrun

tbates/umx documentation built on Dec. 14, 2024, 11:28 a.m.