This is used to set various logical or numeric parameters controlling a non-homogeneous Markov model fit. Usually to be used within a call to nhm.
nhm.control(tmax=NULL, coarsen=FALSE, coarsen.vars=NULL, coarsen.lv=NULL,
checks=FALSE,rtol=1e-6, atol=1e-6, fishscore=NULL, linesearch=FALSE, damped=FALSE,
damppar=0,obsinfo=TRUE,splits=NULL,safe=FALSE, ncores=1,parallel_hess=TRUE,
print.level=2, maxLikcontrol=NULL, nlminb_control=list(),constrained=FALSE,
lower_lim=-Inf, upper_lim=Inf,nlminb_scale=1)A list containing the values of each of the above constants.
Optional parameter to set the maximum time to which the Kolmogorov Forward equations should be integrated. Defaults to 1+max(time) if left unspecified.
If TRUE the covariate values will be subjected to coarsening using K-means clustering, so there are fewer unique values. This is useful for large datasets with continuous covariates.
Vector of the index of covariates which require coarsening. Must be supplied if coarsen=TRUE.
Number of unique covariate values to which the covariates should be coarsened.
If TRUE some basic checks will be performed to ensure the accuracy of the supplied intens function. Mainly useful if a user defined type="bespoke" intensity function is used for which the default is TRUE, otherwise default is FALSE
Relative error tolerance to be passed to lsoda, default is 1e-6
Absolute error tolerance to be passed to lsoda, default is 1e-6
If TRUE then the Fisher scoring algorithm will be used provided the model has no censoring, exact death times or misclassification. This is generally faster, but less robust than the BHHH algorithm.
If TRUE and fishscore=TRUE then a line search will be performed to find the best step length in the Fisher scoring algorithm.
If TRUE the Fisher scoring algorithm will be damped (e.g. Levenberg type algorithm). Useful if some parameters are close to being unidentifiable.
Numerical damping parameter to be applied if damped=TRUE
If TRUE the observed Fisher information will be computed in addition to the expected information when the Fisher scoring algorithm is used. For optimization with maxLik the observed Fisher information will be used as the Hessian rather than the squared gradient vectors.
Optional vector of intermediate split times for solving the ODEs. Only needed if P(0,t) becomes singular for some t causing the optimization to stop. Should be a set of consecutive values less than tmax.
If TRUE will solve ODEs only from unique start times rather
than by inverting.
Number of cores to use. 1= no parallelization, 2 or more: Uses mclapply when solving ODEs with different covariates patterns.
If TRUE then applies parallelization using ncores (at an overall functional evaluation level) to find the final Hessian by finite differences.
For maxLik optimization; level of detail to print. Integer from 0 to 3. Defaults to 2.
For maxLik optimization; optional list of control parameters to be passed to maxLik.
For nlminb optimization; optional list of
control parameters to be passed to nlminb.
If TRUE then box-constrained optimization using nlminb will be used rather than BHHH or Fisher scoring.
Lower limits for box-constrained. Should either be a scalar or a numeric vector of length equal to number of unknown parameter.
Upper limits for box-constrained. Should either be a scalar or a numeric vector of length equal to number of unknown parameter.
Numeric value to be used as the scale argument in
nlminb.
Andrew Titman a.titman@lancaster.ac.uk
tmax, rtol and atol refer directly to parameters with the lsoda function in deSolve and relate to how the Kolmogorov Forward Equations are numerically solved.
coarsen, coarsen.vars and coarsen.lv are useful in situations where it is computationally infeasible (or unattractive) to compute the exact solution for all covariate patterns. Implements an approximate solution in which the covariates are coarsened using K-means clustering (as proposed in Titman (2011)).
linesearch, damped, damppar are specific to the Fisher scoring algorithm.
Setting obsinfo=TRUE will tend to give more accurate standard error estimates and gives more opportunity to check for non-convergence of the maximum likelihood procedure.
The option splits modifies the way in which the transition probabilities are computed. By default, nhm solves a single system of differential equations starting from 0 to obtain \(P(0,t)\) and then uses inversion of the Chapman-Kolmogorov equation \(P(0,t) =P(0,t_0)P(t_0,t)\) to find \(P(t_0,t)\) for a given \(t_0 > 0\). In some cases \(P(0,t_0)\) will be singular or effectively singular. If a split is specified at \(s\) then nhm will find \(P(t_0,t)\) for \(t_0 > t*\) by solving the system of equations \(P(t*,t)\) where \(t*\) is the smallest interval start time greater than or equal to \(s\) within the data. If nhm fails due to the lack of split times, the error message will advise on the interval in which the split should be introduced.
Note that the need for splits can also arise if the initial parameters specified are inappropriate, or for models where the likelihood is quite flat in some directions. Hence it will usually be better to either find more appropriate initial parameter estimates (for instance by fitting the analogous homogeneous model in msm) or to use constrained=TRUE and set lower and
upper bounds for the parameter values, than set many split values. An option safe=TRUE can also
be chosen. This avoids using any inversion of \(P(t_0,t)\) to find transition probabilities but will
come at the cost of large increase in computation time.
ncores allows parallel processing to be used, through the parallel package, to simultaneously solve the systems of differential equations for each covariate pattern. If ncores > 1 then ncores defines the mc.cores value in mclapply. Note that the data needs to include multiple covariate patterns for this to successfully increase computation speed.
parallel_hess specifies whether the parallelization should also apply to the computation of the final Hessian to compute the observed Fisher information (used if obsinfo=TRUE and either constrained=TRUE or fishscore=TRUE). Generally, this should be more efficient since each overall function evaluation should take approximately the same time. However, for large datasets and large numbers of cores it may cause memory issues.
Setting parallel_hess=FALSE when ncores>1 means that the parallelization will instead apply within each function evaluation at the ODE solver stage.
Titman AC. Flexible Nonhomogeneous Markov Models for Panel Observed Data. Biometrics, 2011. 67, 780-787.
nhm