Add a cycle, such as a daily rhythm, that drives a model's latent processes
Source:R/ctModelPeriodicComponent.R
ctModelPeriodicComponent.RdAdds a pair of latents, <name>_cos and <name>_sin, that turn
at a fixed period with no noise of their own – DRIFT[cos, sin]
= -2 pi / period and DRIFT[sin, cos] = 2 pi / period – so they
trace the cosine and sine of the time of day (or week, or whatever the
period is). Each latent in indices is driven by both, through
estimated effects DRIFT[k, <name>_cos] and DRIFT[k,
<name>_sin], so it is pushed through the cycle with an amplitude and phase
the data decide, and responds with its own dynamics: a fast process follows
the cycle closely, a slow one smooths and delays it.
Usage
ctModelPeriodicComponent(
ctm,
period,
indices = seq_len(ctm$n.latent),
name = "cycle",
individual = TRUE
)Arguments
- ctm
A model from
ctModel(type = 'ct').- period
The cycle's period, in the data's time units: 24 for a daily rhythm with time in hours.
- indices
Which latents the cycle drives, by position.
- name
Prefix for the added latents, predictors and parameters.
- individual
Let each subject's cycle deviate from the clock.
Details
The cycle is set to the clock at each subject's first observation, from
two time independent predictors, <name>_cos0 and <name>_sin0,
the cosine and sine of that time over the period, which
ctPeriodicPhases adds to the data. So the data's time must
count from an origin shared by every subject – hours since midnight of a
common day, say – for the cycle to mean the same clock time for all.
With individual = TRUE each subject's cycle may also be shifted from
the clock and differ in strength, by an initial deviation of the pair with
an estimated standard deviation, which the filter learns from each
subject's data: rhythms that differ between people, or a time origin that
is not shared, are then still modelled.
The effects start at zero, where they have a gradient: unlike a slow process, the cycle is known, so a refit from the model without it needs no particular start.
Needs the julia backend, which reads time independent predictors in the initial means.
See also
ctPeriodicPhases for the predictors it reads;
ctFitAdequacy's periodic family, which finds cycles a
model lacks; ctModelImprove, which adds one where that
family points.
Examples
m <- ctModel(type = 'ct', manifestNames = c('Y1', 'Y2'),
latentNames = c('eta1', 'eta2'), LAMBDA = diag(2))
m2 <- ctModelPeriodicComponent(m, period = 24)
m2$latentNames
m2$TIpredNames
p <- m2$pars
p[p$matrix %in% 'DRIFT' & (p$row > 2 | p$col > 2) &
(!is.na(p$param) | p$value != 0), c('matrix', 'row', 'col', 'param', 'value')]