sequence_metrics() computes descriptive indices for every sequence and
returns one row per sequence: length and validity, composition and
diversity, spells, transitions, the fate of the initial state, the
dominant and emergent states, cyclic recurrence and a composite
complexity index, plus the integrative potential of a set of favourable
states when favorable is given. It reads any input
extract_sequences() reads: a wide table of positions, an event log, the
output of prepare(), a sequence network or group of networks, or a
tna model. The indices are those of codyna::sequence_indices(), with
three corrections listed under Details.
The indices describe each sequence as it was observed, and several of
them (spells, transitions, recurrence) rest on few positions in a short
sequence; read them beside valid_n. Because there is one row per
sequence, the result can be summarised, plotted or used as predictors;
sequence_patterns() and pattern_outcome() look at which subsequences
recur and how they relate to an outcome.
Usage
sequence_metrics(
x,
favorable = NULL,
omega = 1,
meta = FALSE,
cols = NULL,
actor = NULL,
action = NULL,
time = NULL,
...
)Arguments
- x
The sequence data, in any form
extract_sequences()accepts.- favorable
The favourable states; giving them adds
integrative_potential. States that do not occur in the data are ignored, and an error of classnestimate_bad_inputis raised when none of them occur. DefaultNULL.- omega
The exponent of the position weights in
integrative_potential; a positive value gives later positions more weight,0weights every position equally and a negative value gives earlier positions more weight; any single finite number is accepted. Ignored withoutfavorable. Default1.- meta
Whether to put each sequence's covariates (actor, session, group, metadata) before the indices. Default
FALSE.- cols
The state columns of a wide data frame, as in
extract_sequences(). DefaultNULL.- actor, action, time
The actor, action and timestamp columns of a long event log, as in
extract_sequences(): settingactiondeclaresxan event log. DefaultNULL.- ...
Further arguments passed to
prepare()for a long event log, such astime_thresholdororder.
Value
A data frame with one row per sequence, in the order of
extract_sequences(), and the columns described in Details
(integrative_potential only with favorable). With meta = TRUE,
the input's covariate columns, if it has any, come first.
Details
Positions after a sequence's last observed state are not part of it;
p below is the position of the last observed state.
- valid_n, valid_proportion
The number of observed states, and their share of the first
ppositions.- unique_states
The number of distinct states.
- mean_spell_duration, max_spell_duration
The mean and the longest run of one state.
- longitudinal_entropy
The Shannon entropy of the state proportions, divided by the log of the number of states in the data (0 to 1; 0 when the data hold one state).
- simpson_diversity
One minus the sum of squared proportions.
- self_loop_tendency, transition_rate
The share of transitions (pairs of adjacent observed states) that repeat the state, and the share that change it; the two sum to 1.
- transition_complexity
The number of distinct state-changing transitions, as a share of the \(a(a - 1)\) possible ones, where \(a\) is the number of states in the data;
NAwhen the data hold one state.- initial_state_persistence
The length of the opening spell as a share of
p.- initial_state_proportion
The share of the observed states that are the first state.
- initial_state_influence_decay
The share of the first third spent in the first state minus the share of the last third.
- cyclic_feedback_strength
The largest share, over lags of 2 or more, of positions whose state recurs that many steps later.
- first_state, last_state, dominant_state, dominant_proportion, dominant_max_spell
The opening and closing states; the most frequent state (ties go to the state that sorts first), its share and its longest spell.
- emergent_state, emergent_state_persistence, emergent_state_proportion
A state that settles in later, its spell and its share;
NAwhen there is none. The candidates are a spell of at least 3 that outlasts the dominant spell, the dominant state when it is not the first and has a spell of at least 3, and a return to the first state in a spell of at least 3 and more than half the opening one; the longest of them is taken.- integrative_potential
With
favorable: the position-weighted share of favourable states over the observed positions, with weightsposition^omega(Brzinsky-Fay 2018).- complexity_index
0.4 * longitudinal_entropy + 0.4 * transition_rate + 0.2 * min(CV of spell durations, 1); 0 for a sequence of one spell (one state, no change). This is codyna's composite, not the complexity index of Gabadinho et al. (2011) thatTraMineR::seqici()computes.
Missing values: a missing position is not an observation. The first
state is the first observed one, a missing position inside a sequence
ends a spell, and a pair of states across it is not a transition.
Indices that are undefined for a sequence (for example a rate with no
transition) are NA; a sequence with no observed state has
valid_n and unique_states 0 and every other index
NA. On sequences without
internal gaps the indices shared with TraMineR (seqindic(),
seqistatd(), seqdur(), seqintegr()) agree exactly;
at an internal gap TraMineR joins the states on either side into one
sequence, so spells and transitions differ there.
Corrections relative to codyna::sequence_indices() 1.0.0, which
otherwise agrees value for value: dominant_max_spell is computed
per sequence (codyna reports the last sequence's value for every row);
longitudinal_entropy is normalised by the log of the number of
states (codyna counts NA as one when the data have missing
values); and complexity_index uses the normalised entropy once
(codyna divides it by the log of the number of states a second time) and
is 0, not NA, for a single spell.
Leading and internal missing values follow the rule above, where codyna
reads position 1 as the first state and counts missing positions as
unfavourable and as possible transitions.
References
Saqr, M., Tikka, S., & López-Pernas, S. (2026). codyna: Complex Dynamic Systems. R package version 1.0.0.
Brzinsky-Fay, C. (2018). Unused resources: Sequence and trajectory indicators. International Symposium on Sequence Analysis and Related Methods, Monte Verità.
Gabadinho, A., Ritschard, G., Müller, N. S., & Studer, M. (2011). Analyzing and visualizing state sequences in R with TraMineR. Journal of Statistical Software, 40(4), 1-37. doi:10.18637/jss.v040.i04
Examples
head(sequence_metrics(trajectories))
#> valid_n valid_proportion unique_states mean_spell_duration max_spell_duration
#> 1 12 1 3 1.714286 4
#> 2 15 1 2 5.000000 9
#> 3 15 1 2 3.750000 8
#> 4 15 1 2 1.875000 5
#> 5 15 1 3 1.875000 3
#> 6 15 1 2 1.666667 3
#> longitudinal_entropy simpson_diversity self_loop_tendency transition_rate
#> 1 0.8734790 0.5694444 0.4545455 0.5454545
#> 2 0.2229449 0.1244444 0.8571429 0.1428571
#> 3 0.3574277 0.2311111 0.7857143 0.2142857
#> 4 0.5793802 0.4444444 0.5000000 0.5000000
#> 5 0.7312088 0.4800000 0.5000000 0.5000000
#> 6 0.5793802 0.4444444 0.4285714 0.5714286
#> transition_complexity initial_state_persistence initial_state_proportion
#> 1 0.6666667 0.08333333 0.5833333
#> 2 0.3333333 0.60000000 0.9333333
#> 3 0.3333333 0.06666667 0.1333333
#> 4 0.3333333 0.33333333 0.6666667
#> 5 0.6666667 0.20000000 0.6666667
#> 6 0.3333333 0.13333333 0.6666667
#> initial_state_influence_decay cyclic_feedback_strength first_state last_state
#> 1 -0.35000000 1.0000000 Active Active
#> 2 0.16666667 1.0000000 Average Average
#> 3 0.03333333 1.0000000 Average Active
#> 4 0.50000000 0.6666667 Active Average
#> 5 0.30000000 0.8000000 Active Average
#> 6 -0.06666667 1.0000000 Average Average
#> dominant_state dominant_proportion dominant_max_spell emergent_state
#> 1 Active 0.5833333 4 Active
#> 2 Average 0.9333333 9 Average
#> 3 Active 0.8666667 8 Active
#> 4 Active 0.6666667 5 Active
#> 5 Active 0.6666667 3 Active
#> 6 Average 0.6666667 3 Average
#> emergent_state_persistence emergent_state_proportion complexity_index
#> 1 4 0.5833333 0.7138228
#> 2 5 0.9333333 0.3063208
#> 3 8 0.8666667 0.4102016
#> 4 3 0.6666667 0.5872441
#> 5 3 0.6666667 0.5981935
#> 6 3 0.6666667 0.5642465
head(sequence_metrics(trajectories, favorable = "Active"))
#> valid_n valid_proportion unique_states mean_spell_duration max_spell_duration
#> 1 12 1 3 1.714286 4
#> 2 15 1 2 5.000000 9
#> 3 15 1 2 3.750000 8
#> 4 15 1 2 1.875000 5
#> 5 15 1 3 1.875000 3
#> 6 15 1 2 1.666667 3
#> longitudinal_entropy simpson_diversity self_loop_tendency transition_rate
#> 1 0.8734790 0.5694444 0.4545455 0.5454545
#> 2 0.2229449 0.1244444 0.8571429 0.1428571
#> 3 0.3574277 0.2311111 0.7857143 0.2142857
#> 4 0.5793802 0.4444444 0.5000000 0.5000000
#> 5 0.7312088 0.4800000 0.5000000 0.5000000
#> 6 0.5793802 0.4444444 0.4285714 0.5714286
#> transition_complexity initial_state_persistence initial_state_proportion
#> 1 0.6666667 0.08333333 0.5833333
#> 2 0.3333333 0.60000000 0.9333333
#> 3 0.3333333 0.06666667 0.1333333
#> 4 0.3333333 0.33333333 0.6666667
#> 5 0.6666667 0.20000000 0.6666667
#> 6 0.3333333 0.13333333 0.6666667
#> initial_state_influence_decay cyclic_feedback_strength first_state last_state
#> 1 -0.35000000 1.0000000 Active Active
#> 2 0.16666667 1.0000000 Average Average
#> 3 0.03333333 1.0000000 Average Active
#> 4 0.50000000 0.6666667 Active Average
#> 5 0.30000000 0.8000000 Active Average
#> 6 -0.06666667 1.0000000 Average Average
#> dominant_state dominant_proportion dominant_max_spell emergent_state
#> 1 Active 0.5833333 4 Active
#> 2 Average 0.9333333 9 Average
#> 3 Active 0.8666667 8 Active
#> 4 Active 0.6666667 5 Active
#> 5 Active 0.6666667 3 Active
#> 6 Average 0.6666667 3 Average
#> emergent_state_persistence emergent_state_proportion integrative_potential
#> 1 4 0.5833333 0.62820513
#> 2 5 0.9333333 0.08333333
#> 3 8 0.8666667 0.90833333
#> 4 3 0.6666667 0.56666667
#> 5 3 0.6666667 0.59166667
#> 6 3 0.6666667 0.00000000
#> complexity_index
#> 1 0.7138228
#> 2 0.3063208
#> 3 0.4102016
#> 4 0.5872441
#> 5 0.5981935
#> 6 0.5642465