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 = "_")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.
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.
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.
Returns a tpmatrix object that inherits from data.table
where each column is an element of the transition probability matrix with
elements ordered rowwise.
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.
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