Skip to contents

intoverpop = '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 θ\theta; each model matrix cell is a function of one raw value through that parameter’s transform. When parameters vary across individuals, subject ii gets its own raw vector rather than its own model:

vi=θ+∑lLlubl(i),u∼N(0,I)v_i \;=\; \theta \;+\; \sum_{l} L_l\, u_{b_l(i)}, \qquad u \sim N(0, I)

Here ll indexes the levels of the hierarchy, bl(i)b_l(i) is the group that subject ii belongs to at level ll (itself at the subject level, its study at the study level), and LlL_l 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 uu is standard normal by construction, everything about the spread of individual differences lives in LlL_l — which is what popsd and rawpopcorr report.

Two ways to remove u

The likelihood we want is the marginal one, with uu integrated out. ctsem has two ways to do that.

Augmentation (intoverpop = 'augmented') appends uu 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 nn latent processes to n+kn + k, where kk 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 nn and approximates the integral instead. For a group of members UU that share a random effect,

T(θ)=log⁡∫exp⁡(∑m∈Uℓm(vm)−12u′u)du−d2log⁡2πT(\theta) \;=\; \log \int \exp\Big( \textstyle\sum_{m \in U} \ell_m(v_m) - \tfrac{1}{2}u'u \Big)\, du \;-\; \tfrac{d}{2}\log 2\pi

is approximated by expanding the exponent about its mode û\hat u:

T(θ)≈∑m∈Uℓm(vm(θ,û))−12û′û−12log⁡det⁡M,M=I−AT(\theta) \;\approx\; \sum_{m \in U} \ell_m\big(v_m(\theta, \hat u)\big) \;-\; \tfrac{1}{2}\hat u'\hat u \;-\; \tfrac{1}{2}\log\det M, \qquad M = I - A

where AA is the Hessian of ∑mℓm\sum_m \ell_m with respect to uu at the mode. The identity in MM 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 θ\theta alone, and the outer gradient with respect to θ\theta 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 uu, 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 −0.4-0.4, 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.54976311

Note 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:

m <- ctModel(type = 'ct', id = c('id', 'study'),
  manifestNames = 'Y1', latentNames = 'eta1', LAMBDA = matrix(1),
  T0MEANS = matrix('T0m_eta1||id'), CINT = matrix('cint_eta1'),
  MANIFESTMEANS = matrix(0))

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 −CINT/DRIFT-\text{CINT}/\text{DRIFT} 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 0.40.4 and 0.50.5:

s <- summary(fit)
rbind(
  estimated = c(id = s$popsd.id['cint_eta1', 'mean'],
                study = s$popsd.study['cint_eta1', 'mean']),
  truth = c(id = sd_sub_cint, study = sd_study_cint))
#>              id study
#> estimated 0.411 0.699
#> truth     0.400 0.500

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:

str(lapply(summary(fit)$randomEffects, function(z)
  list(level = z$level, popsd = colnames(z$popsd))))
#> List of 2
#>  $ :List of 2
#>   ..$ level: chr "id"
#>   ..$ popsd: chr [1:2] "T0m_eta1" "cint_eta1"
#>  $ :List of 2
#>   ..$ level: chr "study"
#>   ..$ popsd: chr "cint_eta1"

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

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

c(cint = cor(sp[1, , 'cint_eta1'], truth$cint),
  T0means = cor(sp[1, , 'T0m_eta1'], truth$t0))
#>      cint   T0means 
#> 0.9687434 0.9503230

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:

k <- ctPredict(fit, subjects = c(1, 7, 13), timestep = .25,
  timerange = c(0, 9))
plot(k)

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

Under '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 tt can be built from only the data up to tt. 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 tt that has not seen tt — 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.803

Practical 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 ±1\pm 1 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