% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ctFitCovCheck.R
\name{ctFitCovCheck}
\alias{ctFitCovCheck}
\title{Visual lagged covariance or correlation diagnostics for ctsem fits.}
\usage{
ctFitCovCheck(
  fit,
  cor = TRUE,
  plot = TRUE,
  splitby = NULL,
  data = NULL,
  lags = 0:10,
  variables = NULL,
  splitdata = data,
  split = NULL,
  breaks = 2,
  nsamples = NULL,
  minpairn = 10,
  cores = 1,
  keep = c("summary", "samples")
)
}
\arguments{
\item{fit}{A `ctStanFit` object.}

\item{cor}{Logical; if `TRUE` correlations are analysed instead of covariances.}

\item{plot}{Logical; if `TRUE` (default) a `ggplot2` object (or list of plots)
is returned. If `FALSE`, the raw `data.table` with diagnostics is returned.}

\item{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.}

\item{data}{Optional long-format data to use for the empirical lagged
covariances or correlations. If omitted, the fitted data are used.}

\item{lags}{Non-negative integer vector giving observation lags to compare.}

\item{variables}{Optional character vector of manifest variables to include.
Defaults to all manifest variables in the model.}

\item{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.}

\item{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"`.}

\item{breaks}{Number of quantile groups when `split = "quantile"`.}

\item{nsamples}{Optional number of generated data sets to use. Existing
generated data are reused when present; otherwise `ctGenerateFromFit` is
called.}

\item{minpairn}{Minimum number of complete paired observations required for
an empirical or generated lagged covariance/correlation.}

\item{cores}{Number of cores to use for generating data and summarising
generated samples.}

\item{keep}{If `"samples"`, draw-level model diagnostics are attached as the
`"samples"` attribute of the returned data.}
}
\value{
Either a plot/list of plots (default, given by `ctFitCovCheckPlot`) or
  a `data.table`.
}
\description{
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, then averaged over observation-index pairs.
}
\examples{
\donttest{
# Lagged correlations for all manifest variables, lags 0 to 3.
ctFitCovCheck(ctstantestfit, cor = TRUE, lags = 0:3, plot = TRUE)

# Lagged covariances for one manifest variable.
ctFitCovCheck(ctstantestfit, cor = FALSE, variables = "Y1", lags = 0:5,
  plot = FALSE)

# Split the diagnostic by a time independent predictor in the fitted data.
gg <- ctFitCovCheck(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))
ctFitCovCheck(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]
ctFitCovCheck(ctstantestfit, data = dat, splitby = "period",
  split = "factor", lags = 0:2)
}
}
