Skip to contents

Splits the variance each indicator of a fitted model implies into a between person part, a within person part from the latent process, and a within person part from measurement error – with the process part further split into what the system noise contributes and what the mean path moving contributes.

Usage

ctVarianceDecomposition(
  fit,
  method = c("auto", "moment", "simulation"),
  persons = c("auto", "model", "estimated"),
  scale = c("latent", "response"),
  times = NULL,
  npersons = 200L,
  npaths = 20L,
  latents = TRUE,
  quadpoints = 21L,
  subjects = "all",
  realid = TRUE,
  sources = NULL
)

Arguments

fit

fit object as generated by ctFit, from either backend.

method

How the model implied moments are obtained. 'moment' runs the forward moment recursion, which is exact and needs the dynamics to be linear. 'simulation' draws trajectories from the julia engine instead, which is what a model with state dependent DRIFT or DIFFUSION cells needs. 'auto', the default, is 'moment' unless the model has such cells.

persons

Which population the between person variance refers to. 'model' draws persons from the fitted population distribution of the random effects, which is the model's own claim about the population and is not shrunk. 'estimated' uses the subjects in the data, which describes this sample: on a backend='julia' fit each at plausible values – its estimated effects plus a draw from their posterior given its data – which are not shrunk either; on a stan fit at their estimated (empirical Bayes) matrices, which attenuates the between person variance. 'auto', the default, is 'model' for a backend='julia' fit and 'estimated' for a stan one, saying which it used – only the julia engine can materialise the model matrices at a drawn set of random effects.

scale

For a binary or ordinal indicator, whether to decompose the linear predictor behind the logit ('latent', the default, with a measurement variance of \(\pi^2/3\)) or the observed response ('response', integrating the link over each row's own normal marginal). The two coincide for a Gaussian indicator.

times

If given, decompose at each of these times rather than averaging over the window: a numeric vector, or 'asdata' for the observed occasions. Every person is evaluated on the one grid, which is what makes a variance across persons at a given time mean anything. The result gains a time column and loses within.deterministic – that term is the variance of the mean path over time, so it exists only in the average. Not available with method='simulation' or with time dependent predictors, neither of which has values on a grid of its own.

npersons

Number of persons to draw when persons='model'. With persons='estimated' on a julia fit, each subject gets as many plausible values as make at least this many persons in all.

npaths

Trajectories drawn per person when method='simulation'. Each person needs several: with one path, the average over that person's rows wanders with the path rather than estimating their mean, and the wander lands in the between person term. The two Monte Carlo corrections this makes necessary are applied, so the result is unbiased at any npaths, but small values are noisy.

latents

If TRUE, also decompose the latent processes, which have no measurement component.

quadpoints

Gauss-Hermite nodes used when scale='response'.

subjects

'all', or the subjects whose designs the decomposition is computed over, as ids in the data (see realid).

realid

If TRUE (the default), subjects are read as the ids in the data, and integers that are not ids there are read as ctsem's numbering of the subjects, 1 to N, with a message. If FALSE, they are read as that numbering.

sources

Optional named list of latent names, one entry per group of processes whose innovations are independent of the other groups' – fast affect, a day-scale tier, a slow tier, say. The stochastic within person term is then split by where it came from: within.stochastic.<group> for each group's innovations and within.stochastic.initial for the initial state's variance still present, which add up to within.stochastic. Averaged over the window, level.<group> is the part of each that is the variance of the record's own mean: a process as slow as the record is long acts within it mostly as a level, and this says how much. Needs method='moment'.

Value

A data frame of class ctVarianceDecomposition, one row per variable, with columns variable, type, between, within.deterministic, within.stochastic, within.measurement, within, total and the corresponding proportions. The population the between column refers to, the scale, and the number of persons are recorded as attributes and shown by print.

Details

The decomposition is a nested law of total variance over the population of (person, occasion) pairs at the design the fit was built on. With \(g = E[y | \eta]\) the model's expected observation given the latent state,

$$Var(y) = E[Var(y|\eta)] + E_i E_t Var(g) + E_i Var_t(E[g]) + Var_i(E[g])$$

whose four terms are the four columns reported. They are non-negative and sum to the total exactly.

within.deterministic is where non-stationarity appears: it is the variance of a person's own mean path over their observation times, so it is zero for a stationary process with no time dependent predictors and positive when there is a trend, a predictor driven shift, or a process still relaxing from its starting distribution.

The moments come from the forward recursion over each subject's actual observation times, with no data entering, so unequal spacing, missingness and time dependent predictors are handled exactly rather than by assuming stationarity. The result is exact for a model with linear dynamics.

A model whose DRIFT or DIFFUSION cells depend on the state has no single transition to run that recursion with, so method='simulation' draws its trajectories from the engine and takes the same decomposition over the draws. It is refused rather than linearised at a point nothing chose. A state dependent measurement cell – LAMBDA, MANIFESTMEANS, MANIFESTVAR – is refused by both routes, since turning a drawn state into an expected observation then needs the measurement model re-materialised at every row.

Random effect levels. A model with a grouping level above the subject (id = c('subject','study') in ctModel) is fitted with intoverpop='laplace' – or sampled, which prepares the same description and is handled the same way here – and gets one between.<level> column per level, each the variance of that level's own departure from the level outside it. They are orthogonal by construction and sum to between.

Each level's fitted modes are shrunk toward the level outside them by an amount that follows the information per unit rather than the number of units: on a 6-study, 30-subject example the subject level's modes retained 52 per cent of the population standard deviation (ten occasions each) while the study level's retained 97 per cent (five subjects each). persons='estimated' therefore adds to each mode a draw from that unit's posterior, drawn jointly over its levels: the spread of such plausible values is the population's, where the spread of the modes is not. persons='model' draws from each level's own fitted covariance instead, and is the default.

When the split changes over the window. The columns above are averages over each person's occasions, and for a process that has not settled they average a split that is genuinely different at different times. within.deterministic is the flag that this is happening – it is the mean path moving – and times= is how to look. On a fixture whose T0MEANS is fixed, so that every person starts in the same place, the between person share of an indicator's variance runs from zero at the first occasion to 20 per cent by the twentieth, against a window average of 17 per cent that describes no occasion in particular.

Designs. Nothing here assumes a balanced one. Each person is evaluated over their own observation times, so everyone measured at the same occasions, everyone at their own, and subjects with different numbers of occasions all work, as does an observation being missing – a row still has a model implied distribution whether or not its indicator was seen, so every design row counts and the answer does not move with the missingness pattern. Persons are weighted equally rather than by row count: the estimand is over persons, so a frequently measured subject should not be a larger share of the population than a rarely measured one.

method='simulation' checks, by generating twice, that the engine draws a model's individually varying parameters rather than leaving every simulated person at the population values, and refuses rather than returning a between person variance of zero if it does not.

See also

ctSummaryMatrices for the matrices this is built from, and ctStateDependencePlot for a model whose dynamics vary over the state space.

Examples

# \donttest{
ctVarianceDecomposition(ctstantestfit)
# }