Transition probability matrix

tpmatrix() both defines and evaluates a transition probability matrix in which elements are expressions. It can be used within define_tparams() to create a transition probability matrix or directly to create a tparams_transprobs() object. These are, in turn, ultimately used to create a CohortDtstmTrans object for simulating health state transitions.

tpmatrix(..., complement = NULL, states = NULL, prefix = "", sep = "_")

Arguments

...

Named values of expressions defining elements of the matrix. Each element of ... should either be a vector or a 2-dimensional tabular object such as a data frame. See "Details" and the examples below.

complement

Either a character vector or a numeric vector denoting the transitions (i.e., the columns of the tabular object formed from ...) that are complementary (see "Details" below). If a character vector, each element should be the name of a column in the tabular object; if a numeric vector, each element should be the index of a column in the tabular object.

states, prefix, sep

Arguments passed to tpmatrix_names() for naming the columns. If states = NULL (the default), then the states are named s1, ..., sh where h is the number of health states.

Value

Returns a tpmatrix object that inherits from data.table where each column is an element of the transition probability matrix with elements ordered rowwise.

Details

A tpmatrix is a 2-dimensional tabular object that stores flattened square transition probability matrices in each row. Each transition probability matrix is filled rowwise. The complementary probability (equal to \(1\) minus the sum of the probabilities of all other elements in a row of a transition probability matrix) can be conveniently referred to as C or specified with the complement argument. There can only be one complement for each row in a transition probability matrix.

See also

A tpmatrix is useful because it provides a convenient way to construct a tparams_transprobs object, which is the object in hesim used to specify the transition probabilities required to simulate Markov chains with the CohortDtstmTrans class. See the tparams_transprobs documentation for more details.

The summary.tpmatrix() method can be used to summarize a tpmatrix across parameter samples.

Examples

p_12 <- c(.7, .6)
tpmatrix(
  C, p_12,
  0, 1
)
#>    s1_s1 s1_s2 s2_s1 s2_s2
#>    <num> <num> <num> <num>
#> 1:   0.3   0.7     0     1
#> 2:   0.4   0.6     0     1

tpmatrix(
  C, p_12,
  C, 1
)
#>    s1_s1 s1_s2 s2_s1 s2_s2
#>    <num> <num> <num> <num>
#> 1:   0.3   0.7     0     1
#> 2:   0.4   0.6     0     1

# Pass matrix
pmat <- matrix(c(.5, .5, .3, .7), byrow = TRUE, ncol = 4)
tpmatrix(pmat)
#>    s1_s1 s1_s2 s2_s1 s2_s2
#>    <num> <num> <num> <num>
#> 1:   0.5   0.5   0.3   0.7

# Pass vectors and data frames
p1 <- data.frame(
  p_12 = c(.7, .6),
  p_13 = c(.1, .2)
)

p2 <- data.frame(
  p_21 = 0,
  p_22 = c(.4, .45),
  p_23 = c(.6, .55)
)

p3 <- data.frame(
  p_31 = c(0, 0),
  p_32 = c(0, 0),
  p_33 = c(1, 1)
)

tpmatrix(
  C, p1,
  p2,
  p3
)
#>    s1_s1 s1_s2 s1_s3 s2_s1 s2_s2 s2_s3 s3_s1 s3_s2 s3_s3
#>    <num> <num> <num> <num> <num> <num> <num> <num> <num>
#> 1:   0.2   0.7   0.1     0  0.40  0.60     0     0     1
#> 2:   0.2   0.6   0.2     0  0.45  0.55     0     0     1

# Use the 'complement' argument
pmat <- data.frame(s1_s1 = 0, s1_s2 = .5, s2_s1 = .3, s2_s2 = 0)
tpmatrix(pmat, complement = c("s1_s1", "s2_s2"))
#>    s1_s1 s1_s2 s2_s1 s2_s2
#>    <num> <num> <num> <num>
#> 1:   0.5   0.5   0.3   0.7
tpmatrix(pmat, complement = c(1, 4)) # Can also pass integers
#>    s1_s1 s1_s2 s2_s1 s2_s2
#>    <num> <num> <num> <num>
#> 1:   0.5   0.5   0.3   0.7

# Can control column names
tpmatrix(pmat, complement = c(1, 4),
         states = c("state1", "state2"), sep = ".")
#>    state1.state1 state1.state2 state2.state1 state2.state2
#>            <num>         <num>         <num>         <num>
#> 1:           0.5           0.5           0.3           0.7