The names ctFit reads from optimcontrol. A name means
the same thing on both backends. One a backend does not have is refused by
name, unless its value asks for nothing that backend does not already do
(gradient = 'adjoint' on stan, nsubsets = 1 on julia), and a
misspelled name is an error. Leaving a name unset keeps that backend's own
default.
Stopping
tolBoth. Stop when the objective changes by less than this. Default
1e-8on stan, off on julia.g_tolBoth. Stop when the l2 norm of the gradient falls below this. Default
1e-8on julia, off on stan.x_tolBoth. Stop when the parameter step falls below this. Off by default.
maxiterBoth. Iteration cap. Default 1000 on julia, mize's on stan.
lbfgs_scoresJulia. Default TRUE. Runs beside L-BFGS a second model of the curvature, the centred outer product of the per-unit scores plus the prior's precision and a learned correction, and takes each step on whichever model predicted the last step's gain better; while a fit is batched, only on the whole data.
lbfgs_localJulia. Default TRUE. On the Laplace route, where some parameters are read by few units (a study's, a group's, an item few answered), starts L-BFGS's inverse Hessian from their exact Hessian columns, differenced over those units alone, and the score model of the rest; built once the optimisation has spent what it costs.
lbfgs_memoryBoth. How many curvature pairs L-BFGS keeps. Default on julia one per free parameter, at least 20 and at most 1000; mize's on stan.
stallretriesBoth. Default 2. How often a fit that stopped short of a maximum is tried again: stan restarts from fresh random values when the gradient exceeds
stalltolper data point; julia resumes from the better point its probe found by pulling flat coordinates back, or from where it stopped when the check finds the fit short, keeping a resumed stage only if it improves the objective, and stopping one that stops gaining. 0 turns it off.
Starting values
initsdBoth. Default 0.01. The sd of the random start, on the raw scale.
datastartJulia. Default TRUE. Starting values for the diagonals of DRIFT, DIFFUSION, T0VAR and MANIFESTVAR are read off the data's scale – through the link, so a count is read through
log1pand a binary or ordinal indicator contributes none – rather than from one fixed point whatever the units. They are kept only where the objective can be evaluated there; otherwise the fit starts from the default and says so. Suppliedinitsare never overridden.carefulfitBoth. A rough first pass with ctsem's
normal(0,1)raw priors on every coordinate, for starting values; the fit's own objective is then maximised from there. Skipped withpriors = TRUE, which already has those priors, and wheninitsare supplied. Default TRUE on both backends. On julia it runs to its own convergence, at most 200 iterations, and a number sets that cap; it keeps the fit from starting where a boundary (a correlation at one, a variance at zero) has already captured it.fit$optim$carefulfitrecords whether it ran.
The optimiser
stochasticBoth. Start with ctsem's stochastic-gradient optimiser and finish with L-BFGS;
'auto'does so above 50 parameters. Default TRUE on stan, FALSE on julia. On large, poorly conditioned models it can be much faster than L-BFGS alone, and it can carry a fit further toward a degenerate limit, such as a variance running to zero.fit$optim$sgd_iterationsrecords the phase.gradientJulia.
'adjoint'(reverse mode, the default) or'forward'. The same gradient; the adjoint's cost does not grow with the number of parameters.batchJulia. Default TRUE, or FALSE when
initsare supplied. Start on a random subset of the subjects and grow it as the fit needs more data; needs at least 80 subjects or top-level groups. A supplied start is not batched from, since the subsets' gradients walk off a point already chosen;TRUEasks for it anyway.coresetJulia. Default
'auto'. Run stretches of L-BFGS on a weighted few of the units (subjects, or top-level groups where random effects are integrated by Laplace), chosen so that their changes in gradient and their spread reproduce all the units', each stretch checked by a full gradient; the full objective finishes, so the estimate and its standard errors are those of every unit.'auto'runs them for data of at least 200 subjects or top-level groups and 10,000 data cells (rows times manifest variables), where they save time; on smaller data they save none and can change which of several maxima a fit reaches.TRUEruns them whenever a coreset is expected to save gradients,FALSEnever.fit$optim$coreset_sizesrecords the stages.explosive_forwardJulia. Default FALSE. For a subject whose predictions grow more than 100-fold between observations (explosive dynamics over a long gap), take its gradient by forward mode instead of the reverse pass, as a cross-check: the reverse pass is accurate there too. The first such subject in a session compiles the filter again, minutes on a large model. The fit counts such subjects either way (
fit$optim$explosive_passes) and warns when any is explosive at the estimate.lbfgs_diagonalJulia. Default TRUE. L-BFGS's initial inverse Hessian takes a scale per parameter, learned from the curvature pairs (Gilbert and Lemarechal); FALSE uses one scale for all, which can be much slower on large models. Like
stochastic, it can carry a fit further toward a degenerate limit.lbfgs_gllJulia. Default 0. A step is accepted against the worst of the last
Wobjective values (Grippo, Lampariello and Lucidi), so it may cross a curved valley.lbfgs_nonmonotoneJulia. Between 0 (the default) and 1. A step is accepted against a running average of recent objective values (Zhang and Hager).
initial_alphaJulia. Default 0.1. The length of the first trial step, in raw units.
preconditionJulia. Default FALSE. TRUE starts L-BFGS's per-parameter scaling from the model's transforms rather than learning it from the curvature alone. It made fits whose intercepts start far from the data settle in worse optima.
saemJulia,
intoverpop = 'laplace'. Default FALSE. Start with SAEM: the random effects are sampled from their conditional distribution rather than integrated by the Laplace approximation, heading for the exact marginal posterior mode. The usual optimiser then polishes and certifies its point on the Laplace objective, so the estimate usually ends where a fit without SAEM does; what it can change is which maximum is reached when the Laplace objective has more than one. Its point carries Monte Carlo error, so where the posterior itself has several maxima – weakly identified random-effect scales and correlations – that error, not the data, can decide which one is reached. So the fit also finishes from its own start without SAEM, one more optimisation, and keeps whichever maximum has the higher log posterior on the quadrature-corrected objective (quadrature for each unit narrow enough, as the refined fit screens), where a maximum the Laplace approximation over-credits loses;fit$optim$saem_guardrecords both. Not a better approximate estimate on its own – for that, sample withoptimize = FALSE. A number caps its iterations (TRUE is 10000).fit$optim$saem_iterations,saem_settled,saem_trend,saem_chains,saem_acceptanceandsaem_tracerecord the phase.saem_proposalJulia. SAEM's proposal,
'rw'or'laplace'.restartsJulia. Default 0. Random restarts for a fit that has still not converged after its corrections – typically a likelihood with more than one basin – each from the fit's own start plus normal noise of sd
restartsd(default 1) on the raw scale, keeping the best if it is better. They run in worker processes whencores > 1and the fit took more than 30 seconds. Not wheninitsormaxiterwere supplied.fit$optim$restartsrecords each start.
The finish and its certification (julia)
newtonDefault TRUE. Newton steps once close, on an exact Hessian updated after each step and formed again when its steps stop paying for it, ending on the Hessian the certification and the standard errors use; it tries the direction of negative curvature at a saddle and checks what the directions with no curvature are worth. Under
intoverpop = 'laplace'it runs only when the fit is certified. May name the curvature its steps use:'chord'(the default except as below),'exact'(a fresh Hessian whenever a step contracts slowly),'subset', or'krylov': the outer product of the units' scores corrected by Hessian-vector products taken at each step, with the exact Hessian formed where its steps converge.'krylov'is the default underintoverpop = 'laplace'where the exact Hessian would cost at least 200 gradients.fit$optim$newton_stepsrecords the steps, andnewton_krylov_productsthe gradients the Krylov steps took.certifyDefault TRUE. The curvature check that certifies a fit has converged.
estonlyskips it too.gaptolDefault
5e-5. How much objective the curvature may still predict at the estimate before the fit is continued. The gap is half the squared distance from the maximum in standard errors, so the default is 0.01 standard errors, a tenth ofhessianreuse: close enough that the estimate's Hessian is the maximum's. A smaller value, such as1e-6, holds the estimate closer still.hessianreuseDefault 0.1. How far, in standard errors, the estimate may move from where a Hessian was formed for that Hessian still to give the standard errors. A Wald standard error assumes the curvature is constant over about a standard error around the estimate, and is in error by however much it is not; a Hessian formed this far away adds about this fraction to that error, where forming a fresh one costs a gradient per parameter (two on the Laplace route). 0 forms one at the estimate.
innergaptolWhat a prediction of the remaining gain that can be optimistic – L-BFGS's, or a Newton step's on a Hessian taken at another point – has to fall below to stop; by default a hundredth of
gaptol. A gain read off the exact Hessian at the estimate is held togaptolitself.overshoot'magnitude'(the default),'saturation'or'off': which directions are pulled back after a fit, to test whether it stopped at a maximum.stallwindow,stallratio,stallcooldownThe stall check (defaults 80, 0.001, 30): over how many iterations a fit's gain is read (half a nat or less starts a look for a transform gone flat), how much of its responsiveness a transform must have lost to count as the reason the fit stopped, and how long the check waits after finding a fit slow rather than stuck.
escapesaturatedDefault FALSE. Refit a fit stalled on a saturated transform from a zeroed boundary, keeping whichever wins.
escapepinDefault FALSE. Hold the escaped coordinates still while the rest re-optimises around them, then release them.
The Laplace route (julia, intoverpop = 'laplace')
laplace_inner_maxiter,laplace_inner_tolDefaults 200 and
1e-10. The inner solve that finds each unit's random-effect mode. Raise the first when the fit reports modes that did not converge; the tolerance bounds the inner gradient, floored at1e-10 * (1 + abs(value)).laplace_soft_directions'quadrature'(the default) or'logdet_floor': how a unit is scored whose likelihood is convex in some direction of its random effects, where plain Laplace would credit that direction more width than the integrand has.'quadrature'integrates the softest direction by a three-point quadrature where the unit's curvature has an eigenvalue below 0.7, blending into plain Laplace between 0.2 and 0.7;'logdet_floor'floors the log determinant at zero. Recorded infit$laplace$soft_directions, and used by every function that rebuilds the objective;fit$laplace$conditioningcounts such units. It applies too when sampling withintoverpop = FALSEandsampleControl$placement = 'fit'.
Uncertainty
uncertaintyBoth. Default
'hessian'('sandwich'with subject weights on julia). The method computed when the optimiser ends, as inctFitUncertainty. The default is for building a model, with the checks below beside it; for intervals to report, sample withctFitUncertainty(fit, 'sample').'sample'is refused here: useoptimize = FALSE, orctFitUncertainty(fit, 'sample')on the fit.checksJulia. Default
TRUE: the two checks a fit makes last, of the approximations its numbers rest on, asctFitUncertainty'schecksmakes them;FALSEfor neither, or one of'randomeffects'and'intervals'. The random-effects check, onintoverpop = 'laplace': every unit, whatever its number of effects, scored at draws of its random effects, and a warning where integrating them exactly would move an estimate by 0.1 standard errors or more, giving the move's size below one standard error (past that the check's linear step is no guide to it) and how far Laplace's log likelihood is from the integrated one, and namingctFitUncertainty(fit, intoverpop = 'quadrature')and joint sampling. Wherever it runs,fit$estimate$loglikis Laplace's plus the check's integral of every unit's error (loglik_seits standard error,loglik_laplacethe value the optimiser maximised,loglik_method'checked'). Every model whose effects enter linearly passes at once, and a fit whose optimiser stopped where a unit's Laplace term jumps warns instead, naming the units;fit$laplace$correctionrecords it. The interval check, withuncertainty = 'hessian':'checked''s check of the curvature's normal against the posterior's gradients, on the density the intervals come from, said in a message and insummary()where the posterior departs from that normal. Underintoverpop = 'quadrature'that density is the refined fit's, where the check can cost more than the refinement (seectFitUncertainty'schecks);checks = 'randomeffects'leaves it out. Neither runs withestonly.uncertaintyDraws,finishsamples,uncertaintyControlBoth.
ctOptimUncertainty'sdraws(default'auto'), andctFitUncertainty'sfinishsamples(1000) andcontrol.accuracy,sampleControlJulia. An accuracy in posterior standard deviations, off by default: once
uncertainty's method has run, its own account of its error is read against it, and where the method falls short, or has none, the fit is sampled to that accuracy (ctFitUncertainty'scontrol$accuracy);sampleControlholds the sampler's other settings for that run.estonlyBoth. Default FALSE. Point estimates only: no Hessian, so no standard errors and no certification; under
intoverpop = 'laplace'no Newton finish and no quadrature correction either.
Progress and output (julia)
callbackA function called while the fit runs, with
(iteration, total, objective, gradient_norm, parameters), whereparametersis the raw vector the objective and gradient describe; one declaring only the first four is called with four. It is called on a time cadence and once more at the end, for live progress in a front end;checkpointbelow writes a resumable checkpoint itself. An error inside it disables it with a warning.fit$optim$traceholds every iteration after the fit, andctTracePlotdraws it.checkpointA file path. While the fit optimises, its point is written there every
checkpoint_everyseconds (default 60) and at the end of each run, with each subject's random-effect modes on the Laplace route and the smoothing parameters of any smooth terms; each exact Hessian the fit forms is kept beside it (<checkpoint>.hessian). Where the file already exists, the fit starts from it: the same call again resumes an interrupted fit, its modes, smoothing parameters and Hessian included, which starting frominitsalone does not keep. A file written for a different model stops the fit rather than being overwritten.progressForce the progress line on or off.
tipredMissingHow missing TI predictor values are handled. Each gets a normal distribution from a regression on the other variables;
'impute'holds the value at its mean,'sample'makes it a parameter with that distribution as its prior, and'auto', the default, imputes when optimizing and samples when sampling. A sampled fit is placed with the values imputed.ctFitUncertainty(fit, 'sample')reads the fit's setting, and itscontrol$tipredMissingoverrides it.tipredMissingIncludeOutcomeDefault TRUE. Whether the outcome informs the imputation of missing TI predictors.
saveEffectsA sampling setting; read here for older scripts. Use
sampleControl$saveEffects.
Stan only
nsubsets,subsamplesize,lproughnesstarget,stochasticTolAdjust,parstepsTuning of stan's stochastic-gradient optimiser and its stepwise phase.
stalltolDefault 0.01. The gradient per data point above which stan calls a fit stalled and restarts it (see
stallretries).