Skip to contents

This function generates data according to the specified ctsem model object.

Usage

ctGenerate(
  ctmodelobj,
  n = 100,
  burnin = 0,
  dtmean = 1,
  logdtsd = 0,
  dtmat = NA,
  Tpoints = NULL,
  wide = FALSE,
  backend = c("auto", "r", "julia", "stan"),
  intoverstates = "auto",
  fromPriors = FALSE,
  nsamples = 200,
  datastruct = NA,
  cores = getOption("mc.cores", 2L),
  values = NULL,
  n.subjects
)

Arguments

ctmodelobj

ctsem model object from ctModel.

n

Number of subjects to output. For a model with grouping levels above the subject (ctModel(id = c('subject', 'study'))), one count per level in the same order, innermost first: c(100, 10) is 100 subjects split evenly over 10 studies. A level not given has one group.

burnin

Number of initial time points to discard (to simulate stationary data)

dtmean

Positive numeric. Median time interval (delta T) to use. Intervals are drawn as exp(rnorm(n, log(dtmean), logdtsd)), so dtmean is the median rather than the mean whenever logdtsd is non-zero: the mean interval is dtmean * exp(logdtsd^2/2), which at logdtsd = 0.6 is about 20 percent longer than dtmean.

logdtsd

Numeric. Standard deviation of the log time interval. Zero gives an equal-interval design.

dtmat

Either NA, or numeric matrix of n rows and Tpoints-1 columns, containing positive numeric values for all time intervals between measurements. If not NA, dtmean and logdtsd are ignored.

Tpoints

Optional number of time points to generate. If supplied, this overrides any Tpoints stored in ctmodelobj. If not supplied, ctGenerate uses ctmodelobj$Tpoints when available.

wide

Logical. Output in wide format?

backend

Which generator to use: 'r', 'julia', or 'auto' (the default). 'julia' generates from the model itself: each subject's parameters are drawn from the population at every level, its latent trajectory is simulated from the process, and each observation is drawn from its measurement model, so nonlinear dynamics, random effects on any parameter and binary, ordinal or count indicators are all generated exactly. It needs ctmodelobj to be a ctModel(type='ct'/'dt') object rather than the matrix-list form. 'r' integrates a linear Gaussian system with a matrix exponential at the values the model states, with individual differences only through TRAITVAR and MANIFESTTRAITVAR, and fills free parameters with fixed defaults; it refuses a nonlinear model and has no measurement link. 'auto' uses 'r', as ctGenerate always has, unless the model or the call needs 'julia': a nonlinear model, a non-Gaussian indicator, more than one count in n, or values. On a model that declares random effects or TI predictor effects, 'r' says what it leaves out.

intoverstates

For backend='julia': 'auto' (the default, which is FALSE), TRUE or FALSE. A diagnostic handle rather than a modelling choice.

FALSE samples the latent trajectory from the process and then each observation from its conditional distribution given the state at its row: a draw from the model. TRUE instead draws each row from the filter's one-step-ahead predictive, for the same subjects, which is the density a fit integrating over the states maximises. The two agree in distribution for linear dynamics with Gaussian indicators and differ otherwise, which is what makes the comparison useful.

backend='r' already generates this way and ignores the argument.

fromPriors

Draw the parameters from the model's priors rather than using the values the model specifies, and return nsamples datasets instead of one. This is the prior predictive: what the model says the data could look like before it has seen any. It needs no fitted model and no data – with no datastruct, a balanced design of n subjects at Tpoints occasions dtmean apart is used.

nsamples

With fromPriors=TRUE, how many datasets to draw.

datastruct

A long format data frame giving the design to generate for, in place of the balanced one n, Tpoints and dtmean build: the subject (and any group) ids and times, TD and TI predictor values, and which observations exist – a manifest cell that is NA stays missing, any other value or a manifest column left out is generated. A predictor the model names and datastruct lacks is zero (TD) or drawn standard normal per subject (TI). The same data frame is returned with the generated values filled in. Needs backend='julia', or fromPriors=TRUE, where a fit passed as ctmodelobj brings its own.

cores

With fromPriors=TRUE, cpu cores to use.

values

For backend='julia': the population values to generate from, named and scaled as summary() reports them, so a model written for fitting can generate data at chosen values. A named numeric vector gives free parameters' values on their natural scale, e.g. c(mm = 2, drift = -0.3). A list gives summary()'s sections: popmeans (the same), popsd (random-effect sds on the natural scale, named by parameter), rawpopcorr (correlations of the random effects, named 'a__b') and tipreds (linearised TI predictor effects, named 'tip_<predictor>_<parameter>'), as in list(popmeans = c(mm = 2), popsd = c(mm = 0.5), tipreds = c(tip_TI1_mm = 1)); with grouping levels, popsd.<level> and rawpopcorr.<level> name a level's. What is not given takes its prior's centre: raw zero for a mean, sdscale for a raw sd, zero for a correlation or a free effect. A value fixed in the model cannot also be given here.

n.subjects

Deprecated; use n.

Value

From the R generator, a long format matrix with one row per subject and time point, or wide format with wide = TRUE. From the julia generator, the same long format, carrying the attributes described under Generating values. With fromPriors = TRUE, a list: Y, an nsamples by data rows by manifest variables array of generated data, and llrow, the matching array of row log likelihoods.

Details

Covariance related matrices are treated as Cholesky factors. TRAITTDPREDCOV and TIPREDCOV matrices are not accounted for, at present. The first 1:n.TDpred rows and columns of TDPREDVAR are used for generating tdpreds at each time point.

Generating values

With backend='julia' every value the model leaves free is fixed by the scale of its prior, and all of them are named in a message:

  • a free parameter is at its prior's centre, raw zero, unless values names it;

  • an individually varying parameter's population sd is its sdscale, at every level it varies at, on the raw, untransformed scale, unless RAWPOPVAR (RAWPOPVAR_<level>) states a number, and random effects are uncorrelated unless it states a coordinate – ctCov writes one from a covariance;

  • a time independent predictor is drawn standard normal per subject, and an effect fixed in the model ('mm||||TI1=0.5') shifts the raw parameter by that much per unit of the predictor; an effect left free is zero.

fromPriors=TRUE draws all of these from the priors instead.

The julia generator also returns what it generated from, as attributes: attr(, 'subjectpars'), each subject's parameters on their natural scale with its id and groups; attr(, 'grouppars'), for a model with grouping levels, each group's parameters at each level – its own effects and those above it, as a subject of average deviation within it would have; and attr(, 'states'), the latent states at every row by id and time (not with intoverstates=TRUE, which draws observations from the filter rather than states).

Examples

#a 2 process model, each process measured by a noisy indicator, with stable
#individual differences in process levels
generatingModel<-ctModel(Tpoints=8,n.latent=2,n.TDpred=0,n.TIpred=0,n.manifest=2,
 MANIFESTVAR=diag(.1,2),
 LAMBDA=diag(1,2),
 DRIFT=matrix(c(-.2,-.05,-.1,-.1),nrow=2),
 DIFFUSION=matrix(c(1,.2,0,4),2),
 CINT=matrix(c('cint1, indvarying=TRUE, sdscale=0.05',
   'cint2, indvarying=TRUE, sdscale=0.08'),nrow=2),
 MANIFESTMEANS=matrix(0,ncol=1,nrow=2),
 T0MEANS=matrix(0,ncol=1,nrow=2),
 T0VAR=diag(1,2))

#the R generator: every subject at the values the model states, with free
#cells filled by fixed defaults and no individual differences
data <- ctGenerate(generatingModel,n=15,burnin=10)

# \donttest{
#the julia engine: each subject's CINT drawn from the population, with the
#means stated on the natural scale and the sds given by sdscale on the raw
#scale (CINT is 10 * raw, so 0.5 and 0.8)
if (isTRUE(ctJuliaStatus()$available)) {
  data <- ctGenerate(generatingModel,n=15,burnin=10,
    backend='julia',values=c(cint1=1,cint2=0))
}
# }

#the prior predictive: what the model says data could look like before it
#has seen any. No fit, and no data.
# \donttest{
priorpred <- ctGenerate(generatingModel, fromPriors = TRUE, Tpoints = 6,
  n = 10, nsamples = 20, cores = 2)
str(priorpred$Y)
# backend = 'auto' generates with julia where it is available. Julia keeps
# running between calls, holding what it has compiled; this ends it.
if (isTRUE(ctJuliaStatus()$available)) ctJuliaKill("session")
# }