Why expand a multi-state history?
A subject’s follow-up is often stored in wide format: one row per subject, with a column for each event time and event indicator. A transition model, by contrast, needs records that identify the transition being followed, the interval during which the subject was at risk for it, and whether that transition occurred. The R function mstate::msprep performs this expansion for a specified state-transition structure.
The expansion is a data-preparation step, not a fitted model. It does not decide whether the chosen states or transitions are scientifically appropriate, and it cannot repair inconsistent histories. Its output is useful only when the wide data correctly encode each subject’s observed path.
Inputs and alignment with the transition structure
Suppose the process has three states: 1, “well”; 2, “ill”; and 3, “dead.” State 3 is absorbing. The allowed transitions are 1 to 2, 1 to 3, and 2 to 3. A transition matrix can be constructed with mstate::transMat(list(c(2, 3), c(3), c()), names = c("Well", "Ill", "Dead")). The nonzero entries identify allowed transitions and their transition numbers.
For this example, each subject has one wide-format row with an illness time and status, and a death-or-end-of-follow-up time and status. Use time and status vectors aligned with the state labels: msprep(time = c(NA, "illt", "dt"), status = c(NA, "ills", "ds"), data = wide, trans = tmat, id = "id"). Here illt and ills describe entry into state 2, while dt and ds describe entry into state 3. The first vector entries are NA because state 1 is the initial state, not an event destination. If needed, use keep to carry selected subject-level variables into the expanded data.
A status value of 1 indicates that the corresponding destination state was entered at its recorded time; 0 indicates that the subject was censored with respect to that event. In this illness-death example, a subject who dies before becoming ill has illness status 0 and death status 1. Their illness time records the end of their opportunity to become ill—death in this case—not a missing value. A subject censored while well has both statuses 0 and uses their censoring time for both event-time fields. An illness followed by death has illness status 1, and the death time is later than the illness time.
The input should describe observed times on a common time scale from the same origin, with one row per subject and valid 0/1 status indicators. The transition matrix must represent the intended pathways. Event ordering must be possible: for example, a recorded death cannot precede a recorded illness that is marked as having occurred. Simultaneous transitions are generally not meaningful in this simple illness-death setup and require an explicit data or scientific rule rather than an arbitrary ordering.
Worked Example: Expanding Four Illness-Death Histories
Consider these hypothetical follow-up records. Times are measured in years from enrollment. For subjects without illness, illt is the end of their opportunity to become ill. Each status is 1 for an observed event and 0 otherwise.
| id | illt | ills | dt | ds | Observed history |
|---|---|---|---|---|---|
| 1 | 3 | 1 | 8 | 1 | Ill at 3; dead at 8 |
| 2 | 5 | 0 | 5 | 1 | Dead at 5 without prior illness |
| 3 | 4 | 0 | 4 | 0 | Censored at 4 while well |
| 4 | 2 | 1 | 6 | 0 | Ill at 2; censored at 6 |
Using the three-transition structure above, subject 1 contributes three records. For transition 1 to 2, follow-up is from 0 to illness at 3, so Tstart = 0, Tstop = 3, and status = 1. For transition 1 to 3, the subject is at risk only while still well: illness at 3 ends that risk interval, so the record is 0 to 3 with status 0. After illness, subject 1 is at risk for transition 2 to 3 from 3 to death at 8, giving status 1.
Subject 2 contributes two records from 0 to 5: transition 1 to 2 is censored at death (status 0), and transition 1 to 3 occurs (status 1). There is no record for transition 2 to 3, because this subject never entered state 2. Subject 3 contributes two censored records from 0 to 4, one for each transition out of state 1. Subject 4 contributes three records: transition 1 to 2 occurs from 0 to 2; transition 1 to 3 is censored at 2 when illness changes the subject’s state; and transition 2 to 3 is censored from 2 to 6.
Thus the expansion has 10 records in total: three for subject 1, two each for subjects 2 and 3, and three for subject 4. In every record, Tstop − Tstart is nonnegative, and status 1 appears only for the transition that actually occurred at that record’s endpoint. This hand-constructed result is the audit target for the corresponding call to msprep.
Why the intervals have this form
The key logic is that a subject is at risk for a transition only while occupying its origin state. Starting in state 1, the subject can be followed for each allowed transition out of state 1 until the first event that ends residence in state 1. If illness occurs, it is an event for transition 1 to 2 and ends the risk interval for direct death from state 1. The subject then starts a new interval in state 2. If death occurs first, it is an event for transition 1 to 3 and there is no later state-2 interval. Censoring ends observation but does not count as a transition.
This is a bookkeeping consequence of the observed path and transition structure. It explains why the transition 1-to-3 record for someone who becomes ill is censored at illness time, even if the person is observed for years afterward: after illness, that person is no longer in state 1.
Worked Example: Checking an Illness Followed by Censoring
A hypothetical subject has illt = 2.5, ills = 1, dt = 7, and ds = 0. The subject becomes ill at 2.5 years and is censored at 7 years without a recorded death.
The well-state interval for transition 1 to 2 is from 0 to 2.5, with status 1. The well-state interval for transition 1 to 3 is also from 0 to 2.5, but with status 0, because illness—not direct death—ends the time in state 1. The illness-state interval for transition 2 to 3 is from 2.5 to 7, with status 0. Its duration is 7 − 2.5 = 4.5 years. The history is internally consistent because the death-or-censoring time follows the illness time and death status is 0.
Auditing the expanded data
Do not treat successful execution of msprep as proof that the data are correct. Check both the output structure and each subject’s history. A practical audit can be organized as follows.
Confirm that every observed change of state is an allowed transition and that the transition numbers in the output match the intended map.
For each event status of 1, verify that the corresponding time is the actual event time. For status 0, verify that the time is the relevant end of observation for that event.
Confirm Tstart is the time the subject entered the origin state, Tstop is the time that transition-specific observation ended, and Tstop is not earlier than Tstart.
Sort records by Tstart within id. A status-1 transition should lead to the next origin state only if that destination has outgoing transitions and the subject has further observed follow-up.
Count status-1 records by transition and compare with event counts in the wide data. Each observed event should be represented once as an event for its actual transition.
Worked Example: Detecting an Impossible History
Suppose a hypothetical record has illt = 7, ills = 1, dt = 5, and ds = 1. Read literally, this says the subject died at 5 years but became ill at 7 years. The statuses cannot both describe the stated history because death is absorbing and the illness occurs after death.
The correction is not to change the expanded records by hand. Return to the source data and determine which value or status is wrong. If death actually occurred at 5 without illness, the consistent encoding would have illness status 0, illness opportunity ending at 5, death time 5, and death status 1. If illness occurred at 7 and the subject later died, then death time must exceed 7. This check illustrates why subject-level review must precede interpretation of transition-specific output.
Common mistakes, alternatives, and limits
- Using missing illness time for a person who never became ill. The illness time needs to mark the end of that subject’s opportunity to enter state 2, such as death or censoring. A missing value may prevent the routine from constructing the intended risk interval.
- Marking every later death as direct death from the initial state. If illness occurred first, the subject left state 1. The later death is represented on the transition from illness to death, not as an observed 1-to-3 event.
- Mixing time origins. If illness time is measured from enrollment but death time is measured from illness, the intervals cannot be compared as written. Convert the data to a consistent time scale before expansion.
- Assuming msprep validates scientific meaning. Software can expand the supplied columns, but it cannot decide whether an unrecorded event was truly absent or whether the transition graph is clinically sensible.
The main alternative is to construct start-stop records manually. That can be appropriate for a small or unusual state structure, but it is easy to omit a transition-specific censoring record or assign a post-transition event to the wrong origin state. msprep standardizes the expansion for supported wide-format histories; manual construction remains valuable as an independent check. For complex histories, time-varying covariates, recurrent transitions, or unusual observation schemes, verify that the input representation and the function’s assumptions match the data before relying on the output.
The expanded records alone do not establish assumptions needed for later statistical inference. In particular, whether censoring is independent of the event process, possibly conditional on covariates, is a modeling and study-design issue; msprep does not test it. Nor does the function fit transition-specific hazard models, select between model specifications, or produce state-occupancy probabilities. Those are distinct analyses. The practical aim here is narrower: produce a faithful representation of observed histories that those analyses can use.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions below.
- A subject is observed well until death at year 6 and never becomes ill. What are the illness and death status indicators, and what are the two event-time fields?
- A subject becomes ill at year 4 and is censored at year 9. What are the transition-specific intervals and statuses in the illness-death structure?
- Why is a transition 1-to-3 record censored at illness time when the subject later dies?
- What should be investigated if an expanded record has Tstop earlier than Tstart?
Solutions. (1) Illness status is 0 and death status is 1; both the illness-opportunity end time and death time are 6. (2) Transition 1 to 2 runs from 0 to 4 with status 1; transition 1 to 3 runs from 0 to 4 with status 0; transition 2 to 3 runs from 4 to 9 with status 0. (3) Illness ends residence in state 1, so subsequent follow-up is no longer at risk for direct death from state 1; the later death belongs to the illness-to-death transition. (4) Check the original event times, their time origins, the status coding, and the transition map. A negative interval is a signal of inconsistent input or incorrect interpretation, not a duration to accept as valid.