# Incorporating OpenMx in documentation examples of other packages.

7 posts / 0 new
Offline
Joined: 11/11/2011 - 22:18
Incorporating OpenMx in documentation examples of other packages.

I'm on a grant whose goal is to develop reliable kinship links to facilitate BG and other developmental studies with the NLSY samples (eg, http://www.bls.gov/nls/nlsy79.htm). We're developing an R package (cran.r-project.org/web/packages/NlsyLinks/) that assists with many of the common manipulations and analyses. We're targeting all BG researchers who are interested in the NLSY, including those with limited experience in R.

OpenMx seems like a natural fit for our examples, but I'm hesitant to use it in our basic documentation, because of two deployment issues:
(1) It doesn't have the typical deployment pattern for an R package, and
(2) It's not available in 64-bit Windows.

We'll definitely include OpenMx in the vignette examples, but it doesn't seem like a good fit for the documentation examples. I feel that anything beyond 10 example lines erodes the cohesiveness of the page. I don't want to explain that they'll need to close their 64-bit session and open a new 32-bit session (which is necessary if they're using the R Console, Tinn-R or RStudio). These extra details make the documentation examples much less automatic. They're trivial to experienced R users, but we're hoping to expand beyond that group.

Also, I'm hesitant to spend a few lines explaining that that the "source('http://openmx.psyc.virginia.edu/getOpenMx.R')" line will install OpenMx. That's something that the imports/depends/suggests package option does smoothly behind the scenes without user intervention.

I'm wondering if the package documentation will even pass the "R CMD check" process if it depends on a non-standard repository. (The documentation says a general rule is "All packages that are needed to successfully run R CMD check on the package must be listed in one of ‘Depends’ or ‘Suggests’ or ‘Imports’. Packages used to run examples or tests conditionally (e.g. via if(require(pkgname))) should be listed in ‘Suggests’ or ‘Enhances’. (This allows checkers to ensure that all the packages needed for a complete check are installed.)" -http://cran.r-project.org/doc/manuals/R-exts.html).

How have these issues been addressed in the past? Are there any existing R packages that use OpenMx (in their documentation examples or as an imports/depends/suggests option) that I can learn from?

We know there are other SEM packages, but I really prefer this one. We're most familiar with Mx/OpenMx. We also feel it could be the best choice for the users of our package (both in the beginners and as the learn more BG).

-Will
-----
Mike Hunter has been kind enough to explain the licensing issues why OpenMx isn't immediately available through the conventional CRAN mechanism. And regarding the Windows 64-bit build, have the developers considered using R's WinBuilder (http://win-builder.r-project.org/)? I've never used it, but its self-description is: "this is intended for developers on other platforms who do not have access to Windows but wish to provide binaries for the Windows platform."

edit: modified description of grant's goals.

Offline
Joined: 07/31/2009 - 15:24
Hi Will, The 64-bit windows

Hi Will,

The 64-bit windows issue is related to the licensing issue. Because we currently rely on the NPSOL optimizer, which we are free to distribute as a binary but not the source code, then we need to compile a NPSOL library for 64-bit windows. Our attempts to use Rtools (http://www.murdoch-sutherland.com/Rtools/) to compile a 64-bit version of NPSOL on windows have not been successful.

Offline
Joined: 11/11/2011 - 22:18
64-bit obstacles

Is the Rtools the same thing as Winbuilder? I got the impression they're different, but I've never used either.

If neither accomplishes what you need, I’m happy to build the 64-bit Windows binaries and return them to you guys to deploy. I’ll set up a VM with this as its sole purpose. My company has an MSDN subscription, so it won’t cost any licensing fees. Since it’s a VM, I could later migrate/ship it to your system easily, if your team ever believes it’s in your interest to control that yourself (but you would have to purchase your own license).

Would that address the obstacle that is currently blocking 64-bit Windows users? Or am I misunderstanding some technical or licensing issue? This group of users is huge already, and will continue growing as more Netburst CPUs are retired and most standard computers arrive with 4GB+ RAM.

Offline
Joined: 07/31/2009 - 14:25
Answer to typical deployment pattern question

The procedure to install OpenMx can be almost as short a one-liner as a package already on CRAN.

Just use:

install.packages('OpenMx', repos='http://openmx.psyc.virginia.edu/testing/')
Offline
Joined: 11/11/2011 - 22:18

Thanks Timothy, I like your suggestion (and the related thread you started). That does make it more self-explanatory than the 'source' command, with minimal added complexity.

But I don't think it's a favorable comparison to a package on CRAN. Those packages don't require any extra installation code in the examples, if they're in the 'Depends' or 'Imports' field of my package's DESCRIPTION file.

The install.packages line make the example code & explanation a little longer. But my real objection is that some person or some code has to check to see if it's installed already. That extra management is unnecessary with conventional deployment pattern. It's so convienent that a conventional imported package installs only once (if it's not already) when my package installs, and then loads only once (if it's not loaded already) when my code or example types require. The extra OpenMx installation work & explanation can fit into a vignette example well, but not a documentation example, especially for a portion of the users that we're targeting.

Is anyone aware of other CRAN packages that Depends/Imports OpenMx? Either for documentation examples, or that are integrated into their actual code? Your software is so powerful and useful, I'm sure I'm not the first package author who wanted to Import it.

Offline
Joined: 07/31/2009 - 15:24
As one of the developers, I

As one of the developers, I agree with all your comments. There are several package authors who want to declare the OpenMx package as an dependency. Unfortunately, we don't have a viable solution. Many of these issues would disappear if we had an efficient open-source numerical optimizer that supported linear systems with non-linear constraints. Hint: we've been trying to fund such a project but review committees have been lukewarm on the idea. Promote the need for such a project to your peers and colleagues if you agree that it is worthwhile goal.

Offline
Joined: 11/11/2011 - 22:18
I’m sorry the funders on

I’m sorry the funders on those review committees haven’t yet interpreted the situation similarly. Avoiding that licensing restriction and deploying it through CRAN, will lower the barrier and can introduce more people to OpenMx. Package authors can refer to and depend on it with more ease and more trust.

For software to be popular, I think it helps to be accessible and useful to a broad spectrum of abilities. Spss is good at the entry-level, but limiting at the high-level. Mplus is the opposite -especially if you consider the price. (Don’t get me started on SAS).

Hooking beginners, and growing with them as they become more sophisticated, is something Mx/OpenMx has been good at for a while. The easy transition from Mx’s GUI to code input is an example of this. I’m sure this current issue has been given much more careful thought by your team than I’m doing now. But I thought I’d share my outsider opinion regardless.

If licensing restrictions required two different versions of the package (ie, one on CRAN and one at openmx.psyc.virginia.edu/testing/), that might be a huge pain to ensure their APIs were exactly identical -including the output format and their error messages. I guess it depends on how encapsulated NPSOL (and it’s open source alternative) is.