R: Ancillary arguments for controlling nhm fits

nhm.control {nhm}

R Documentation

Ancillary arguments for controlling nhm fits

Description

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.

Usage

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,ncores=1,print.level=2, maxLikcontrol=NULL)

Arguments

`tmax`	Optional parameter to set the maximum time to which the Kolmogorov Forward equations should be integrated. Defaults to 1+max(time) if left unspecified.
`coarsen`	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.
`coarsen.vars`	Vector of the index of covariates which require coarsening. Must be supplied if `coarsen=TRUE`.
`coarsen.lv`	Number of unique covariate values to which the covariates should be coarsened.
`checks`	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`
`rtol`	Relative error tolerance to be passed to lsoda, default is 1e-6
`atol`	Absolute error tolerance to be passed to lsoda, default is 1e-6
`fishscore`	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.
`linesearch`	If `TRUE` and `fishscore=TRUE` then a line search will be performed to find the best step length in the Fisher scoring algorithm.
`damped`	If `TRUE` the Fisher scoring algorithm will be damped (e.g. Levenberg type algorithm). Useful if some parameters are close to being unidentifiable.
`damppar`	Numerical damping parameter to be applied if `damped=TRUE`
`obsinfo`	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.
`splits`	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.
`ncores`	Number of cores to use. 1= no parallelization, 2 or more: Uses `mclapply` when solving ODEs with different covariates patterns.
`print.level`	For `maxLik` optimization; level of detail to print. Integer from 0 to 3. Defaults to 2.
`maxLikcontrol`	For `maxLik` optimization; optional list of control parameters to be passed to `maxLik`.

Details

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. It may often be better to find more appropriate initial parameter estimates,for instance by fitting the analogous homogeneous model in msm, rather than adding multiple split times.

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.

Value

A list containing the values of each of the above constants

Author(s)

Andrew Titman a.titman@lancaster.ac.uk

References

Titman AC. Flexible Nonhomogeneous Markov Models for Panel Observed Data. Biometrics, 2011. 67, 780-787.