OpenMx library function names

5 replies [Last post]
mspiegel's picture
Offline
Joined: 07/31/2009

Currently the functions named "omx*" consist of (A) uncommon functions that we intend to remain backwards compatible in all future versions of OpenMx, and (B) uncommon functions that may be helpful to advanced OpenMx users but whose interface might change in the future. We would like to keep type (A) functions in the "omx*" category and rename type (B) functions with a new character prefix. We wish to solicit feedback on which functions should remain in the "omx*" category, and get suggestions for the new prefix string for the type (B) functions.

At the bottom of this forum post are all the current "omx*" functions. Here is an initial suggestion of which functions should remain "omx*" functions: omxAllInt, omxApply, omxAssignFirstParameters, omxCheckCloseEnough, omxCheckEquals, omxCheckError, omxCheckIdentical, omxCheckSetEquals, omxCheckTrue, omxCheckWithinPercentError, omxGetParameters, omxGraphviz, omxInterval, omxLapply, omxMnor, omxParallelCI, omxQuotes, omxSapply, omxSetParameters, omxSymbolTable.

The new prefix for the remaining functions should be the following criteria:

  • should be relatively short
  • should not start with "mx" or "omx" (for tab completion)
  • should be all lowercase
  • should not Google rank too high. These are uncommon functions, so we don't want them showing up. That rules out "openmx"

My suggestion is "opmx".

Here are all the current "omx*" functions:

omxAddDependency              omxIndependentModels
omxAllInt                     omxInitModel
omxApply                      omxInterval
omxAssignFirstParameters      omxIsDefinitionVariable
omxCheckCloseEnough           omxIsPath
omxCheckEquals                omxLapply
omxCheckError                 omxLocateIndex
omxCheckIdentical             omxLocateLabel
omxCheckMatrices              omxLookupSymbolTable
omxCheckNamespace             omxMnor
omxCheckSetEquals             omxModelBuilder
omxCheckTrue                  omxModelTypes
omxCheckVariables             omxOriginalMx
omxCheckWithinPercentError    omxParallelCI
omxConstraintRelations        omxQuotes
omxConvertIdentifier          omxReplaceMethod
omxConvertLabel               omxReplaceModels
omxConvertSubstitution        omxReservedNames
omxDataTypes                  omxReverseIdentifier
omxDependentModels            omxSameType
omxEvalByName                 omxSapply
omxExtractMethod              omxSeparatorChar
omxExtractNames               omxSetParameters
omxExtractReferences          omxSquareMatrix
omxFilterDefinitionVariables  omxSymbolTable
omxFlattenModel               omxSymmetricMatrix
omxFreezeModel                omxTypeName
omxGenSwift                   omxUntitledName
omxGenerateLabels             omxUntitledNumber
omxGenerateNamespace          omxUntitledNumberReset
omxGenericModelBuilder        omxUpdateModelValues
omxGetParameters              omxVerifyMatrix
omxGetRAMDepth                omxVerifyModel
omxGraphviz                   omxVerifyName
omxIdentifier                 omxVerifyReference

tbates's picture
Offline
Joined: 07/31/2009
It will help to have a

It will help to have a shorter omx completion list.

Also concur on the proposed list to satay as omx.

I think of omx as a mixture of "helpful" and "internal" functions, and the helpful ones are staying.

To make the division, I would say either
1. bmx or bomx for Beta Off-piste openMX function
2. amx or for advanced (and obscure) openMX function

mspiegel's picture
Offline
Joined: 07/31/2009
How about "imx" for internel

How about "imx" for internel OpenMx functions.

tbates's picture
Offline
Joined: 07/31/2009
imx makes sense, and is

imx makes sense, and is memorable.

Ryne's picture
Offline
Joined: 07/31/2009
umx, where 'u' means

umx, where 'u' means 'unstable'? I'm worried that omx and umx might be too close to one another, but starting with a new first letter will ease organization for tab completion and docs.

I'll add 'omxCheckIdentical' and 'omxGetRAMDepth" to my nominations for the omx list.

Will we be migrating functions from the new designation to omx as they become stable? If opmxBrownie or umxBrownie becomes stable, to we move it to omx, or copy it?

tbrick's picture
Offline
Joined: 07/31/2009
The list of functions looks

The list of functions looks pretty good to me.

I'm not sure I'm sold on any of these yet, but using umx has the added benefit that the alphabetic sort order for these goes mx, omx, umx. This is actually a nice thing, in case people go scrolling through function lists or documentation sets. It also won't show up if somebody autocompletes from just an o.

I am a tiny bit concerned about using the term 'unstable', since folks are likely to interpret that differently than we mean it here.

To answer your question, if we decide umxBrownie should move into the fixed user API, we can just move it to be omxBrownie, and make a note in the changelog. This is expected behavior since umx functions are not guaranteed to stay the same. I don't see any reason we'd change something from omx to umx, but if we do, we need to copy it and leave the omx function intact (but deprecated), since those are guaranteed to be consistent. If we decide to move something from omxBrownie to mxBrownie, we'd have to keep both around and available for a couple revisions at least, with omxBrownie deprecated.