Mark terminal-NA cells with an explicit state label
Source:R/sequence_terminal.R
mark_terminal_state.Rdmark_terminal_state() fills every missing cell after each sequence's
last observed state with an explicit state, "End" by default, and
returns the wide table. This turns right-censored sequences (drop-out,
course end) into data for an absorbing-chain model: in a transition
network built from the result with build_network(), the marked state
is entered once a sequence stops and never left. Internal and leading
missing cells are left as they are, and so are rows observed to the last
position or not at all.
chain_structure() on that network gives the mean time to absorption,
the absorption probabilities and each state's classification.
markov_stability() is not the right summary for an absorbing chain:
its stationary distribution collapses onto the absorbing state.
Arguments
- data
The sequences: a matrix or data frame with one row per actor and one column per position, holding state labels, with
NAfor a missing observation. Withoutcols, the frame must be one column or a numbered run of positions (T1,T2, ...); other columns beside them raise an error of classnestimate_bad_input.- state
The label written into the trailing missing cells, a single non-empty string. Default
"End". If the label already occurs indata, a warning of classnestimate_state_collisionis given and_1,_2, ... is appended until it is unique, so the absorbing marker is never confused with an observed state.- cols
The columns holding the positions, in order; only they are returned. A name not in
dataraises an error of classnestimate_bad_input. DefaultNULL(every column).
Value
A data frame of character columns with the shape of data (or of
its cols), the trailing missing cells filled with the marker. The
label used is kept in the "terminal_state" attribute, which differs
from state when it had to be made unique. The columns are marked as
positions, so build_network() reads them without state_cols.
Details
The marked state is absorbing because each sequence that reaches it
stays there to the last column, so its only observed move is to itself
(P[state, state] = 1 in a "relative" network). That needs at least
one sequence with two or more trailing missing cells: when every
sequence stops at most one cell early, the state has no outgoing
transitions and its row in the network is zero.
Unlike build_network(end = ), which adds an end state only in the cell
after each sequence's last observed state, with no outgoing edges and no
self-loop, this function fills all the trailing cells.
Examples
M <- mark_terminal_state(trajectories, state = "Dropout")
net <- build_network(M, method = "relative")
chain_structure(net)
#> Chain structure [4 states, 2 communicating classes]
#> irreducible: FALSE aperiodic: TRUE regular: FALSE reversible: NA
#> recurrent classes: 1 transient classes: 1
#> absorbing states: Dropout
#>
#> Use summary(x) for the per-state table, plot(x) for the heatmap.