Auxillary function which packages the optional parameters of a
coxme
fit as a single list.
1 2 3 4 5 6 7  coxme.control(eps = 1e08, toler.chol = .Machine$double.eps^0.75,
iter.max = 20, inner.iter = Quote(max(4, fit0$iter+1)),
sparse.calc = NULL,
optpar = list(method = "BFGS", control=list(reltol = 1e5)),
refine.df=4, refine.detail=FALSE, refine.method="control",
sparse=c(50, .02),
varinit=c(.02, .1, .4, .8)^2, corinit = c(0, .3))

eps 
convergence criteria for the partial likelihood 
toler.chol 
tolerance for the underlying Cholesky decomposition. This is used to detect singularity (redundant variables). 
iter.max 
maximum number of iterations for the final fit 
inner.iter 
number of iterations for the ‘inner loop’ fits, i.e. when the
partial likelihood is the objective function of 
sparse.calc 
choice of method 1 or 2 for a particular portion of the calculation. This can have an effect on run time for problems with thousands of random effects. 
optpar 
parameters passed forward to the 
refine.df 
the degrees of freedom for the tdistribution used to draw random samples for the refine.n option 
refine.detail 
this option is mostly for debugging. If TRUE
then an extra component 
refine.method 
method by which the control calculations are done. This is a current research/development question, the option will likely disappear at some future date, and users should ignore it. 
sparse 
rule for deciding sparsity of a random effect, see details below. 
varinit 
the default set of starting values for variances, used if no

corinit 
the default set of starting values for correlations. 
The main flow of coxme
is to use the optim
routine to
find the best values for the variance parameters. For any given trial
value of the variance parameters, an inner loop maximizes the partial
likelihood to select the regression coefficients beta (fixed) and b
(random). Within this loop cholesky decomposition is used. It is
critical that the convergence criteria of inner loops be less than
outer ones, thus toler.chol < eps < reltol.
If no starting values are supplied for the variances of the random effects then a grid search is performed to select initial values for the main iteration loop. The default values given here are based on experience but without any formal arguments for their optimality. We have found that the estimated standard deviation of a random effect is often between .1 and .3, corresponding to exp(.1)= 1.1 to exp(.3)= 1.35 fold “average” relative risks associated with group membership. This is biologically reasonable for a latent trait. Other common solutions ane a small random effect corresponding to only 1–5% change in the hazard or likelihood that is maximized at the boundary value of 0 variance. Variances greater than 2 are very unusual. Because we use the log(variance) as our iteration scale the 0–.001 portion of the variance scale is stretched out giving a loglikelihood surface that is almost flat; a NewtonRaphson iteration starting at log(.2) may have log(.0001) as its next guess and get stuck there, never finding a true maximum that lies in the range of .01 to .05. Corrleation paramters seem to need fewer starting points.
The sparse option controls a sparse approximation in the code.
Assume we have a mixed effects model with a random intercept per group,
and there are 1000 groups.
In a Cox model (unlike a linear mixed effects model) the resulting
second derivative matrix used during the solution will be 1000 by 1000
with no zeros, and
fitting the model can consume a large amount of both time and memory.
However, it is almost sparse, in that elements off the diagonal are
very small and can often be ignored. Computation with a sparse
matrix approximation will be many times faster.
Luckily, as the number of groups increases the accuracy of the
approximation also increases.
If sparse=c(50, .03)
this states that sparse approximation will
be employed for any grouping variable with 50 or more levels, and off
diagonal elements that relate any two levels both of which represent
.03 of less of the total sample will be treated as zero.
a list of control parameters
Terry Therneau
coxme
Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.
All documentation is copyright its authors; we didn't write any of that.