Visual lagged covariance or correlation diagnostics for ctsem fits.
Source:R/ctFitCovCheck.R
ctFitCheckCov.RdCompares empirical lagged covariances or correlations with the same quantity
computed from data generated by the fitted model. For each requested lag,
covariances or correlations are computed across subjects for each matching
observation-index pair. By default (x = "lag") they are then averaged
over observation-index pairs, which hides misfit that differs between waves,
such as a variance that changes at one wave; x = "obs" or a data
column instead shows each wave, or each value or bin of the column, as a
point of its own.
ctFitCovCheck is maintained as a backward-compatible alias.
Usage
ctFitCheckCov(
fit,
cor = TRUE,
plot = TRUE,
splitby = NULL,
data = NULL,
lags = NULL,
variables = NULL,
splitdata = data,
split = NULL,
breaks = 2,
nsamples = NULL,
minpairn = 10,
cores = getOption("mc.cores", 2L),
keep = c("summary", "samples"),
x = "lag",
xbins = 10,
lagrows = c("all", "observed")
)Arguments
- fit
A fitted object from
ctFit, from either backend.- cor
Logical; if `TRUE` correlations are analysed instead of covariances.
- plot
Logical; if `TRUE` (default) a `ggplot2` object (or list of plots) is returned. If `FALSE`, the raw `data.table` with diagnostics is returned.
- splitby
Optional character string giving the variable name on which to split subjects or observations. Numeric variables are split at the subject mean and then at the grand mean by default; non-numeric variables are treated as groups and may vary within subject.
- data
Optional long-format data to use for the empirical lagged covariances or correlations. If omitted, the fitted data are used.
- lags
Non-negative integer vector giving observation lags to compare. If `NULL`, `0:10` for `x = "lag"` and `0:1` (variances or covariances, and lag-1 relations) otherwise.
- variables
Optional character vector of manifest variables to include. Defaults to all manifest variables in the model.
- splitdata
Optional data containing `splitby`, useful when the split variable was not in the fitted model. If omitted, `data` is used when supplied, otherwise the fitted data are used.
- split
Split rule for `splitby`: `"median"`, `"mean"`, `"quantile"`, `"factor"`, or `"none"`. If `NULL`, numeric split variables use `"mean"` and non-numeric split variables use `"factor"`.
- breaks
Number of quantile groups when `split = "quantile"`.
- nsamples
Optional number of generated data sets to use. Existing generated data are reused when present; otherwise `ctGenerateFromFit` is called.
- minpairn
Minimum number of complete paired observations required for an empirical or generated lagged covariance/correlation: for each observation-index pair averaged under `x = "lag"`, and for each point otherwise. A point with fewer is left out of the plot and of the share outside the model's interval; raise it to drop bins that hold only a few off-schedule observations.
- cores
Cores for generating the data when
fitcarries none: engine threads for a julia fit, and for a stan fit worker processes, which start only for a job large enough to repay them. The summary of the generated datasets is computed in this session.- keep
If `"samples"`, draw-level model diagnostics are attached as the `"samples"` attribute of the returned data.
- x
What the x axis shows. `"lag"` (default): one point per lag, averaged over observation indices. `"obs"`: one point per observation index within subject (1 for each subject's first row), a panel per lag. Or the name of a column of `data` (or of the fitted data), such as the time column or an age: one point per value of that column, or per quantile bin of it (see `xbins`), a panel per lag. Each pair of observations is placed by its later observation, as a row-level split is.
- xbins
Number of quantile bins for a numeric `x` column with more distinct values than this; a column with no more is used as it is. The x axis shows each bin's mean.
- lagrows
Which rows a lag counts. `"all"` (default): lag k pairs a row with the subject's k-th earlier row. `"observed"`: with the k-th earlier row at which the column variable was observed, so a variable measured at only some waves is paired with its own previous measurement rather than with rows that hold only other variables. The gap in time between the two then varies more, and the model's data, which share the observed data's missingness, are paired the same way.
See also
ctPostPredPlots, the posterior predictive dashboard,
whose LaggedCovariance panel is this function without the splitting.
Examples
# \donttest{
# Lagged correlations for all manifest variables, lags 0 to 3.
ctFitCheckCov(ctstantestfit, cor = TRUE, lags = 0:3, plot = TRUE)
# Lagged covariances for one manifest variable.
ctFitCheckCov(ctstantestfit, cor = FALSE, variables = "Y1", lags = 0:5,
plot = FALSE)
# Variances, covariances and lag-1 covariances at each wave rather than
# averaged over waves, and the same by bins of time.
ctFitCheckCov(ctstantestfit, cor = FALSE, x = "obs")
ctFitCheckCov(ctstantestfit, cor = FALSE, x = "time", xbins = 5)
# Lag each variable by its own previous observation, for variables
# measured at only some waves.
ctFitCheckCov(ctstantestfit, x = "obs", lagrows = "observed")
# Split the diagnostic by a time independent predictor in the fitted data.
gg <- ctFitCheckCov(ctstantestfit, cor = TRUE, splitby = "TI1", lags = 0:3)
print(gg[[1]])
# Use an external subject-level variable for the split.
splitdat <- unique(data.frame(ctstantestdat)[, "id", drop = FALSE])
splitdat$group <- rep(c("a", "b"), length.out = nrow(splitdat))
ctFitCheckCov(ctstantestfit, splitby = "group", splitdata = splitdat,
lags = 0:2)
# Split observations into early and late periods within each subject.
dat <- data.table::as.data.table(data.frame(ctstantestdat))
dat[, period := ifelse(time <= stats::median(time, na.rm = TRUE),
"early", "late"), by = id]
ctFitCheckCov(ctstantestfit, data = dat, splitby = "period",
split = "factor", lags = 0:2)
# }