Outputs predicted, updated, and smoothed estimates of manifest indicators and latent states,
with covariances, for specific subjects from data fit with ctFit,
based on either the mode (if optimized) or mean (if sampled) of parameter distribution.
ctKalman is an alias for this function and returns the same long data
frame. The pre-3.11 name ctStanKalman is not its Stan-prefixed twin:
that is an alias for ctKalmanArray, which returns a list of
arrays instead.
Usage
ctPredict(
fit,
timerange = "asdata",
timestep = "auto",
subjects = NULL,
removeObs = FALSE,
plot = FALSE,
standardisederrors = FALSE,
realid = TRUE,
randomEffects = NULL,
newdata = NULL,
...
)Arguments
- fit
fit object as generated by
ctFit.- timerange
Either 'asdata' to just use the observed data range, or a numeric vector of length 2 denoting start and end of time range, allowing for estimates outside the range of observed data. Ranges smaller than the observed data are ignored.
- timestep
Either 'asdata' to just use the observed data (which also requires 'asdata' for timerange) or a positive numeric value indicating the time step to use for interpolating values. Lower values give a more accurate / smooth representation, but take a little more time to calculate.
- subjects
subject ids to predict for, or NULL (the default) for the first subject in the data, or every subject in
newdatawhen that is given. Withrealid=FALSE, integers denoting subjects from 1 to N.- removeObs
Logical or integer. If TRUE, observations (but not covariates) are withheld from the filter, so only expectations based on parameters and covariates are returned (the observations themselves are still reported, for comparison). If a positive integer N, every N observations are retained while others are withheld – useful for observing prediction performance forward further in time than one observation.
- plot
Logical. If TRUE, plots output instead of returning it. See
plot.ctKalmanDF(Stan based fit) for the possible arguments.- standardisederrors
if TRUE, also include standardised error output (based on covariance per time point).
- 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.
- randomEffects
For an
intoverpop='laplace'fit, which levels of random effect the trajectories are built from. Naming one of the model's id columns includes that level and every level outside it, so the innermost id gives each subject its own trajectory and an outer id gives the group mean, shared by every subject in the group.'population'includes none, giving the trajectory implied by the population parameters alone. Defaults to the innermost id. Ignored for other fits.With one level of random effects, left in, each subject's predicted and updated values take its random effects at their posterior given its rows up to each time, and its smoothed values at their mode given its whole record. Otherwise every pass takes the modes from each subject's whole record. Those whole-record modes stay the fit's however this call changes the rows being filtered (selecting subjects, a time grid,
removeObs), so with every observation withheld the smoothed values still use that subject's own random effects.- newdata
Optional long format data to predict for instead of the data the model was fitted to, with the same columns: an id, a time, the manifest variables (
NAwhere nothing is observed) and the predictors. New subjects, such as hypothetical people with chosen covariate values; a subject of the fit under other covariate values; or a record cut short at some time, to see what was predictable then. The data are put under the model the fit ran, with its estimates as they stand: nothing is refitted, and the model keeps its structure whatever the number of subjects. A subject's predicted (prior) and updated values condition on its rows innewdataup to each time, and its smoothed values on all of them. For a fit with random effects that includes the subject's random effects, at their posterior given those rows (for a Laplace fit with one level of random effects; otherwise asrandomEffectsdescribes), so a subject with no observations gets the population's prediction for its covariate values. A row at a time with nothing observed gives a prediction there; a time dependent predictor leftNAis taken as zero, asctFittakes it.- ...
additional arguments to pass to
plot.ctKalmanDF.
Value
Returns a list containing matrix objects etaprior, etaupd, etasmooth, y, yprior,
yupd, ysmooth, errprior, errupd, errsmooth, time, loglik, with values for each time point in each row.
eta refers to latent states and y to manifest indicators - y itself is thus just
the input data. With standardisederrors=TRUE, standardised versions
errstdprior, errstdupd, errstdsmooth are included too.
Covariance matrices etapriorcov, etaupdcov, etasmoothcov, ypriorcov, yupdcov, ysmoothcov,
are returned in a row * column * time array.
Some outputs are unavailable for ctStan fits at present.
If plot=TRUE, nothing is returned but a plot is generated.
Examples
# \donttest{
#Basic
ctPredict(ctstantestfit, timerange=c(0,60), plot=TRUE)
#Multiple subjects, y and yprior, showing plot arguments
plot1<-ctPredict(ctstantestfit, timerange=c(0,60), timestep=.1, plot=TRUE,
subjects=2:3,
kalmanvec=c('y','yprior'),
errorvec=c(NA,'ypriorcov')) #'auto' would also have achieved this
#modify plot as per normal with ggplot
print(plot1+ggplot2::coord_cartesian(xlim=c(0,10)))
#or generate custom plot from scratch:#'
k=ctPredict(ctstantestfit, timerange=c(0,60), timestep=.1, subjects=2:3)
library(ggplot2)
ggplot(k[k$Element %in% 'yprior',],
aes(x=Time, y=value,colour=Subject,linetype=Row)) +
geom_line() +
theme_bw()
#New subjects: two hypothetical people differing only in TI1, each
#observed once at time 0, predicted to time 4.
newsubjects <- data.frame(id = c('lowTI1', 'highTI1'), time = 0,
Y1 = 8, Y2 = 12, TD1 = 0, TI1 = c(-1, 1))
newsubjects <- rbind(newsubjects,
transform(newsubjects, time = 4, Y1 = NA, Y2 = NA))
k <- ctPredict(ctstantestfit, newdata = newsubjects, timerange = c(0, 4),
timestep = .1)
k[k$Element %in% 'yprior' & k$Time == 4, ]
ctPredict(ctstantestfit, newdata = newsubjects, timerange = c(0, 4),
timestep = .1, plot = TRUE, kalmanvec = 'yprior', errorvec = 'ypriorcov')
# }