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.tablewhere 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.

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
#> 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
#> 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
#> 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
#> 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
#> 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
#> 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
#> 1:           0.5           0.5           0.3           0.7