Skip to contents

Compares 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 fit carries 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.

Value

Either a plot/list of plots (default, given by `ctFitCovCheckPlot`) or a `data.table`.

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)
# }