Skip to contents

This function is used to specify a continuous time structural equation model, which can then be fit to data with function ctFit.

Usage

ctModel(
  LAMBDA,
  type = "ct",
  n.manifest = "auto",
  n.latent = "auto",
  Tpoints = NULL,
  manifestNames = "auto",
  manifesttype = rep(0, nrow(LAMBDA)),
  ncategories = NULL,
  censormin = NULL,
  censormax = NULL,
  latentNames = "auto",
  id = "id",
  time = "time",
  silent = FALSE,
  T0VAR = "auto",
  T0MEANS = "auto",
  MANIFESTMEANS = "auto",
  MANIFESTVAR = "diag",
  ASYMPTOTES = NA,
  RESPONSE = NA,
  DRIFT = "auto",
  CINT = 0,
  DIFFUSION = "auto",
  n.TDpred = "auto",
  TDpredNames = "auto",
  TDPREDEFFECT = "auto",
  TDPREDMEANS = "auto",
  TDPREDVAR = "auto",
  n.TIpred = "auto",
  TIpredNames = "auto",
  tipredDefault = TRUE,
  PARS = NULL,
  driftScaled = character()
)

Arguments

LAMBDA

n.manifest*n.latent loading matrix relating latent to manifest variables, with latent processes 1:n.latent along the columns, and manifest variables 1:n.manifest in the rows.

type

character string. Use 'ct' (continuous time) or 'dt' (discrete time) for Stan-based fitting with ctFit. These return a modern ctsem model object whose pars data frame can also be edited through the pars-backed matrices view. For legacy workflows, 'omx' returns a matrix-list model object that can be edited directly and then converted via ctModelConvertOMX.

n.manifest

Number of manifest indicators per individual at each measurement occasion / time point. Manifest variables are included as the first element of the wide data matrix, with all the 1:n.manifest manifest variables at time 1 followed by those of time 2, and so on.

n.latent

Number of latent processes.

Tpoints

Number of time points, or measurement occasions, in the data. This will generally be the maximum number of time points for a single individual, but may be one extra if sample relative time intervals are used, see ctIntervalise.

manifestNames

n.manifest length vector of manifest variable names as they appear in the data structure, without any _Tx time point suffix that may be present in wide data. Defaults to Y1, Y2, etc.

manifesttype

n.manifest length vector of manifest variable types. 0 (the default) is a continuous, Gaussian variable; 1 is binary, coded 0/1; 2 is ordinal, coded as consecutive integers from 1; 3 is a count, coded as non-negative integers and modelled as Poisson with a log link, so the latent process gives the log rate. A count keeps a free MANIFESTVAR diagonal, unlike a binary or ordinal variable: for a count that entry is a log-scale dispersion, making the observation Poisson-lognormal with variance \(\mu + \mu^2(e^{\sigma^2}-1)\) against the Poisson's \(\mu\). Fix it to zero for the equidispersed Poisson. 4 is censored, a Gaussian variable observed only within censormin and censormax, with values at a limit contributing the probability of being there rather than a density. Non-Gaussian variables are supported by the julia backend only, and binary additionally by stan.

ncategories

n.manifest length integer vector, giving the number of categories of each ordinal manifest variable and ignored for the others. Required when any manifesttype is 2, because the model has to know how many thresholds to estimate before it sees any data – ctGenerate needs it too.

censormin, censormax

n.manifest length numeric vectors giving the lower and upper censoring limits of each manifesttype = 4 variable, and ignored for the others. Defaults are -Inf and Inf; a variable censored on one side only leaves the other infinite. Unlike thresholds these are known constants rather than parameters – a scale's floor and ceiling are properties of the instrument, and the data cannot inform them.

latentNames

n.latent length vector of latent variable names (used for naming parameters, defaults to eta1, eta2, etc).

id

character string denoting column name containing subject identification variables. id data may be of any form, though will be coerced internally to an integer sequence rising from 1. May instead be a character vector naming a nested hierarchy, innermost first: id = c('subject','study') treats each subject as belonging to one study. A cell says where its parameter varies with the indvarying field (see ctPar): TRUE at every level, FALSE at none, or the names of the levels, so 'cint||study' gives an intercept that varies between studies with subjects exchangeable within a study, and 'cint||subject,study' (or TRUE) one that varies at both. model$pars$indvarying holds the same values, one per cell, and can be edited directly, with TRUE again meaning every level; a cell's sdscale applies at every level it varies at. Intercepts (T0MEANS, MANIFESTMEANS, CINT) left unspecified vary at every level. Levels above the subject require backend='julia' with intoverpop='laplace', and the hierarchy must be strictly nested.

time

character string denoting column name containing timing data. Timing data must be numeric.

silent

Suppress all output to console.

T0VAR

lower triangular n.latent*n.latent cholesky matrix of latent process initial variance / covariance. "auto" freely estimates all parameters.

T0MEANS

n.latent*1 matrix of latent process means at first time point, T0. "auto" freely estimates all parameters.

MANIFESTMEANS

n.manifest*1 matrix of manifest intercept parameters. "auto" frees all parameters.

MANIFESTVAR

lower triangular n.manifest*n.manifest cholesky matrix of variance / covariance between manifests at each measurement occasion (i.e. measurement error / residual). "auto" freely estimates variance parameters, and fixes covariances between manifests to 0. "free" frees all values, including covariances.

ASYMPTOTES

Matrix with one row per binary indicator, in manifest order, and two columns: the lower and upper asymptotes of its response probability, which is then lower + (upper - lower) times the logistic of the linear predictor. NA means no asymptote on that side, so the default – all NA – is the two parameter logistic, and the model has no ASYMPTOTES matrix at all. Name a lower cell to estimate a guessing probability (the three parameter model), an upper cell for a ceiling below one, or both (four parameter); a number between 0 and 1 fixes it, and one name shared across rows estimates one asymptote for those items. A length 2 vector applies to every binary indicator, so c('guess', NA) is one guessing parameter for the whole test. Julia backend only.

RESPONSE

Matrix with one row per manifest variable and two columns, the response scale of a censored indicator (manifesttype 4); rows for other indicators must stay at their defaults. Column 1, halfwidth: the half-width of the interval each recorded value stands for – a value y is the event that the latent response lies between the transformed y - halfwidth and y + halfwidth, and a value at censormin or censormax that it lies below or above half a step in from it. 0, the default, is a value recorded exactly. For a rating scale it is half the step between categories, so the bottom category of a 7-point item and a slider's 0 are each what they are; a step that differs by study is a time independent predictor in the cell. Column 2, power: the transform from the recorded scale to the latent response, \(G(r) = L + ((1 + r - L)^p - 1)/p\) with \(L\) the censormin (0 where there is none). 1, the default, is linear; below 1 the latent response moves less per recorded unit high on the scale, so the recorded value moves faster there; 0 is the log, whose inverse is the exponential link. One transform serves every form an item is asked in, so a name shared across items or studies estimates one curvature from all of them. NA keeps a default, and a length 2 vector fills every censored row, so c(0.5, 'power') is integer data with one estimated transform. Julia backend only.

DRIFT

n.latent*n.latent DRIFT matrix of continuous auto and cross effects, relating the processes over time. "auto" freely estimates all parameters.

CINT

n.latent * 1 matrix of latent process intercepts, allowing for non 0 asymptotic levels of the latent processes. Generally only necessary for additional trends and more complex dynamics.

DIFFUSION

lower triangular n.latent*n.latent cholesky matrix of diffusion process variance and covariance (latent error / dynamic innovation). "auto" freely estimates all parameters.

n.TDpred

Number of time dependent predictor variables in the dataset.

TDpredNames

n.TDpred length vector of time dependent predictor variable names, as they appear in the data structure, without any _Tx time point suffix that may appear in wide data. Default names are TD1, TD2, etc.

TDPREDEFFECT

n.latent*n.TDpred matrix of effects from time dependent predictors to latent processes. Effects from 1:n.TDpred columns TDpredictors go to 1:n.latent rows of latent processes. "auto" freely estimates all parameters.

TDPREDMEANS

Legacy argument for time-dependent predictor means, mainly to support data generation workflows. Expected dimensions are (n.TDpred * Tpoints) rows and 1 column. "auto" creates a free-label matrix.

TDPREDVAR

Legacy argument for time-dependent predictor covariance structure, mainly to support data generation workflows. Expected dimensions are (n.TDpred * Tpoints) square. "auto" creates a free-label matrix.

n.TIpred

Number of time independent predictors. Each TIpredictor is inserted at the right of the data matrix, after the time intervals.

TIpredNames

n.TIpred length vector of time independent predictor variable names, as they appear in the data structure. Default names are TI1, TI2, etc. Or a formula whose terms are such names and smooth terms, ~ s(age, k = 8) + female: a smooth is a penalised spline of a person-level covariate, with its smoothness estimated from the data (backend = 'julia'). It enters the model as k - 1 predictor columns, age_lin (the linear trend) and age_s1, ..., which are built from the data when the model is fitted. A cell's tipreds field names the covariate ('cint||||age') to give it the smooth; without one, under tipredDefault = TRUE, a smooth reaches every free parameter that varies between persons.

tipredDefault

Logical. TRUE sets any parameters with unspecified time independent predictor effects to have effects estimated, FALSE fixes the effect to zero unless individually specified. A cell's effects count as unspecified only when its tipreds field is left out: an empty one ('mypar||||') states that the parameter has no predictor effects, which is the way to exclude a parameter under tipredDefault = TRUE. The setting is kept on the returned model as $tipredDefault.

PARS

for types 'ct' and 'dt' only. May be of any structure, only needed to contain extra parameters for certain non-linear models.

driftScaled

for type 'ct' only: which of "DIFFUSION" and "CINT" to parameterise by what they accrue over one time unit given the process's own drift diagonal, rather than by their instantaneous rates. A diffusion sd s becomes s * sqrt(2 a / expm1(2 a)), s^2 the variance the process gains over one time unit from its own noise (its stationary variance where the drift is fast, the diffusion variance where it is slow); an intercept u becomes u * a / expm1(a). The fit and its likelihood are the default parameterisation's; what changes is that these parameters no longer have to move with the drift diagonal where fast mean reversion and more noise look alike, so that uncertainty and sampling are better behaved there. Only the diffusion's diagonal is rescaled, so its correlations keep their continuous-time meaning. Each such parameter moves, name, transform, random effects and predictor effects with it, to a new cell of PARS, and its own cell becomes an expression of that cell and the drift diagonal. Not available with covmattransform = 'cholesky'.

Value

For type = 'ct' or 'dt', a model of class ctStanModel: $pars holds one row per matrix cell, and $matrices the same cells as matrices, editable either way. For type = 'omx', a list of matrices of class ctsemInit, for ctGenerate or ctModelConvertOMX.

Details

A matrix cell is one of four things, and which one is decided by what its text looks like:

  • a number, which fixes the cell;

  • a parameter name, which frees it – the same name in two cells is one parameter, which is how an equality constraint is written;

  • a name with fields, adding the transform, the levels of id at which the parameter varies, the prior scaling of that variation, and the time-independent predictors acting on the parameter;

  • an expression, computed from the latent states, the time dependent predictors and the PARS cells.

Fields may be given in either of two interchangeable ways: in a fixed order separated by | ('mm||TRUE|0.5'), or by name ('mm, indvarying=TRUE, sdscale=0.5'). With nested ids, indvarying may name levels instead, as in 'mm||study' or 'mm, indvarying=c(subject, study)'. A cell containing | is read the ordered way; otherwise a cell with a field of the form name=value is read the named way, and an unrecognised field name is an error rather than part of a parameter name. ctPar writes the ordered form from the same named arguments, for when a specification is built programmatically.

Every name in an expression has to be declared: a latent state, a time dependent predictor, or a parameter given a PARS cell. Writing a fresh name inside an expression does not declare it, so DRIFT = matrix('-exp(dr)*eta1') needs PARS = c('dr') alongside it. To transform one parameter and nothing else the second field is shorter – DRIFT = matrix('dr|-exp(param)'). A cell may also read a time independent predictor by name, the subject's value of it – a study's known response rounding as MANIFESTVAR = 'rsd + mvar', say, with PARS = c('mvar|1e-10 + 5 * log1p_exp(2 * param)'); this is julia only. A subject's missing value of such a predictor is imputed or sampled as any other (optimcontrol$tipredMissing), and the cell reads that value. Population summaries evaluate the cell at a predictor value of zero, where they report predictor effects. A cell cannot reference a manifest variable or the time interval at all. Predictor effects on a parameter are set with the tipreds field.

Not every simple name in a cell is a parameter name. A latent state or time dependent predictor name is a reference to it, and any number of matrices may reference the same one. A name declared in a PARS cell is likewise a reference wherever else it is written: the PARS cell holds the parameter and carries its transform, and the cells that name it are rewritten into references to that cell.

Repeating a name that is not one of those is the equality constraint, and those cells are one parameter – one value, one random effect – so one transform has to apply to all of them. Cells that would transform it differently are refused, and that includes cells whose defaults differ: the DRIFT diagonal is bounded negative while its off-diagonals are not, so DRIFT = matrix('a', 2, 2) is not a way to tie the whole matrix to one parameter. To share a parameter across cells that would otherwise transform it differently, declare it in one PARS cell (PARS = c('a')) and then apply whatever transform each cell needs in an expression there – DRIFT[1,1] = '-exp(a)' and DIFFUSION[1,1] = 'exp(a)'. One parameter then serves cells that need different transforms, and each transform is stated where it applies. Giving the PARS cell the transform instead (PARS = c('a|-exp(param)')) and writing just the name in each cell works when one transform suits them all. Two PARS cells sharing one label are co-holders rather than references, so they must agree on the transform as any other repeated name must.

A predictor effect belongs to the parameter rather than to the cell, so cells that are one parameter must state the same tipreds. Naming an effect ('mypar||||age=shared') constrains every parameter given that name under that predictor to one coefficient, which costs one fewer free parameter and makes the two parameters' reported effects identical. Because one coefficient displaces each parameter's raw value equally, it means the same thing on the natural scale only where the transforms agree, so sharing a name between parameters transformed differently is refused. A name is scoped per predictor: the same label under two predictors is two coefficients. A number instead of a name ('mypar||||age=0.5') fixes the effect: no coefficient is estimated, and each subject's raw value of the parameter is displaced by 0.5 times their age, before the transform. Fixed effects are fitted by backend = 'julia' and used by ctGenerate; the stan backend refuses them.

A cell that is exactly a latent state or time dependent predictor name is taken as a reference to it rather than as a parameter of that name, and warns, because the two readings are different models. 'state[1]' and 'tdpreds[rowi, 1]' say the same thing without the ambiguity. In PARS it is an error rather than a warning: a bare name there reads as the declaration of a parameter, so write the reference as part of an expression ('log1p(exp(eta1))') if a state-dependent PARS cell is what is wanted.

See also

ctPar for the fields a matrix cell can carry, ctFit for fitting the result.

Examples

 ### Frequentist example:
 ### impulse and level change time dependent predictor 
 ### example from Driver, Oud, Voelkle (2015)
 data('ctExample2')
 tdpredmodel <- ctModel(type='omx', n.manifest = 2, n.latent = 3, n.TDpred = 1, 
 Tpoints = 8, manifestNames = c('LeisureTime', 'Happiness'), 
 TDpredNames = 'MoneyInt', 
 latentNames = c('LeisureTime', 'Happiness', 'MoneyIntLatent'),
 LAMBDA = matrix(c(1,0, 0,1, 0,0), ncol = 3))

 tdpredmodel$DIFFUSION[, 3] <- 0
 tdpredmodel$DIFFUSION[3, ] <- 0
 tdpredmodel$T0VAR[3, ] <- 0
 tdpredmodel$T0VAR[, 3] <- 0
 tdpredmodel$CINT[3] <- 0
 tdpredmodel$T0MEANS[3] <- 0
 tdpredmodel$DRIFT[3, ] <- 0
 
 
###Bayesian example:
model<-ctModel(type='ct',
n.latent=2, latentNames=c('eta1','eta2'),
n.manifest=2, manifestNames=c('Y1','Y2'),
n.TDpred=1, TDpredNames='TD1', 
n.TIpred=3, TIpredNames=c('TI1','TI2','TI3'),
LAMBDA=diag(2))