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
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?
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.
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
How about "imx" for internel OpenMx functions.
imx makes sense, and is memorable.