Multilevel random effects by Laplace approximation
Source:vignettes/laplace-multilevel.qmd
laplace-multilevel.Rmdintoverpop = 'laplace' integrates individual differences
in parameters out of the likelihood by a Laplace approximation, instead
of carrying them as extra latent states. It accepts a vector of
id columns, so subjects can be nested in studies, sites, or classrooms,
with random effects declared at each level.
This vignette covers what the approximation is, how to specify and fit such a model, and how to read, plot and extract from the result. It requires the Julia backend.
The model
Where random effects live
ctsem works internally on a raw, unconstrained parameter vector ; each model matrix cell is a function of one raw value through that parameter’s transform. When parameters vary across individuals, subject gets its own raw vector rather than its own model:
Here indexes the levels of the hierarchy, is the group that subject belongs to at level (itself at the subject level, its study at the study level), and is the Cholesky factor of that level’s population covariance, built from raw standard-deviation and correlation parameters. The shifts are additive on the raw scale and are applied before the transforms, so a subject’s parameter and the population parameter are always on the same scale.
Because
is standard normal by construction, everything about the spread of
individual differences lives in
— which is what popsd and rawpopcorr
report.
Two ways to remove
The likelihood we want is the marginal one, with integrated out. ctsem has two ways to do that.
Augmentation (intoverpop = 'augmented')
appends
to the latent state with no drift and no diffusion, so the Kalman filter
carries it along and integrates it as a by-product of filtering. It is
exact for a linear-Gaussian model and needs no new machinery. The cost
is that every subject’s filtered system grows from
latent processes to
,
where
is the number of varying parameters, and the filter’s linear algebra is
cubic in that dimension.
Laplace (intoverpop = 'laplace') leaves
every subject’s system at
and approximates the integral instead. For a group of members
that share a random effect,
is approximated by expanding the exponent about its mode :
where is the Hessian of with respect to at the mode. The identity in is the standard normal prior’s own curvature.
The mode is found by an inner Newton solve, started from zero at every evaluation so that the objective depends on alone, and the outer gradient with respect to is exact — the approximation is in the integral, not in its derivatives.
What is exact and what is not
When a random effect enters the state mean linearly through an
identity transform in a linear-Gaussian model, the integrand is exactly
Gaussian in
,
and Laplace is not an approximation at all — it reproduces the
closed-form integral. T0MEANS, CINT and
MANIFESTMEANS are identity-transformed by default, so a
model like the one below is in that regime.
It is genuinely approximate when the effect enters through a
nonlinear transform (DRIFT, DIFFUSION, and any
state-dependent parameter), and the approximation is better the more
informative each subject’s data is about its own effects.
ctFit() measures that error itself and corrects for it
by default (optimcontrol$laplace_correct): it recomputes
each unit’s integral by adaptive Gauss-Hermite quadrature, and wherever
the two disagree it continues the fit on the quadrature objective,
reporting the quadrature log likelihood; print(fit) says
when the estimate moved. ctLaplaceCheck() reports the same
measurement on any Laplace fit, as how far the estimate would move if
the integral were taken exactly. Read delta_se: well below
one says the approximation is not what limits the answer, and near or
above one says it is. Read dropped_directions alongside it
rather than on its own — a direction the data does not identify well
enough to correct along is also reported as a zero correction, and the
two look the same in delta_se even though one means “fine”
and the other means “not estimable here”.
ctFitUncertainty(fit, 'is', control = list(likelihood = 'quadrature'))
importance samples against the quadrature posterior, correcting the
shape of the intervals as well as their centre.
The correction moves the estimate and its curvature; the intervals
are still a normal approximation at a mode, which understates the skew a
population standard deviation estimated from few groups has. For the
exact posterior, ctFitUncertainty(fit, 'sample') samples
the parameters and every unit’s random effects jointly, with the Laplace
fit only as a starting point; a short run is often enough to improve on
the normal approximation (vignette('uncertainty')).
Nesting
Subjects in the same study share that study’s random effect, so their likelihood contributions do not factorise and they cannot be integrated separately. The unit of integration is therefore the outermost group: one study, with all of its subjects, is integrated jointly.
That would be expensive done naively — the integral for a study of 100 subjects with 2 subject effects and 1 study effect is 201-dimensional. It is cheap because the curvature has an arrow structure: each subject’s block couples to its study and to nothing else. ctsem assembles, factorises and inverts that structure block by block, so the cost is linear in the number of subjects rather than cubic.
A worked example
Simulating
Thirty subjects in five studies, ten occasions each. A univariate
Ornstein-Uhlenbeck process where subjects differ in their starting level
(T0MEANS) and in their equilibrium (CINT), the
two correlated
,
and where studies additionally differ in average equilibrium.
set.seed(4)
nstudy <- 5; npersub <- 6; nobs <- 10
mu_cint <- 0.3; drift <- -0.4; diffusion <- 0.6; merror <- 0.2
sd_study_cint <- 0.5
sd_sub_cint <- 0.4; sd_sub_t0 <- 0.8; rho <- -0.4
gm <- ctModel(type = 'ct', id = c('id', 'study'),
manifestNames = 'Y1', latentNames = 'eta1', LAMBDA = matrix(1),
T0MEANS = matrix('t0||id'), CINT = matrix('cint||TRUE'), DRIFT = matrix(drift),
DIFFUSION = matrix(diffusion), MANIFESTVAR = matrix(merror),
MANIFESTMEANS = matrix(0), T0VAR = matrix(0))
# The population covariances, on the raw scale: T0MEANS and CINT are 10 times
# their raw parameter, so a covariance is a hundredth of its natural value and
# an sd a tenth.
S <- matrix(c(sd_sub_t0^2, rho * sd_sub_t0 * sd_sub_cint,
rho * sd_sub_t0 * sd_sub_cint, sd_sub_cint^2), 2, 2,
dimnames = list(c('t0', 'cint'), c('t0', 'cint')))
gm$RAWPOPVAR <- ctCov(S / 100)
gm$RAWPOPVAR_study['cint', 'cint'] <- sd_study_cint / 10
dat <- ctGenerate(gm, n = c(nstudy * npersub, nstudy), Tpoints = nobs,
backend = 'julia', values = c(t0 = 0, cint = mu_cint))
# What each subject and each study was generated with.
truth <- attr(dat, 'subjectpars')
studytruth <- attr(dat, 'grouppars')$study
dat <- data.frame(dat)
head(dat)
#> id time study Y1
#> 1 1 0 1 0.18088584
#> 2 1 1 1 -0.06810343
#> 3 1 2 1 1.11520843
#> 4 1 3 1 1.47879448
#> 5 1 4 1 1.15850314
#> 6 1 5 1 1.54976311Note that study is an ordinary column of the long data
frame, constant within subject. Nesting is read from the data, not
declared separately.
Specifying the hierarchy
Pass id a vector, innermost first:
CINT is fixed to zero by default in ctsem, with the
level carried by MANIFESTMEANS. Here it is freed and
MANIFESTMEANS fixed instead, so that the process has a
genuine equilibrium at
for individual differences to act on.
A cell’s indvarying field says at which levels its
parameter varies: TRUE at every level, FALSE
at none, or the levels by name. Intercepts left unspecified vary at
every level, so cint_eta1 varies both between subjects and
between studies, which is what makes its variance decompose into a
within-study and a between-study part. 'T0m_eta1||id' lets
the starting level vary between subjects only;
'cint_eta1||study' would vary between studies only, with
subjects exchangeable within a study. The same field can be written by
name, 'T0m_eta1, indvarying=id', or built with
ctPar('T0m_eta1', indvarying = 'id'). Printing the model
says what varies where, and what each level will estimate:
print(m, matrices = FALSE)
#> ctsem model (continuous time)
#> 1 latent (eta1), 1 manifest (Y1)
#> grouping above subject: study
#>
#> 5 free parameters
#>
#> Varying parameters, by level:
#> id T0m_eta1, cint_eta1
#> study cint_eta1
#> Each level estimates a population covariance over its own parameters:
#> 2 standard deviations and 1 correlation (id), 1 standard deviation (study), on top of the 5 above.
#> Set the levels with indvarying, in a cell or in pars$indvarying: TRUE, FALSE or level names (see ?ctPar).
#>
#> Matrices not shown; see model$matrices or ctModelMatrices(model).m$pars$indvarying holds the same values, one per cell,
and can be edited directly – TRUE, FALSE or
level names, as in a cell. A cell’s sdscale scales the
prior on the standard deviation at every level it varies at. Levels must
be strictly nested: every subject belongs to exactly
one study. ctsem checks this and stops if the data say otherwise.
Fitting
fit <- ctFit(dat, m, backend = 'julia', intoverpop = 'laplace', cores = 4)cores threads the loop over integration units, which are
studies here. Everything else is as usual:
intoverpop = 'laplace' requires
backend = 'julia'. With optimize = FALSE the
same model is sampled instead, the random effects drawn with the
parameters, and the Laplace approximation plays no part in the
result.
Reading the output
summary(fit)
#>
#> Standardised residual covariance
#> --------------------------------
#> Y1
#> Y1 0.15
#> Note: on each subject's random effects estimated from their whole record, so
#> these are smoothed rather than filtered residuals
#>
#> Random-effects correlations (id)
#> --------------------------------
#> mean sd 2.5% 50% 97.5% mode
#> cint_eta1__T0m_eta1 -0.5 0.188 -0.805 -0.518 -0.086 -0.509
#>
#> System Matrices
#> ---------------
#> matrix row col Mean sd 2.5% 50% 97.5%
#> 2 T0MEANS 1 1 0.350 0.124 0.115 0.346 0.589
#> 3 LAMBDA 1 1 1.000 0.000 1.000 1.000 1.000
#> 4 DRIFT 1 1 -0.502 0.089 -0.700 -0.496 -0.347
#> 6 MANIFESTMEANS 1 1 0.000 0.000 0.000 0.000 0.000
#> 7 CINT 1 1 0.470 0.368 -0.230 0.465 1.182
#> 9 asymCINT 1 1 0.941 0.752 -0.471 0.927 2.413
#> 10 asymDIFFUSIONcov 1 1 0.490 0.079 0.356 0.483 0.660
#> 11 DIFFUSIONcov 1 1 0.480 0.049 0.392 0.478 0.583
#> 12 MANIFESTcov 1 1 0.000 0.000 0.000 0.000 0.000
#> 13 T0cov 1 1 0.000 0.000 0.000 0.000 0.000
#> 14 dtDRIFT 1 1 0.608 0.053 0.497 0.609 0.707
#>
#> Random-effects standard deviations (id)
#> ---------------------------------------
#> mean sd 2.5% 50% 97.5% mode
#> T0m_eta1 0.709 0.096 0.539 0.706 0.914 0.674
#> cint_eta1 0.411 0.104 0.248 0.400 0.652 0.409
#>
#> Random-effects standard deviations (study)
#> ------------------------------------------
#> mean sd 2.5% 50% 97.5% mode
#> cint_eta1 0.699 0.309 0.267 0.642 1.42 0.552
#>
#> Fixed-effects / Population means
#> --------------------------------
#> mean sd 2.5% 50% 97.5% mode
#> T0m_eta1 0.350 0.124 0.115 0.346 0.589 0.345
#> drift_eta1 -0.502 0.089 -0.700 -0.496 -0.347 -0.508
#> diff_eta1 0.692 0.035 0.626 0.691 0.764 0.689
#> mvarY1 0.000 0.000 0.000 0.000 0.000 0.000
#> cint_eta1 0.470 0.368 -0.230 0.465 1.182 0.467
#>
#> Note: Population values on the transformed scale. Covariance parameters appear
#> in sd / unconstrained correlation form; see System Matrices (or
#> ctSummaryMatrices()) for cor/cov. mode is the fit's estimate, the other
#> columns its posterior draws.
#> ------------------------------------------------------------------------
#> Units: 30 id within 5 study
#> Log posterior: -274.381
#> Number of parameters: 9
#> AIC: 566.763
#>
#> Convergence: Predicted objective still available at this estimate: 7e-09 (joint
#> displacement 0.000118 in the information metric). Status:
#> certified. Exact value: fit$uncertainty$certification$gap.
#> ------------------------------------------------------------------------
#> Uncertainty draws: 1000
#>
#> Note: Julia backend; intervals from ctFitUncertainty(uncertainty='checked')
#> draws pushed through the transforms.
#> ------------------------------------------------------------------------The parts specific to a hierarchy:
Random-effects standard deviations (id)
and (study) are the spread of the random
effects at each level, on the transformed parameter scale. With more
than one level, nothing is reported in an unlabelled block — a bare
table would leave it ambiguous whether it described spread between
subjects or between studies.
Read together they are a variance decomposition.
cint_eta1 appears at both levels, so its total individual
variation splits into a within-study part and a between-study part,
against generating values of
and
:
Random-effects correlations (id) are
correlations between random effects on the raw, untransformed
scale — the correlation ctsem parameterises, not a correlation of
the transformed parameters. For identity-transformed parameters like
these the two coincide; for DRIFT or DIFFUSION
they do not. The study level has only one effect here, so it has no
correlation table.
Fixed-effects / Population means are
the population values, i.e. the parameters before any subject’s shift is
added.
For programmatic use, summary(fit)$randomEffects holds
the same quantities per level, as raw draws rather than as
summaries:
Per-subject parameters
ctSubjectPars() returns each subject’s own parameter
values — population value, plus its random effects at every level it
belongs to, plus any time-independent predictor effects — pushed through
the model’s transforms:
sp <- ctSubjectPars(fit)
dim(sp)
#> [1] 1 30 2
round(head(sp[1, , ], 4), 3)
#> param
#> subject cint_eta1 T0m_eta1
#> 1 0.778 0.181
#> 2 1.195 0.243
#> 3 0.277 0.288
#> 4 1.719 -0.395The array is draws x subjects x parameters. On a Laplace
fit there is one draw: these are the conditional modes at the estimated
population parameters, a point estimate rather than a posterior. Getting
draws would mean re-solving every subject’s inner mode at every draw,
which is a real computation rather than a lookup.
Against the values that generated the data:
Because cint_eta1 varies at both levels, its subject
estimates carry the study structure. Each study’s own value – the
population value shifted by that study’s effect, with no subject’s on
top – is level = 'study':
st <- ctSubjectPars(fit, level = 'study')
round(rbind(estimated = st[1, , 'cint_eta1'], truth = studytruth$cint), 3)
#> 1 2 3 4 5
#> estimated 0.930 0.372 -0.195 0.027 1.199
#> truth 0.746 0.385 -0.164 0.391 1.285
d <- data.frame(cint = sp[1, , 'cint_eta1'], study = factor(truth$study))
ggplot(d, aes(x = study, y = cint, colour = study)) +
geom_hline(yintercept = mean(d$cint), linetype = 'dashed', colour = 'grey50') +
geom_point(position = position_jitter(width = .12, height = 0), size = 2) +
stat_summary(fun = mean, geom = 'crossbar', width = .5, colour = 'black') +
labs(y = 'subject CINT', title = 'Subject equilibria, grouped by study') +
theme_bw() + theme(legend.position = 'none')
The spread of the black study means around the dashed grand mean is the between-study variation; the scatter within each study is the within-study variation.
Trajectories
ctPredict() and ctKalman() work as they do
for any other fit:
Choosing which levels enter the trajectory
randomEffects selects which levels the trajectory is
built from. Naming an id column includes that level and every level
outside it, so:
-
'id'(the default, the innermost id) gives each subject its own trajectory; -
'study'gives the study mean, shared by every subject in a study; -
'population'includes none, giving the trajectory implied by the population parameters alone.
The effect is clearest in the expectation at each subject’s first observation, which is driven by the parameters rather than by data:
subs <- c(1, 7, 13, 19, 25) # one from each study
sapply(c('id', 'study', 'population'), function(lev) {
p <- ctPredict(fit, subjects = subs, timestep = .5, timerange = c(0, 9),
randomEffects = lev)
round(p$value[p$Element %in% 'yprior' & p$Time == 0], 3)
})
#> id study population
#> [1,] 0.181 0.345 0.345
#> [2,] -0.149 0.345 0.345
#> [3,] 0.803 0.345 0.345
#> [4,] -0.390 0.345 0.345
#> [5,] -0.224 0.345 0.345Under 'id' each subject starts at its own estimated
T0MEANS. Under 'study' and
'population' they all start at the same place, because
T0MEANS varies only at the subject level here — the study
effect is on CINT, so it acts on where the trajectories go,
not on where they begin.
The smoothing caveat
A Laplace fit warns, once per call, that its trajectories are the smoothed equivalent. This is worth understanding rather than dismissing.
In an augmented fit the random effects are latent states, so the
filter updates them observation by observation, and a trajectory at time
can be built from only the data up to
.
Under Laplace they are conditional modes estimated from each subject’s
whole record. There is no version of them from before a subject’s later
data arrived, so even yprior is conditional on the complete
series. Comparisons that depend on genuine out-of-sample filtering — a
prediction at
that has not seen
— are not what these give.
What the modes are not is recomputed. They are the ones the
fit arrived at, against the data the fit saw, and they stay fixed
however a prediction call changes the rows being filtered — selecting
subjects, interpolating onto a time grid, or withholding observations
with removeObs. So a prediction with every observation
withheld still uses that subject’s own random effects, which is what
makes it a prediction for that subject rather than for the
average one:
firstrow <- function(...) {
k <- ctPredict(fit, subjects = c(1, 7, 13), ...)
v <- k[k$Element %in% 'yprior', ]
v <- v[order(v$Subject, v$Time), ]
round(unlist(lapply(split(v, v$Subject), function(d) d$value[1])), 3)
}
rbind(
`as observed` = firstrow(timestep = 'asdata'),
interpolated = firstrow(timestep = .5, timerange = c(0, 9)),
`no data` = firstrow(timestep = .5, timerange = c(0, 9), removeObs = TRUE))
#> 1 7 13
#> as observed 0.181 -0.149 0.803
#> interpolated 0.181 -0.149 0.803
#> no data 0.181 -0.149 0.803Practical notes
How many groups at the outer level. A level’s
standard deviation is estimated from the number of groups at
that level, not the number of subjects. Five studies is few, and the
interval on popsd.study above is correspondingly wide. With
very few groups the correlation parameters can be driven to the
boundary; ctsem caps them just short of
and reports that it has done so rather than failing.
Priors are available at every level and are the standard remedy when an outer level is weakly identified.
Choosing between them.
intoverpop = TRUE, and the default 'auto' when
optimizing, take Laplace on the julia backend. It integrates random
effects that shift a mean in a linear Gaussian model exactly, inside
each subject’s filter, as augmentation would, and every other effect by
the Laplace approximation; it is the only option for nesting beyond the
subject level. Name augmentation explicitly for an effect the filter
does not take – one random parameter shared by several cells, say –
where its carrier state is cheaper than a Laplace coordinate.
Time-independent predictors work at any level, provided the predictor actually varies at that level.
Session
sessionInfo()
#> R version 4.6.0 (2026-04-24 ucrt)
#> Platform: x86_64-w64-mingw32/x64
#> Running under: Windows 11 x64 (build 26300)
#>
#> Matrix products: default
#> LAPACK version 3.12.1
#>
#> locale:
#> [1] LC_COLLATE=English_Australia.utf8 LC_CTYPE=English_Australia.utf8
#> [3] LC_MONETARY=English_Australia.utf8 LC_NUMERIC=C
#> [5] LC_TIME=English_Australia.utf8
#>
#> time zone: Europe/Zurich
#> tzcode source: internal
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] ggplot2_4.0.3 ctsem_4.0.0 Rcpp_1.1.2
#>
#> loaded via a namespace (and not attached):
#> [1] generics_0.1.4 lattice_0.23-1 digest_0.6.39
#> [4] magrittr_2.0.5 evaluate_1.0.5 grid_4.6.0
#> [7] RColorBrewer_1.1-3 fastmap_1.2.0 plyr_1.8.9
#> [10] jsonlite_2.0.0 Matrix_1.7-6 pkgbuild_1.4.8
#> [13] ps_1.9.3 gridExtra_2.3.1 QuickJSR_1.11.0
#> [16] scales_1.4.0 codetools_0.2-20 cli_3.6.6
#> [19] rlang_1.3.0 expm_1.0-1 parallelly_1.48.0
#> [22] splines_4.6.0 withr_3.0.3 yaml_2.3.12
#> [25] otel_0.2.0 StanHeaders_2.39.1 tools_4.6.0
#> [28] rstan_2.32.7 inline_0.3.21 parallel_4.6.0
#> [31] rstantools_2.7.1 JuliaConnectoR_1.1.6 dplyr_1.2.1
#> [34] cOde_1.1.1 Deriv_4.3.5 curl_8.0.0
#> [37] vctrs_0.7.3 R6_2.6.1 matrixStats_1.5.0
#> [40] stats4_4.6.0 lifecycle_1.0.5 V8_8.2.0
#> [43] pkgconfig_2.0.3 RcppParallel_6.2.1 pillar_1.11.1
#> [46] gtable_0.3.6 loo_2.10.1 data.table_1.18.6.1
#> [49] glue_1.8.1 xfun_0.60 tibble_3.3.1
#> [52] tidyselect_1.2.1 knitr_1.52 farver_2.1.2
#> [55] htmltools_0.5.9 labeling_0.4.3 rmarkdown_2.32
#> [58] compiler_4.6.0 S7_0.2.2 mize_0.2.5