Skip to contents

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

tol

Both. Stop when the objective changes by less than this. Default 1e-8 on stan, off on julia.

g_tol

Both. Stop when the l2 norm of the gradient falls below this. Default 1e-8 on julia, off on stan.

x_tol

Both. Stop when the parameter step falls below this. Off by default.

maxiter

Both. Iteration cap. Default 1000 on julia, mize's on stan.

lbfgs_scores

Julia. 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_local

Julia. 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_memory

Both. 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.

stallretries

Both. 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 stalltol per 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

initsd

Both. Default 0.01. The sd of the random start, on the raw scale.

datastart

Julia. 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 log1p and 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. Supplied inits are never overridden.

carefulfit

Both. 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 with priors = TRUE, which already has those priors, and when inits are 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$carefulfit records whether it ran.

The optimiser

stochastic

Both. 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_iterations records the phase.

gradient

Julia. 'adjoint' (reverse mode, the default) or 'forward'. The same gradient; the adjoint's cost does not grow with the number of parameters.

batch

Julia. Default TRUE, or FALSE when inits are 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; TRUE asks for it anyway.

coreset

Julia. 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. TRUE runs them whenever a coreset is expected to save gradients, FALSE never. fit$optim$coreset_sizes records the stages.

explosive_forward

Julia. 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_diagonal

Julia. 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_gll

Julia. Default 0. A step is accepted against the worst of the last W objective values (Grippo, Lampariello and Lucidi), so it may cross a curved valley.

lbfgs_nonmonotone

Julia. Between 0 (the default) and 1. A step is accepted against a running average of recent objective values (Zhang and Hager).

initial_alpha

Julia. Default 0.1. The length of the first trial step, in raw units.

precondition

Julia. 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.

saem

Julia, 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_guard records both. Not a better approximate estimate on its own – for that, sample with optimize = FALSE. A number caps its iterations (TRUE is 10000). fit$optim$saem_iterations, saem_settled, saem_trend, saem_chains, saem_acceptance and saem_trace record the phase.

saem_proposal

Julia. SAEM's proposal, 'rw' or 'laplace'.

restarts

Julia. 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 when cores > 1 and the fit took more than 30 seconds. Not when inits or maxiter were supplied. fit$optim$restarts records each start.

The finish and its certification (julia)

newton

Default 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 under intoverpop = 'laplace' where the exact Hessian would cost at least 200 gradients. fit$optim$newton_steps records the steps, and newton_krylov_products the gradients the Krylov steps took.

certify

Default TRUE. The curvature check that certifies a fit has converged. estonly skips it too.

gaptol

Default 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 of hessianreuse: close enough that the estimate's Hessian is the maximum's. A smaller value, such as 1e-6, holds the estimate closer still.

hessianreuse

Default 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.

innergaptol

What 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 to gaptol itself.

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, stallcooldown

The 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.

escapesaturated

Default FALSE. Refit a fit stalled on a saturated transform from a zeroed boundary, keeping whichever wins.

escapepin

Default 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_tol

Defaults 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 at 1e-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 in fit$laplace$soft_directions, and used by every function that rebuilds the objective; fit$laplace$conditioning counts such units. It applies too when sampling with intoverpop = FALSE and sampleControl$placement = 'fit'.

Uncertainty

uncertainty

Both. Default 'hessian' ('sandwich' with subject weights on julia). The method computed when the optimiser ends, as in ctFitUncertainty. The default is for building a model, with the checks below beside it; for intervals to report, sample with ctFitUncertainty(fit, 'sample'). 'sample' is refused here: use optimize = FALSE, or ctFitUncertainty(fit, 'sample') on the fit.

checks

Julia. Default TRUE: the two checks a fit makes last, of the approximations its numbers rest on, as ctFitUncertainty's checks makes them; FALSE for neither, or one of 'randomeffects' and 'intervals'. The random-effects check, on intoverpop = '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 naming ctFitUncertainty(fit, intoverpop = 'quadrature') and joint sampling. Wherever it runs, fit$estimate$loglik is Laplace's plus the check's integral of every unit's error (loglik_se its standard error, loglik_laplace the 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$correction records it. The interval check, with uncertainty = '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 in summary() where the posterior departs from that normal. Under intoverpop = 'quadrature' that density is the refined fit's, where the check can cost more than the refinement (see ctFitUncertainty's checks); checks = 'randomeffects' leaves it out. Neither runs with estonly.

uncertaintyDraws, finishsamples, uncertaintyControl

Both. ctOptimUncertainty's draws (default 'auto'), and ctFitUncertainty's finishsamples (1000) and control.

accuracy, sampleControl

Julia. 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's control$accuracy); sampleControl holds the sampler's other settings for that run.

estonly

Both. 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)

callback

A function called while the fit runs, with (iteration, total, objective, gradient_norm, parameters), where parameters is 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; checkpoint below writes a resumable checkpoint itself. An error inside it disables it with a warning. fit$optim$trace holds every iteration after the fit, and ctTracePlot draws it.

checkpoint

A file path. While the fit optimises, its point is written there every checkpoint_every seconds (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 from inits alone does not keep. A file written for a different model stops the fit rather than being overwritten.

progress

Force the progress line on or off.

tipredMissing

How 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 its control$tipredMissing overrides it.

tipredMissingIncludeOutcome

Default TRUE. Whether the outcome informs the imputation of missing TI predictors.

saveEffects

A sampling setting; read here for older scripts. Use sampleControl$saveEffects.

Stan only

nsubsets, subsamplesize, lproughnesstarget, stochasticTolAdjust, parsteps

Tuning of stan's stochastic-gradient optimiser and its stepwise phase.

stalltol

Default 0.01. The gradient per data point above which stan calls a fit stalled and restarts it (see stallretries).