This function generates data according to the specified ctsem model object.
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)), sodtmeanis the median rather than the mean wheneverlogdtsdis non-zero: the mean interval isdtmean * exp(logdtsd^2/2), which atlogdtsd = 0.6is about 20 percent longer thandtmean.- 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
Tpointsstored inctmodelobj. If not supplied,ctGenerateusesctmodelobj$Tpointswhen 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 needsctmodelobjto be actModel(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 throughTRAITVARandMANIFESTTRAITVAR, and fills free parameters with fixed defaults; it refuses a nonlinear model and has no measurement link.'auto'uses'r', asctGeneratealways has, unless the model or the call needs'julia': a nonlinear model, a non-Gaussian indicator, more than one count inn, orvalues. 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 isFALSE),TRUEorFALSE. A diagnostic handle rather than a modelling choice.FALSEsamples 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.TRUEinstead 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
nsamplesdatasets 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 nodatastruct, a balanced design ofnsubjects atTpointsoccasionsdtmeanapart 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,Tpointsanddtmeanbuild: 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 anddatastructlacks is zero (TD) or drawn standard normal per subject (TI). The same data frame is returned with the generated values filled in. Needsbackend='julia', orfromPriors=TRUE, where a fit passed asctmodelobjbrings its own.- cores
With
fromPriors=TRUE, cpu cores to use.- values
For
backend='julia': the population values to generate from, named and scaled assummary()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 givessummary()'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') andtipreds(linearised TI predictor effects, named'tip_<predictor>_<parameter>'), as inlist(popmeans = c(mm = 2), popsd = c(mm = 0.5), tipreds = c(tip_TI1_mm = 1)); with grouping levels,popsd.<level>andrawpopcorr.<level>name a level's. What is not given takes its prior's centre: raw zero for a mean,sdscalefor 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
valuesnames it;an individually varying parameter's population sd is its
sdscale, at every level it varies at, on the raw, untransformed scale, unlessRAWPOPVAR(RAWPOPVAR_<level>) states a number, and random effects are uncorrelated unless it states a coordinate –ctCovwrites 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")
# }