umxRAM_DE: Build and run path-based Double-entry SEM models including...

In umx: Structural Equation Modeling and Twin Modeling in R

Build and run path-based Double-entry SEM models including censored data

Description

umxRAM_DE expedites SEM with censored data. Each name in DEvars is a latent trait. Prepared ⁠_cont⁠ / ⁠_cens⁠ columns are indicators of that latent (loading fixed at 1, residual fixed at 0). Write ordinary umxPath() calls using the base name (e.g. "litres"). Do not Cartesian-expand to ⁠_cont⁠/⁠_cens⁠.

Fully continuous variables may be mixed with double-entry pairs. Prepare the censored traits with umx_make_double_entry_data(). At least one DEvar is required.

As you can see from the examples below, most of the work is done by umxPath(). umxRAM_DE wraps these paths up, takes the ⁠data =⁠ input, and then builds the latent measurement model for each DE trait and sets thresholds. By default it will also run it.

Gotchas A common error is to include data in the main list, a bit like saying lm(y ~ x + df) instead of lm(y ~ x, data = df).

nb: Because it uses the presence of a variable in the data to detect if a variable is latent or not, umxRAM needs data at build time.

If you are used to hacking a quick model with lavaan string syntax, use umxRAM() at present. Likewise, if you are at the "sketching" stage of theory consideration, umxRAM supports that, umxRAM_DE does not.

Usage

umxRAM_DE(
  model = NA,
  ...,
  data = NULL,
  DEvars = NULL,
  doubleEntrySuffix = c("_cont", "_cens"),
  fixCensorThresholds = c("yes", "auto", "no"),
  censorCuts = NULL,
  sep = NULL,
  name = NA,
  group = NULL,
  group.equal = NULL,
  suffix = "",
  comparison = TRUE,
  type = c("Auto", "FIML"),
  weight = NULL,
  allContinuousMethod = c("cumulants", "marginals"),
  autoRun = getOption("umx_auto_run"),
  tryHard = c("no", "yes", "ordinal", "search"),
  std = FALSE,
  refModels = NULL,
  remove_unused_manifests = TRUE,
  independent = NA,
  setValues = TRUE,
  optimizer = NULL,
  verbose = FALSE
)

Arguments

model	A model to update (or set to string to use as name for new model)
...	umxPaths, mxThreshold objects, etc.
data	data for the model. Can be an OpenMx::mxData() or a data.frame
DEvars	A character vector of base names for double-entry variables (e.g. c("litres") creates litres_cont/litres_cens). Base names only; do not include suffix.
doubleEntrySuffix	Suffixes for the continuous and censored variables (default = c("_cont", "_cens")).
fixCensorThresholds	One of c("yes","auto","no"). "yes" fix every DE pair from censorCuts/prep attr; "auto" fix only pairs with finite known cut; "no" free thresholds.
censorCuts	Optional named numeric vector of known cuts on analysis scale. Names may be base ("litres"), "_cont" or "_cens" form.
sep	Separator used in prep (default NULL infers from attr(data,"umxDoubleEntry")$sep or "").
name	A friendly name for the model.
group	(optional) Column name to use for a multi-group model (default = NULL). Fixed DE thresholds (known cut) are applied in every group.
group.equal	In multi-group models, what to equate across groups (default = NULL: all free)
suffix	String to append to each label (useful if model will be used in a multi-group model)
comparison	Compare the new model to the old (if updating an existing model: default = TRUE)
type	One of "Auto" or "FIML". note: other types, e.g., "WLS" are rejected (use umxRAM()).
weight	Passes weight values to mxData
allContinuousMethod	"cumulants" or "marginals". Used in all-continuous WLS data to determine if a means model needed.
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"
std	Whether to show standardized estimates, raw (NULL print fit only)
refModels	pass in reference models if available. Use FALSE to suppress computing these if not provided.
remove_unused_manifests	Whether to remove variables in the data to which no path makes reference (defaults to TRUE)
independent	Whether the model is independent (default = NA)
setValues	Whether to generate likely good start values (Defaults to TRUE)
optimizer	optionally set the optimizer (default NULL does nothing)
verbose	Whether to tell the user what latents and manifests were created etc. (Default = FALSE)

Details

WLS / cov / cor type = "WLS", "DWLS", "ULS", "cov", or "cor" is not valid in umxRAM_DE. Double-entry needs raw-data FIML (each row is either the continuous density or the threshold CDF). Those types fit a correlation/moment structure and cannot use the mutual-NA ⁠_cont⁠/⁠_cens⁠ pattern. For WLS/cov/cor on ordinary (non-DE) data, use umxRAM().

Value

• OpenMx::mxModel()

References

https://tbates.github.io, https://github.com/tbates/umx

See Also

umxPath(), umxSummary(), plot(), parameters(), umxSuperModel(), umxLav2RAM()

Other Core Model Building Functions: umx, umxLISREL(), umxMatrix(), umxModify(), umxPath(), umxRAM(), umxSuperModel()

Examples

# Here's a path example that models miles per gallon (mpg) as a function of weight (wt) and 
# engine displacement (disp) using the widely used `mtcars` data set.

# 1: Create the censored data
# Just for a demo, we will create a censored litres column, censoring at 2.
data(mtcars)
tmp = mtcars
tmp$litres = tmp$disp / 61.02
tmp = umx_make_double_entry_data(tmp, cols = list(litres= 2), sep="", nSib=1)
# 2: Create the RAM_DE model
m1 = umxRAM_DE("test", data = tmp, DEvars = c("litres"),
	umxPath("litres", to = "mpg"),
	umxPath("wt", to = "mpg"),
	umxPath("wt", with = "litres"),
	umxPath(v.m. = c("litres", "wt", "mpg"))
)

umx documentation built on Oct. 11, 2026, 5:07 p.m.