Skip to contents

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 newdata when that is given. With realid=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 (NA where 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 in newdata up 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 as randomEffects describes), 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 left NA is taken as zero, as ctFit takes 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')
 # }