OpenMxGUI:
A graphical user interface to OpenMx

Claude Monet, Le Barche Rosse Argenteuil

Introduction:

OpenMxGUI is open source R code for a windowing system that allows users to interact with OpenMx without writing and debugging code. The GUI was developed for large models expressed in matrix notation. It does not create path diagrams and may be inefficient for small models. There are two parts to the GUI:

  1. OpenMxpractical is for users who create their own MxModel and want to fit a set of nested models. It allows users to: change the fixed and free status of parameters; alter start values and fixed values; alter parameter labels; alter parameter bounds; run the model and assess the solution; rerun a model using the current estimates as starting values or with different starting values or jiggled starting values; and save the fitted MxModel object to a system file.
  2. OpenMxproject is for users with little knowledge of R. It creates an object of class OpenMxGUIproject that keeps track of different MxModels fitted to the same data objects. It assists the user in writing MxModels, editing these models to create new MxModels, editing parameter matrices, fitting models, assessing convergence, and saving models. Utility functions for an OpenMxGui project allow the user to read in data in several formats, open and view the saved models and compare models.

This is my first foray into programming in R. Hence, the code is definitely primitive. Also, I have yet to learn how to create an R package, so it is available only as source code. Currently only OpenMxGUIpractical is available for testing. I will release OMxGUIproject when: (1) the OpenMx team has finalized some issues, (2) I am finished writing some bells and whistles, and (3) I find the time to write the instructions.

Download

OpenMxGUIpractical

Download the package and unzip it into a directory. File with the .R extension are R source files, and files ObsCovMZ.RData, ObsCovMZ.RData, and testModel.RData are R objects for an example test file. ObsCovMZ and ObsCovDZ are observed covariance matrices from the National Merit Twin study, and testModel is an MxModel with a model to be fitted to these data.

Using a text editor, browse to the folder into which you downloaded and unzipped the files.

Edit file “omxGUIalphaTest.R”, and change the first line to reflect the path in your system to the directory (folder) containing the OpenMxGUI files. This file also contains a list of required R packages. You should make certain that these packages are installed on your system.

Thereafter, read omxGUIalphaTest.R into R as a source file. (In the R GUI select "File" on the menu bar, then "Source"). It will load the necessary packages, read in the source files with the necessary functions, and also place the R objects into the global environment.

To call OpenMxGUIpractical, enter the command

myFinalMxModel <- OpenMxGUIpractical(myMxModel)

or, if you have MxModel objects in the global environment and want to select from them,

myFinalMxModel <- OpenMxGUIpractical()

A window will appear from the VIM package. Just close it and continue.

OpenMxGUIpractical has two major functions, both of which can be called directly. The first, omxGUIeditMatrixValues, allows a user to edit values of the parameter matrices without running the model. Its call is

myEditedMxModel <- omxGUIeditMatrixValues(myMxModel)

where myMxModel is the name of the MxModel object to be edited and myEditedMxModel is the MxModel object returned after the edits.

The second major function, omxGUImxRun, will run an MxModel object without editing its parameter values. Its call is

myFinalMxModel <- omxGUImxRun(myMxModel)

where myMxModel is the MxModel object that will be fitted to data and myFinalMxModel is the same model with the output from fitting the model.

Notes:

  1. Windows users! Beware! The R GUI for Windows grabs the focus, hiding the OpenMxGUI windows. A user may mistakenly think that R has hung up. Just move or minimize the R GUI window.
  2. OpenMxGUI does not check for valid R names. If you enter a stupid name for an R object, you will get stupid results.
  3. Really annoying undocumented feature: Upon loading, the VIM package automatically displays a window called Visualization and Imputation of Missing Values. Just close the window and continue.
  4. OpenMxGUI does not yet support MxPath objects.
  5. Error: no function to return to, returning to top level. This comes from function tk2edit in package tcltk2 so don’t blame me. The error does not seem to matter.
  6. Warning: closing unclosed connection # (""). If you know how to suppress this warning, please let me know.
  7. OpenMxGUI active windows prevent entering R commands. Eventually, I would like to move the GUI into an interface with drop down menus that would allow a user to also enter commands into R while the main OpenMxGUI window is active. For now, when GUI windows are active, a user cannot use the main GUI window, and some messages and warnings from R and OpenMx may not immediately appear in the R window. To use R, exit OpenMxGUI and then restart it after you are finished entering commands in the R interface.
  8. OpenMxGUI will abort upon an OpenMx error. Suggestions on a fix are welcome.
  9. thisOMxModel. For safety, OpenMxGUI never changes a user's MxModel. Instead, it operates on an R objected called thisOMxModel in the global environment. When you process a model, the algorithm copies your model into thisOMxModel and when you save a model, thisOMxModel is copied into the the R object using the name that you specify. As a result, MAKE CERTAIN TO SAVE YOUR MODELS ONCE YOU ARE SATISFIED WITH THEIR FITS! Otherwise, subsequent edits and runs will change thisOMxModel and the model that fit the data will be destroyed.
  10. boundary conditions. The next major release of OpenMx will have the tools necessary for the GUI to deal with boundaries on parameters (see http://openmx.psyc.virginia.edu/thread/786), Until then, use and interpret boundaries at your own peril.