OpenMx 2.19 released!

We are pleased to announce the official release of OpenMx version 2.19.1. Click here for instructions on how to install the package from our repository. As usual, our repository has package binaries for Windows and macOS, and source tarballs for Linux/GNU and other non-Mac Unix-likes, all of which come with the proprietary NPSOL optimizer. Alternately, users may install the fully open-source build of the new version from CRAN.

GREML

We are excited to report that, a few weeks prior to this new version release, our manuscript documenting OpenMx's GREML (Genomic-relatedness-matrix REstricted Maximum Likelihood) feature was published online (click here to read it)! Consequently, we wish to highlight several new "mxGREML"-related developments included in OpenMx 2.19:

  • Numerically differentiating the GREML fitfunction during optimization is extremely slow. Previously, users who wanted something faster than numerical differentiation could have the fitfunction pass the optimizer analytic derivatives. But to do so, the user needed to provide MxMatrices or MxAlgebras representing the first partial derivatives of the model-expected covariance matrix, with respect to all free parameters, from which the backend would calculate analytic fitfunction derivatives. That is, using the faster option required the user to know some matrix calculus (and not make any mistakes with it!), and also required extra memory to store those matrix derivatives. But now, "semi-analytic derivatives" of the fitfunction (as described in the paper) have been implemented. Specfically, by default the mxGREML backend numerically differentiates the model-expected covariance matrix with respect to each free parameter for which the user did not provide an analytic matrix derivative, and then calculates analytic fitfunction derivatives from those numeric matrix derivatives. While not quite as fast as fully analytic derivatives, semi-analytic derivatives are much faster than numeric derivatives, and require less RAM than fully analytic derivatives.
  • Previously, the mxGREML backend required users to provide analytic matrix derivatives with respect to all free parameters, or with respect to none. Now, users can provide analytic matrix derivatives with respect to some but not all free parameters. As described above, by default, the mxGREML backend will substitute semi-analytic fitfunction derivatives where needed.
  • It is now possible for the user to tell the GREML fitfunction to use the expected information matrix as an approximation to the Hessian, for use during Newton-Raphson optimization and for computing the sampling covariance matrix of the parameter estimates. Previously, the GREML fitfunction could only use the average information matrix as a Hessian approximation, and the average information matrix is generally a good Hessian approximation only when the model-expected covariance matrix is linear in the free parameters.
  • The GREML fitfunction backend is now smarter about how it load-balances among multiple threads the computation of the information matrix. Briefly summarized, it is now more accurate at gauging the running time of various calculations, and it is also now able to modify its load-balancing scheme appropriately for the current step in the MxModel's compute plan.
  • As described in the paper, mxAutoStart() is now compatible with the GREML expectation type.
  • Another new development concerns scenarios where the fitfunction can provide analytic derivatives to the optimizer. Now, by default (i.e., under the default behavior of the on-load default optimizer) in such a scenario, the optimizer will use those derivatives during calculation of confidence intervals. Although this new feature is not specific to mxGREML analyses, mxGREML was its motivating use-case.
  • There was a bug in the GREML fitfunction backend that could crash R if the number of threads in use was greater than the number of free parameters in the model. That bug has been repaired.

A repository of example scripts that demonstrate the mxGREML feature is available here.

Genome-Wide SEM

Although the package gwsem has been available on CRAN for some time already, the article documenting how to use it is finally out. If you didn't know already, most genome-wide association study (GWAS) analyses test the association between single-nucleotide polymorphisms (SNPs) and a single trait or outcome. While multivariate GWAS opens up a broad new landscape of feasible and informative analyses, its adoption has been slow. An OpenMx add-on, gwsem, overcomes the inherent computational challenges associated with multivariate GWAS. In the associated article, we conducted (1) a series of GWAS using three substance use frequency items from data in the UK Biobank, (2) a timing study for several predefined GWAS functions, and (3) a Type I Error rate study. Our multivariate GWAS analyses emphasize the utility of GW-SEM for identifying novel patterns of associations that vary considerably between genomic loci for specific substances, highlighting the importance of differentiating between substance-specific use behaviors and polysubstance use.

New Features and Performance Improvements Since v2.18:

  • All OpenMx optimizers now assume that zeros that appear in non-linear constraint Jacobians will remain zero throughout optimization. Previously, only NPSOL made this assumption. This optimization saves many fit evaluations when constraint Jacobians are mostly zero. However, in some cases it may now be necessary for users to ensure that equality constraints are violated at the start values (e.g., not starting binary indicator variance at exactly 1.0 when using an equality constraint to constrain the variance to 1.0). This is a backward incompatible change.
  • SLSQP is now capable of multithreaded evaluation of inequality constraints.
  • The OpenMx backend now has better heuristics for speeding up multithread performance when argument rowwiseParallel to mxFitFunctionML() is NA (which is now its default).
  • mxSE() is now faster, since the elements of its Jacobian matrix are now calculated in parallel.
  • mxPath() now accepts argument arrows=0, which forms a "co-path" representing Pearson-Aitken selection (see example here).
  • The WLS fitfunction is now faster for diagonally-weighted least-squares (DWLS) estimation, by avoiding unnecessary linear-algebra computations.

Bug-fixes and Tweaks Since v2.18:

  • At some point, a regression was introduced into the OpenMx codebase that prevented multithreaded processing during confidence-interval calculation. Multithreaded confidence-interval calculation is now restored. OpenMx is still limited to estimation of a single CI at a time, but multiple threads can be used within each CI problem.
  • Previously, due to a bug, OpenMx did not calculate standard errors for WLS models containing MxConstraints. OpenMx now calculates robust, constraint-corrected standard errors for such models.
  • SLSQP no longer ignores the value of mxOption "Feasibility tolerance" for non-linear constraints. That is, in prior releases, SLSQP would always prefer to eliminate constraint violations completely regardless of the loss in fit. Now SLSQP will correctly permit "Feasibility tolerance" worth of constraint violation in exchange for improved fit.
  • In prior releases, the addition or removal of a box constraint (upper or lower bound) could dramatically affect SLSQP's optimization trajectory leading to failed optimization attempts. Box constraints no longer affect SLSQP's search direction except for parameters very close to a boundary.
  • mxGenerateData() no longer fails with an unhelpful error if it is passed a model with definition variables but no data.
  • mxAutoStart() no longer fails with an error when given a model that has a custom compute plan containing an MxComputeConfidenceInterval step.
  • The RAM expectation type now exposes the unfiltered mean vector and unfiltered covariance matrix (i.e., the mean vector and covariance matrix for all variables in the model, both manifest and latent) for use in MxAlgebras or MxConstraints.
  • CSOLNP no longer gets stuck in an infinite loop when printing verbose output to the R console.
  • OpenMx now gives a more-helpful error message when the user attempts to run a model with an ordinal covariance block with dimension exceeding the current value of mxOption "maxOrdinalPerBlock".

Known Issues:

  • The MxModel class's runstate slot unnecessarily stores the pre-run states of MxMatrices and MxAlgebras that are modified during runtime. Thus, the runstate slot expands the memory footprint of many mxGREML models by around 50%. We plan to eliminate the runstate slot in the next OpenMx release.
  • mxCompare() works correctly with WLS models only some of the time.
  • The argument names and documentation concerning user-provided WLS weight and asymptotic-covariance matrices are very confusing. A better interface and better documentation already exist in the source repository, and will be included in the next OpenMx release.
  • mxModelAverage() fails with an unhelpful error if any of reference quantities have variances of NaN in any of the MxModels in argument models.
  • The OpenMx Project's issue tracker can be found here.