Why the Transition Matrix Must Match the State Diagram
Before software can work with a multi-state process, its states and the transitions allowed between them must be encoded consistently. In an illness-death example, a person may begin alive and illness-free, move to an ill state, and eventually die. Death may also occur before illness. The transition matrix records which directed moves are permitted and assigns an identifier to each permitted move.
This matrix is a structural description, not an analysis result. It does not contain follow-up times, observed event histories, transition probabilities, or fitted effects. Its job is to make the state system explicit so that subsequent data preparation and modeling can refer to the same transitions.
State labels and state numbers are related but not interchangeable. The state numbers are the positions in the ordered state list supplied to the software. For example, if the state order is “Well,” “Ill,” “Dead,” then Well is state 1, Ill is state 2, and Dead is state 3. Transition numbers are a separate numbering system: they identify arrows, not states.
The usual illness-death structure has three permitted arrows: \(1 \to 2\), \(1 \to 3\), and \(2 \to 3\). Death is absorbing in this structure because there are no transitions out of state 3. That is a modeling choice represented by the diagram; the software does not infer that a state is absorbing merely because its label says “Dead.”
Constructing an Illness-Death Matrix
The mstate function transMat takes a list of permitted destination state numbers, one list element for each origin state. The first list element describes transitions out of state 1, the second describes transitions out of state 2, and so on. State names can be supplied to label the matrix rows and columns.
Worked Example: The Standard Three-State Illness-Death Structure
Suppose a hypothetical follow-up study uses three states: 1 = Well, 2 = Ill, and 3 = Dead. The clinical diagram allows illness-free participants to become ill or die, and allows ill participants to die. Death has no outgoing arrows. In R, the construction is:
R expression: transMat(list(c(2, 3), c(3), c()), names = c("Well", "Ill", "Dead"))
The first list element, c(2, 3), says that state 1 has arrows to states 2 and 3. The second element, c(3), says that state 2 has an arrow to state 3. The empty third element says that state 3 has no outgoing arrows. With the states ordered as supplied, the resulting matrix is:
| Origin \ Destination | Well (1) | Ill (2) | Dead (3) |
|---|---|---|---|
| Well (1) | NA | 1 | 2 |
| Ill (2) | NA | NA | 3 |
| Dead (3) | NA | NA | NA |
Thus transition 1 is Well to Ill, transition 2 is Well to Dead, and transition 3 is Ill to Dead. The matrix has three non-NA entries, exactly matching the three permitted arrows. The diagonal entries are NA because this model does not include self-transitions.
In this construction, transition numbers are assigned by moving through origins in state order and then through each origin’s destination list in the order supplied. Listing destinations in increasing state order is a simple way to make the numbering reproducible. If the state order or destination order changes, transition numbers can change even when the clinical diagram is otherwise equivalent. Record the state order and transition mapping alongside the analysis.
What Must Be True Before Encoding
A matrix can be syntactically valid yet represent the wrong scientific process. Specify the state system before calling transMat. In particular, check that the states are well-defined and mutually exclusive at a given time, that the state numbering is fixed, and that every arrow has a clear origin and destination. The set of permitted arrows should reflect the scientific question and the intended follow-up, not merely the event codes available in a data file.
Also decide whether the process truly excludes return to a prior state. The standard illness-death diagram above does not allow recovery from Ill to Well. If recovery is possible and is part of the target process, omitting that arrow would encode a different model. Conversely, adding an arrow simply because it is imaginable can be inappropriate if it is outside the prespecified state system or cannot occur under the study’s definitions.
A transition matrix describes allowed pairs; it does not impose a Markov assumption, choose a time scale, or specify how hazards are modeled. Those are separate modeling decisions. Likewise, an NA entry means “not an allowed transition in this specified system,” not “the transition was unobserved in this sample.”
A Short Justification for the Numbering and Checks
Let \(E\) be the set of allowed ordered origin-destination pairs. The matrix assigns one integer to each pair in \(E\), and places NA in every cell outside \(E\). If the list for origin \(r\) contains \(d_r\) destinations, the number of allowed transitions is \(K = \sum_r d_r\). Sequential numbering from 1 through \(K\) gives each allowed pair a unique transition identifier.
Here \(S\) is the number of states and \(t_{rs}\) is the transition number in row \(r\), column \(s\). This gives a practical verification rule: the number of non-NA cells must equal the number of listed arrows, and the non-NA values must be distinct consecutive integers. These checks establish that the encoding is internally consistent; they cannot establish that the chosen arrows are clinically correct.
Write each state label beside its integer index. Use the same order for the list supplied to transMat and for interpreting matrix rows and columns.
For each origin, list every allowed destination once. Use an empty vector for a state with no allowed outgoing transition.
Check the matrix labels, non-NA cells, transition numbers, and the clinical diagram against one another.
Worked Matrix Variations
Worked Example: Adding a Distinct Remission State
Consider a hypothetical four-state process: 1 = Well, 2 = Ill, 3 = Remission, and 4 = Dead. Suppose the diagram allows Well to Ill, Ill to Remission, Remission to Ill, and death from each of the three living states. This is not the same diagram as the standard irreversible illness-death model because it explicitly represents remission and allows illness to recur.
The origin lists, in the stated state order, are c(2, 4) for Well, c(3, 4) for Ill, c(2, 4) for Remission, and c() for Dead. The corresponding R expression is transMat(list(c(2, 4), c(3, 4), c(2, 4), c()), names = c("Well", "Ill", "Remission", "Dead")).
| Origin \ Destination | Well (1) | Ill (2) | Remission (3) | Dead (4) |
|---|---|---|---|---|
| Well (1) | NA | 1 | NA | 2 |
| Ill (2) | NA | NA | 3 | 4 |
| Remission (3) | NA | 5 | NA | 6 |
| Dead (4) | NA | NA | NA | NA |
There are \(2+2+2+0=6\) listed arrows and six numbered entries. The row for Remission contains a transition back to Ill and a transition to Dead; it does not contain a transition to Well. The absence of that arrow is intentional under the stated diagram, rather than an assumption the software makes automatically.
Worked Example: Verifying a Proposed Matrix Against an Arrow List
Suppose a hypothetical team specifies four states in this order: 1 = No illness, 2 = Mild illness, 3 = Severe illness, and 4 = Dead. The permitted arrows are \(1 \to 2\), \(1 \to 4\), \(2 \to 3\), \(2 \to 4\), and \(3 \to 4\). Therefore the origin lists should be c(2, 4), c(3, 4), c(4), and c().
The number of proposed arrows is \(2+2+1+0=5\). The R expression transMat(list(c(2, 4), c(3, 4), c(4), c()), names = c("No illness", "Mild illness", "Severe illness", "Dead")) should consequently yield five numbered cells. Reading by origin and destination order, they are: transition 1, No illness to Mild illness; transition 2, No illness to Dead; transition 3, Mild illness to Severe illness; transition 4, Mild illness to Dead; and transition 5, Severe illness to Dead.
To audit the result, compare each row with its origin list. Row 1 must have numbers under columns 2 and 4, row 2 under columns 3 and 4, row 3 under column 4, and row 4 no numbered entries. The total number of non-NA entries must be 5, and sorting those entries must produce 1, 2, 3, 4, 5. If, for example, row 2 also had a number under column 1, the matrix would contain an extra Mild illness to No illness arrow and would not match the specified system.
Diagnostics, Alternatives, and Common Errors
Useful checks can be done by inspection or with simple R expressions. For an object named tmat, sum(!is.na(tmat)) counts the encoded transitions. sort(tmat[!is.na(tmat)]) should return consecutive integers from 1 to that count. Check that row and column names match the state order and that there are no duplicate state labels. Then compare each numbered cell with a written arrow list or diagram; a count check alone cannot detect a wrongly placed arrow.
For small state systems, manually entering a matrix can be a useful independent check, especially when validating an output from transMat. However, manual entry is more vulnerable to misplaced entries, inconsistent numbering, and confusion between rows and columns. The origin-list approach is concise and makes the outgoing destinations explicit. Neither approach decides which transitions are scientifically justified; that decision must come from the defined state system.
- Reversing rows and columns. Rows are origins and columns are destinations. A number in row 2, column 3 means a transition from state 2 to state 3.
- Confusing state and transition numbers. State 3 is a destination label or index; transition 3 is the identifier assigned to a particular arrow. They need not refer to the same thing.
- Treating missing observations as forbidden arrows. NA encodes a structural restriction in the diagram, not a transition that happened to have zero observed cases.
- Assuming an absorbing state from its name. A state is absorbing in the encoded diagram only when its row contains no permitted outgoing transitions.
- Changing state order without updating interpretation. Reordering states changes the indices used in the origin lists and can change transition numbering. Update labels, lists, and any written transition map together.
The matrix has limits: it records allowed direct transitions, but it does not represent the timing of transitions, establish that every allowed transition occurs in the data, or encode repeated events within a state. If the proposed process needs additional states or a different event-history representation, changing the labels alone will not solve the structural mismatch. Verify that the chosen diagram is the one intended before proceeding.
Check Your Understanding
Answer each question, then compare with the brief solutions below.
- In a three-state matrix, what does an integer in row 1, column 3 represent?
- For the standard illness-death structure with states Well, Ill, and Dead, how many non-NA entries should the matrix contain?
- If the third state has no outgoing transitions, what should its origin list contain?
- Why is it not enough to check only that the matrix has the expected number of numbered cells?
- Does an NA cell mean that no participant in the data made that transition? Explain.
Solutions. (1) A permitted transition from state 1 to state 3. (2) Three: Well to Ill, Well to Dead, and Ill to Dead. (3) An empty vector, c(). (4) The correct number of entries could still be placed in the wrong cells, so each cell must be compared with the intended arrow list. (5) No. NA means the transition is not allowed in the specified state system; it does not describe how often an otherwise allowed transition was observed.