Skip to contents

Build the generator matrix of a continuous-time Markov chain

generator.Rd

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
)

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.

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.

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))
#>            S1         S2
#> S1 -0.3678794  0.3678794
#> S2  0.3678794 -0.3678794
# 3 states: 6 free off-diagonal elements
generator(rep(-2, 6))
#>            S1         S2         S3
#> S1 -0.2706706  0.1353353  0.1353353
#> S2  0.1353353 -0.2706706  0.1353353
#> S3  0.1353353  0.1353353 -0.2706706