Structural Equation and Twin Modeling in R

Quickly create, run, and report structural equation and twin models. See '?umx' for help, and"NEWS", package="umx")) for NEWS.

umx is a structural equation modelling package designed to make SEM easier to build, modify, and report.

It includes high-level functions for complex models such as multi-group twin models, as well as for graphical model output.

Grab it from CRAN with


The best way to learn what is on offer is to use the help ('?umx' works) and the online tutorial:

umx stands for "user" OpenMx functions. umx contains over 100 functions which build on OpenMx, and are designed to automate activities such as labelling, setting start values etc., and also provides umxRAM and umxPath functions that make Structural Equation Modeling in R straightforward.

Some highlights include:

  1. Building Path Models
    • umxRAM() # mxModel with an R-like data = parameter, no need to specify type = "RAM", + auto-discovery of manifests and latents from the paths you write
    • umxPath() # mxPath on steroids: one-word settings to set var , mean cov, fixedAt and more. Great time-saver!
  2. Reporting output
    • umxSummary(model) # Get a brief summary of model fit, similar to a journal report (Χ², p, CFI, TLI, & RMSEA). Optionally show the path loadings
    • plot(model, std=T, digits = 3, file = "name") # Create a graphical representation of model!
    • umx_time(model) # Report the time taken by a model in a compact programable format
  3. Modify models
    • umxModify() *# Modify and run a model. You can add objects, drop or add paths, including by regular-expression label matching), re-name the model, re-run, and even return the comparison. All in 1 line *
    • umxGetParameters(model, regex = "as_r_2c_[0-9]", free = T) # A powerful assistant to get labels from a model. like omxGetParameters but uses regular expressions.
  4. Twin models
    • umxACE() # 1-line function handling twin ACE modeling with aplomb paths are labeled, and works with plot() and umxSummary
    • umxIP(), umxGxE(), umxCP()
  5. Lower level helpers, data helpers, etc.
    • umxStart() # Add plausible start values to RAM or matrix models, or matrices: very helpful
    • umxLabel() # Add systematic labels to paths ("var1_to_var2") and matrix cells ("a_r1c1"). This is great for setting, equating and dropping paths by label!
    • umxHcor(data, use = "pairwise.complete.obs") # Compute appropriate pair-wise correlations for mixed data types.
  6. Helpers for easy-to-forget option names
    • umx_set_cores()
    • umx_set_optimizer()

Dozens more (?umx to see them all). Check out the "family links" in any help file also!

Feel free to use, and improve: Log suggestions using the Github comments. Tell your friends! Get awesome publications :-)

You can install the development version from github:



umx 1.4.8

  • December 2016 bug fix
  • FIXED: umx_make_TwinData fix bug in DZ moderator code and A+C computation
  • IMPROVED: more functionality hints in man page titles

umx 1.4.5

  • November 2016 "Usability is queen/Sincere Pumpkin Patch"
  • IMPROVED: Reorganize function families to increase clarity
  • IMPROVED: umx_set functions now show legal options by default
  • NEW: umx_set functions have silent option
  • FIX secure http URLs

umx 1.4.0

  • Mid October 2016 "New features and improvements"
  • BUG FIX: umxFitIndices RMR and SRMR (h/t Brenton Wiernik!)
  • NEW: umxMatrix with default labels and name as 1st parameter
  • NEW: Definition variable umxPath type, e.g.
    • umxPath(defn = "def", labels = "data.age")
  • IMPROVED: More concise feedback
  • IMPROVED: umxEquate supports autoRun and compare
  • IMPROVED: umx_names can, as a convenience, take string vectors
  • RENAME: umxGetOpenMx aliased to install.OpenMx or umx_install_OpenMx
  • IMPROVED: umxFitIndices new indices + computes refModels automatically
  • IMPROVED: umxRAM remove_unused_manifests no longer updates manifestVars + leaves variable in data by default.
  • RENAME: plot() "showFixed" deprecated in favour of easier to type "fixed"

umx 1.3.0

  • R 3.3.1 companion: "Bug in your Hair" August 2016
  • NEW: umxPath allows unique.pairs connection
  • Useful for growth curve models
  • IMPROVED: umxRAM handles suffix labels
  • Useful for models embedded in multi-group
  • IMPROVED: umxSummary to show parameters from first model in multi-group
  • Begin to support multi-group in umxSummary
  • IMPROVED: twin model figures tweaked
  • CHANGE showStd= to std= in most remaining cases
  • Might need to update your code!
  • CHANGE: umx_show_options to umx_get_options
  • Might need to update your code!
  • FIX: umx_check_parallel typo
  • FIX: plot calls from summary
  • REMOVE: dependency on non-condensed slots

umx 1.2.8

  • R 3.3.0 companion: "Very compatible" May 2016
  • NEW: umxRAM can now build and run Joint Continuous Ordinal models. Tada!!
  • NEW: umx_show_options function to help users learn the options available
  • BETA: umxACE can now implement a form of left-censoring. Tada!!
  • BETA: umxThresholdMatrix can now implement a form of left-censoring.
  • IMPROVE: umxRAM & umxRAM2Ordinal can turn off refModel computation with refModels = F;
  • IMPROVE: umx_show can show thresholds
  • IMPROVED: listOK option for umx_is_MxModel
  • IMPROVED: rowwiseParallel and numberSubjects options for umx_check_parallel
  • CHANGE: I changed "suffix" to "sep" in several places for consistency: this will break some low level code: nearly all of it mine, and fixed. But might affect some users!!
  • UPDATE: umx_time and umx_check_parallel to work with new S4 list deprecation
  • UPDATE: shorter run-time on 2sls code

umx 1.2.7

  • May 2016 stable release
  • ADDED: umxTwoStage FIML-based Instrumental variable and Mendelian Randomization (beta)
  • ADDED: umx_make_MR_data to simulate SNP-based Mendelian randomization data (beta)
  • ADDED: umx_set_condensed_slots(TRUE|FALSE): Get and set matrix compression
  • ADDED: umx_get_OpenMx() (download OpenMP/parallel version of OpenMx with NPSOL)
  • ADDED: umx_cont_2_quantile(x, nlevels=)
  • ADDED: umx_factor alias to umxFactor
  • FIXED: plot(resid = "none") was not suppressing plotting residuals
  • IMPROVED: umxFactor now handles dataframes and allows non-ordered output
  • IMPROVED: umx_CI() more flexible, now allows removing CIs
    • Old code will break: replace "add" with "which"
  • IMPROVED: umx_time handling of no input arguments
  • IMPROVED: umx_pb_note() better feedback and setup
  • IMPROVED: loadings() generic
  • CHANGE: umxModify - if free is a string, it will be used as input and the found paths will be freed.
  • CHANGE: umxModify - show summary as well as comparison if comparison is TRUE
  • CHANGE: Plot defaults for std and showFixed changed h/t @MikeNeale
  • CHANGE: umx_scale_wide_twin_data argument names for consistency: "suffix" "data"
  • CHANGE: umx_residualize() ditto

umx 1.2.5

  • April 2016 bug fix release
  • FIX: $models bug in umxStandardizeACE
  • EXPAND: test suite

umx 1.2.0

  • April 2016 R 3.2.4 Very Secure Dishes edition
  • NEW: Plot using DiagrammeR!
  • NEW: Choose plot format!
  • umx_set_plot_format("DiagrammeR")
  • umx_set_plot_format("graphviz")
  • NEW: Choose table format!
  • umx_set_table_format("markdown")
  • umx_set_table_format("latex")
  • NEW: set plotting by default: umx_set_auto_plot(TRUE)
  • NEW: Exploratory factor analysis! with umxEFA() (beta!)
  • NEW loadings() support for umxEFA
  • CHANGE: .dot --> .gv suffix for plotting (more compatible)
  • CHANGE: To $ from @ accessors for OpenMx compression compatibility
  • BETTER: Help! ACECov figure, ... many other improvements
  • ENHANCED: umx_print, umx_show, umxCompare
  • REQUIRE knitr, DiagrammeR
  • INCREASE minimum R / OpenMx to >= 3.2.0 / >= 2.5.0

umx 1.1.5

  • March 2016 Boulder Workshop feedback updates
  • NEW: plot() now works on Windows and Unix as well as OS X! (h/t @mhunter)
  • CHANGE: umxReRun to umxModify (h/t @hmaes)
  • BETTER: compatibility with OpenMx 2.5.2

umx 1.1.1

  • Feb 2016 R 3.2.3 Wooden Christmas Tree edition
  • NEW: auto-run now the default for all models!
    • Added option to switch this: options("umx_auto_run" = TRUE)
  • NEW: plot should generate pdfs for Windows and Unix users now
  • NEW: umxACEcov support for ACE with covariates
  • NEW: umx_make_TwinData added to support simulation studies
  • BETTER: umx_check_parallel now returns timing information
  • BETTER: umx_time now supports "start" and "stop")
  • BETTER: umxAPA can format more objects in APA style, inc just a p-value)
  • BETTER: summaryAPA can now summarise a data.frame with mean, sd, and correlations
  • BETTER: umxLabel now preserves existing labels in umxRAM models: labels = is now saved
  • BETTER: Help improvements (wording, seealso etc)
  • DEEP: Removed dependency on

umx 1.1.0

  • December 2015 update
  • NEW: vcov() added
  • NEW: Begin support for sex-lim twin models
  • NEW: New data file for sex-limitation
  • IMPROVED: umxRAM can take existing model as input (very useful)
  • IMPROVED: umxRAM reports model fit and comparison (if old model exists)
  • IMPROVED: umxPath now lbounds [email protected] for v.m.
  • IMPROVED: umx_residualize can now take multiple DVs
  • IMPROVED: umxMI enhanced to cope with more situations
  • IMPROVED: summary more resilient with missing CIs (#ht Nathan Gillespie!)
  • IMPROVED: summaryAPA now handles data as well as lm
  • IMPROVED: help for twin functions
  • Various new function features
  • IMPROVED: umx_print resilient to 0-row input
  • IMPROVED: summary helpers (e.g. umx_fun_mean_sd)
  • IMPROVED: consistency in parameter names (minor backward incompatibility)
  • DEEP: Replacing @ with $ accessor begun

umx 1.0.0

  • NEW CP twin models! (create, plot, summary)
  • NEW IP twin models! (create, plot, summary)
  • NEW GxE twin models! (create, plot, summary)
  • FIXED limitation in umxPath where "to" was not being set.
  • SUPPORT Circles as well as lines for residualvariance
  • IMPROVE Help text. Thanks Mike Neale esp.!
  • IMPROVE Organization of functions into @families in the help.
  • IMPROVE Rxample for umx_lower2full()
  • DROPPED umxRAM functionality to set endogenous, exogenous, and latent traits
  • DROPPED A dozen deprecated functions.

umx 0.50.0

  • First CRAN release

umx 0.49.0

  • IMPROVE Edge cases work
  • IMPROVE Improving help files and feedback
  • IMPROVE Rationalizing fn names into @families

umx 0.45-beta

  • Feature complete
  • Bug squashing
  • Optimizing fn names for memorability and typing

umx 0.40-beta

  • Beta level!
  • Standard confint(); plot() etc functions implemented
  • Adding umxRAM() and umxPath shortcuts

umx 0.30-alpha

  • Alpha release
  • 90% feature complete
  • lots of name rationalization

umx 0.25-alpha

  • Alpha release
  • 80% feature complete
  • Function prefix reflects usage:: umxMajor, umx_utility_function, xmuNotForUser

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


2.8.0 by Timothy C Bates, 2 months ago

Report a bug at

Browse source code at

Authors: Timothy C Bates [aut, cre] (<>)

Documentation:   PDF Manual  

Task views:

GPL-3 license

Imports cowplot, ggplot2, DiagrammeR, knitr, MASS, Matrix, mvtnorm, nlme, numDeriv, polycor, R2HTML, RCurl, sfsmisc, xtable, methods, utils

Depends on OpenMx

Suggests cocor, devtools, gdata, Hmisc, testthat, rmarkdown

See at CRAN