`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 |
---|---|

complement | Either a character vector or a numeric vector denoting the
transitions (i.e., the columns of the tabular object formed from |

states, prefix, sep | Arguments passed to |

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.

#> s1_s1 s1_s2 s2_s1 s2_s2 #> 1: 0.3 0.7 0 1 #> 2: 0.4 0.6 0 1tpmatrix( 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#> 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#> 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