LaMa (version 3.1.0)

generator: Build the generator matrix of a continuous-time Markov chain

Description

This function builds the infinitesimal generator matrix for a continuous-time Markov chain from an unconstrained parameter vector.

Usage

generator(
  beta,
  Z = NULL,
  Eta = NULL,
  byrow = FALSE,
  report = TRUE,
  param = NULL
)

Value

infinitesimal generator matrix of dimension c(nStates, nStates) or array of such matrices of dimension c(nStates, nStates, nObs) if Z or Eta is provided.

Arguments

beta

parameters; either

• a vector of length nStates * (nStates-1), or

• a matrix of dimension c(nStates * (nStates-1), p+1) if design matrix Z is also provided.

Z

optional covariate design matrix with or without intercept column, i.e. of dimension c(nObs, p) or c(nObs, p+1). If provided, beta needs to be a matrix of dimension c(nStates * (nStates-1), p+1).

Eta

optional pre-calculated matrix of linear predictors of dimension c(nObs, nStates * (nStates-1)). If provided, Z and beta will be ignored.

byrow

logical indicating if the generator matrix should be filled by row

report

logical; if TRUE (default), the coefficient matrix beta is reported from the fitted model, if Z is provided. Requires automatic differentiation with RTMB.

param

deprecated, please use argument beta instead.

Details

Generator matrices. The off-diagonal entry \(q_{ij} \geq 0\) of a generator \(Q\) is the rate of switching from state \(i\) to state \(j\), i.e. \(\Pr(S_{t+h} = j \mid S_t = i) \approx q_{ij} h\) for small \(h\). The diagonal entries are \(q_{ii} = -\sum_{j \neq i} q_{ij}\), so that each row sums to zero. Hence, the time spent in state \(i\) is exponentially distributed with rate \(-q_{ii}\), and when leaving state \(i\), the chain moves to state \(j\) with probability \(q_{ij} / (-q_{ii})\). Transition probabilities over intervals of length \(\Delta t\) are \(\exp(Q \Delta t)\), calculated by tpm_ct.

Parameterisation. The off-diagonal entries are calculated as \(q_{ij} = \exp(\beta_k)\) to ensure positivity, and the diagonal entries are then set to the negative row sums. By default (byrow = FALSE), the off-diagonal entries are filled column-wise, i.e. for 3 states \(\beta\) corresponds to \((q_{21}, q_{31}, q_{12}, q_{32}, q_{13}, q_{23})\). With byrow = TRUE, they are filled row-wise, i.e. \((q_{12}, q_{13}, q_{21}, q_{23}, q_{31}, q_{32})\). For 2 states, this means \(\beta = (\log q_{21}, \log q_{12})\) by default and \(\beta = (\log q_{12}, \log q_{21})\) with byrow = TRUE.

Covariates. If a design matrix Z is provided, each off-diagonal entry depends on covariates via \(q_{ij}^{(t)} = \exp(z_t^\top \beta_{ij})\), where \(z_t\) is row \(t\) of Z, and one generator matrix is returned for each row of Z. Then beta needs to be a matrix of coefficients of dimension c(nStates * (nStates-1), p+1), where the first column contains the intercepts and rows are ordered as above. Alternatively, a matrix of linear predictors Eta can be provided, with one column per off-diagonal entry in the same order. When passed to tpm_ct, the generator is assumed constant within each interval, so row \(t\) of Z should contain the covariates at the start of interval \(t\).

See Also

Other transition probability matrix functions: generator_g(), tpm(), tpm_ct(), tpm_emb(), tpm_emb_g(), tpm_g(), tpm_g2(), tpm_p()

Examples

# 2 states: 2 free off-diagonal elements
generator(rep(-1, 2))
# 3 states: 6 free off-diagonal elements
generator(rep(-2, 6))