Learn R Programming

OpenMx (version 2.7.9)

mxTryHard: Make multiple attempts to run a model

Description

Makes multiple attempts to fit an MxModel object with mxRun() until the optimizer yields an acceptable solution or the maximum number of attempts is reached. Each attempt uses the parameter estimates of the previous attempt as start values, but they are each perturbed by random numbers, and optimization-control parameters may be altered. From among its attempts, the function returns the fitted, post-mxRun() model with the smallest fit-function value, and can print to the console the start values it used for that model.

Usage

mxTryHard(model, extraTries = 10, greenOK = FALSE, loc = 1, scale = 0.25,
initialGradientStepSize = imxAutoOptionValue("Gradient step size"),
initialGradientIterations = imxAutoOptionValue('Gradient iterations'),
initialTolerance=as.numeric(mxOption(NULL,'Optimality tolerance')), 
checkHess = TRUE, fit2beat = Inf, paste = TRUE,	iterationSummary=FALSE, 
bestInitsOutput=TRUE, showInits=FALSE, verbose=0, intervals = FALSE,
finetuneGradient=TRUE, jitterDistrib=c("runif","rnorm","rcauchy"), exhaustive=FALSE,
maxMajorIter=3000, OKstatuscodes, wtgcsv=c("prev","best","initial"))

mxTryHardOrig(model, finetuneGradient=FALSE, maxMajorIter=NA, wtgcsv=c("prev","best"), ...)

mxTryHardctsem(model, initialGradientStepSize = .00001, initialGradientIterations = 1, initialTolerance=1e-12, jitterDistrib="rnorm", ...)

mxTryHardWideSearch(model, finetuneGradient=FALSE, jitterDistrib="rcauchy", exhaustive=TRUE, wtgcsv="prev", ...)

mxTryHardOrdinal(model, greenOK = TRUE, checkHess = FALSE, finetuneGradient=FALSE, exhaustive=TRUE, OKstatuscodes=c(0,1,5,6), wtgcsv=c("prev","best"), ...)

Arguments

model
The MxModel to be run.
extraTries
The number of attempts to run the model in addition to the first. In effect, is the maximum number of attempts mxTryHard() will make, since the function will stop once an acceptable solution is reached. Defaults to 10 (for mxTryHard()), in which case a maximum of 11 total attempts will be made.
greenOK
Logical; is a solution with Mx status GREEN (optimizer status code 1) acceptable? Defaults to FALSE (for mxTryHard()). Ignored if a value is provided for OKstatuscodes.
loc, scale
Numeric. The location and scale parameters of the distribution from which random values are drawn to perturb start values between attempts, defaulting respectively to 1 and 0.25. See below, under "Details," for additional information.
initialGradientStepSize, initialGradientIterations, initialTolerance
Numeric. Initial values of optimization-control parameters passed to mxComputeGradientDescent() if model is using the default compute plan.
checkHess
Logical; is a positive-definite Hessian a requirement for an acceptable solution? Defaults to TRUE (for mxTryHard()). If TRUE, the Hessian and standard errors are calculated with each fit attempt, irrespective of the value of relevant options. The exception is if model or any of its submodels contains MxConstraints, in which case checkHess is coerced to TRUE.
fit2beat
Numeric upper limit to the fitfunction value that an acceptable solution may have. Useful if a nested submodel of model has already been fitted, since model, with its additional free parameters, should not yield a fitfunction value any greater than that of the submodel.
paste
Logical. If TRUE (default), start values for the returned fitted model are printed to console as a comma-separated string. This is useful if the user wants to copy-paste these values into an R script, say, in an omxSetParameters() statement. If FALSE, the vector of start values is printed as-is. Note that this vector, from omxGetParameters(), has names corresponding to the free parameters; these names are not displayed when paste=TRUE.
iterationSummary
Logical. If TRUE, displays parameter estimates and fit values for every fit attempt. Defaults to FALSE.
bestInitsOutput
Logical. If TRUE, displays starting values that resulted in best fit, according to format specified by paste argument. Defaults to TRUE.
showInits
Logical. If TRUE, displays starting values for every fit attempt. Defaults to FALSE.
verbose
If model is using the default compute plan, is passed to mxComputeGradientDescent() to specify level of output printed to console during optimization.
intervals
Logical. If TRUE, OpenMx will estimate any specified confidence intervals.
finetuneGradient
Logical. If TRUE (default for mxTryHard()), then as repeated fit attempts appear to be improving, mxTryHard() will adjust optimization-control parameters gradientStepSize, gradientIterations, and tolerance, as well as argument scale, to "fine-tune" its convergence toward an optimal solution. finetuneGradient=FALSE is recommended for analyses involving thresholds.
jitterDistrib
Character string naming which random-number distribution--either uniform (rectangular), normal (Gaussian), or Cauchy--to be used to perturb start values. Defaults to the uniform distribution (for mxTryHard()). See below, under "Details," for additional information.
exhaustive
Logical. If FALSE (default for mxTryHard()), mxTryHard() stops making additional attempts once it reaches an acceptable solution. If TRUE, the function instead continues until it reaches its maximum number of attempts (as per extraTries), and returns the best solution it found.
maxMajorIter
Integer; passed to mxComputeGradientDescent(). Defaults to 3000, which was the internally hardcoded value mxTryHard() used in at least one prior version of OpenMx. Value of NA is permitted, in which case mxTryHard() will calculate a value via the on-load default formula for the "Major iterations" option.
OKstatuscodes
Optional integer vector containing optimizer status codes that an acceptable solution is permitted to have. mxTryHard() always considers a status code of 0 to be acceptable, this argument notwithstanding. By default, mxTryHard() will consider status code 0 acceptable, and, if greenOK=TRUE, status code 1 as well. If a value is supplied for OKstatuscodes that conflicts with greenOK, OKstatuscodes controls.
wtgcsv
Character vector. "Where to get current start values." See below, under "Details," for additional information.
...
Additional arguments to be passed to mxTryHard().

Value

Usually, mxTryHard() returns a post-mxRun() MxModel object. Specifically, this will be the fitted model having the smallest fit-function value found by mxTryHard() during its attempts. The start values used to obtain this fitted model are printed to console if bestInitsOutput=TRUE. If every attempt at running model fails, mxTryHard() returns an object of class 'try-error'. mxTryHard() throws a warning if the returned MxModel object has a nonzero status code (unless nonzero status codes are considered acceptable per argument greenOK or OKstatuscodes).

Details

mxTryHardOrig(), mxTryHardctsem(), mxTryHardWideSearch(), and mxTryHardOrdinal() are wrapper functions to the main workhorse function mxTryHard(). Each wrapper function has default values for certain arguments that are tailored toward a specific purpose. mxTryHardOrig() imitates the functionality of the earliest implementations of mxTryHard() in OpenMx's history; its chief purpose is to find good start values that lead to an acceptable solution. mxTryHardctsem() uses mxTryHard() to "zero in" on an acceptable solution with models that can be difficult to optimize, such as continuous-time state-space models. mxTryHardWideSearch() uses mxTryHard() to search a wide region of the parameter space, in hope of avoiding local fitfunction minima. mxTryHardOrdinal() attempts to use mxTryHard() as well as it can be used with models involving ordinal data. Argument wtgcsv dictates where mxTryHard() is permitted to find free-parameter values, at the start of each fit attempt after the first, before randomly perturbing them to create the current fit attempt's start values. If "prev" is included, then mxTryHard() is permitted to use the parameter estimates of the most recent non-error fit attempt. If "best" is included, then mxTryHard() is permitted to use the parameter estimates at the best solution so far. If "initial" is included, then mxTryHard() is permitted to use the initial start values in model, as provided by the user. The default is to permit all three, in which case mxTryHard() is written to use the best solution's values if available, and otherwise to use the most recent solution's values, but to periodically revert to the initial values if recent fit attempts have not improved on the best solution. Once the start values are located for the current fit attempt, they are randomly perturbed before being assigned to the MxModel. The distributional family from which the perturbations are randomly generated is dictated by argument jitterDistrib. The distribution is parametrized by arguments loc and scale, respectively the location and scale parameters. The location parameter is the distribution's median. For the uniform distribution, scale is the absolute difference between its median and extrema (i.e., half the width of the rectangle); for the normal distribution, scale is its standard deviation; and for the Cauchy, scale is one-half its interquartile range. Start values are first multiplied by random draws from a distribution with the provided loc and scale, then added to random draws from a distribution with the same scale but with a median of zero.

See Also

mxRun(), mxComputeTryHard

Examples

Run this code
<!-- %Could use a better example... -->
library(OpenMx)

data(demoOneFactor)  # load the demoOneFactor dataframe

manifests <- names(demoOneFactor) # set the manifest to the 5 demo variables
latents   <- c("G")  # define 1 latent variable
model <- mxModel(model="One Factor", type="RAM",
    manifestVars = manifests,
    latentVars   = latents,
    mxPath(from=latents, to=manifests, labels=paste("b", 1:5, sep="")),
    mxPath(from=manifests, arrows=2, labels=paste("u", 1:5, sep="")),
    mxPath(from=latents  , arrows=2, free=FALSE, values=1.0),
    mxData(cov(demoOneFactor), type="cov", numObs=500)
)
model <- mxTryHard(model) # Run the model, returning the result into model
summary(model) # Show summary of the fitted model

Run the code above in your browser using DataLab