Tidy per-actor endpoint summary of a wide-format sequence dataset
Source:R/sequence_terminal.R
actor_endpoints.Rdactor_endpoints() returns one row per sequence (actor) of a
wide-format sequence table, with its first and last observed states, the
positions where they occur, the number of observed cells and whether the
sequence ends early. A sequence ends early (dropped_out) when its last
observed state comes before the last column, so every cell after it is
missing: the terminal-NA pattern of drop-out, course end or censoring.
Internal gaps do not count.
The flag records only where the observations stop; it cannot say why.
A sequence recorded over fewer positions than the others looks the same
as one that left. mark_terminal_state() turns the terminal-NA cells
into an explicit end state, and chain_structure() then describes the
chain with that 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, every column is read as a position, so the frame must be one column or a numbered run of positions (T1,T2, ...); a frame with other columns beside them, such as an id, raises an error of classnestimate_bad_input. A table frommark_terminal_state()ormark_first_state()is read as it is, because those functions mark their columns as positions.- cols
The columns holding the positions, in order; the other columns are ignored. A name not in
dataraises an error of classnestimate_bad_input. DefaultNULL(every column).
Value
A data frame with one row per actor and the columns:
actorThe row name when
datahas row names other than1,2, ...; otherwise the row number.first_state,last_stateThe first and the last observed state.
first_step,last_stepThe positions (column numbers among the position columns) of the first and the last observed state.
n_observedThe number of observed cells.
dropped_outTRUEwhenlast_stepis before the last column, so the row ends in missing cells.
A row with no observed state has NA states and steps, n_observed
0 and dropped_out FALSE.
Examples
actor_endpoints(trajectories) |> head()
#> actor first_state last_state first_step last_step n_observed dropped_out
#> 1 1 Active Active 1 12 12 TRUE
#> 2 2 Average Average 1 15 15 FALSE
#> 3 3 Average Active 1 15 15 FALSE
#> 4 4 Active Average 1 15 15 FALSE
#> 5 5 Active Average 1 15 15 FALSE
#> 6 6 Average Average 1 15 15 FALSE