pattern_outcome() selects the n sequential patterns most associated
with a two-valued outcome and fits one logistic regression of the
outcome on their presence (or their counts), returning one row per
selected pattern with its log odds ratio, odds ratio and Wald interval.
It reads any sequence data extract_sequences() reads, takes the
outcome from a stored covariate, a vector or each sequence's last state,
and can adjust for covariates and add a random intercept per actor.
Each estimate is the association of one pattern with the outcome,
adjusted for the other selected patterns and the covariates; it is not a
causal effect. The patterns are chosen by their association with the
outcome in the same data the model is fitted to, so the p-values do not
account for that selection and overstate the evidence: treat them as a
ranking, or confirm the selected patterns on new data. A pattern and a
longer pattern containing it often occur together, and each coefficient
is then adjusted for the other; sequence_patterns() shows how often
each pattern occurs, overall and by group.
Usage
pattern_outcome(
x,
outcome = "last_obs",
type = c("ngram", "gapped", "repeated"),
len = 1:2,
gap = 1,
min_freq = 5,
min_support = 0.01,
start = NULL,
end = NULL,
contain = NULL,
n = 10,
priority = "chisq",
desc = TRUE,
occurrences = FALSE,
adjust = NULL,
adjust_length = FALSE,
group = NULL,
reference = NULL,
ci_level = 0.95,
cols = NULL,
actor = NULL,
action = NULL,
time = NULL,
...
)Arguments
- x
The sequence data, in any form
extract_sequences()accepts: prepared data, a long event log, a wide data frame, anetobject,netobject_grouportnamodel.- outcome
The outcome, with exactly two distinct values: the name of a column stored with the sequences (a covariate of a wide data frame or long event log, or of a network's metadata), or a vector with one value per sequence; use a vector for a model that stores no covariates, such as a
tnamodel. The default,"last_obs", uses each sequence's last observed state as the outcome and removes the states that end some sequence from all sequences, as codyna does; it suits data whose final state codes the outcome, such as an appended"pass"or"fail". An outcome without exactly two values, a vector of the wrong length or a column that is not stored with the sequences raises an error of classnestimate_bad_input.- type, len, gap, min_freq, min_support, start, end, contain
The pattern definition and filters; see
sequence_patterns(). The defaults are codyna's:type = "ngram",len = 1:2,gap = 1,min_freq = 5andmin_support = 0.01. When no pattern passes the filters under both outcome values, an error of classnestimate_no_patternsis raised.- n
The number of patterns entered into the model, a positive whole number. Default
10.- priority
The columns ranking the patterns for selection, applied in order:
"chisq"(default),"p_value","support","n_sequences","occurrences","proportion","lift"and"length".- desc
Whether each
prioritycolumn ranks in descending order, recycled to the length ofpriority. DefaultTRUE, so"p_value"needsdesc = FALSEto select the smallest p-values.- occurrences
Whether each pattern enters the model as its number of occurrences in the sequence instead of its presence (0/1). Default
FALSE.- adjust
Covariate columns added to the model. Default
NULL. A name that is not a column stored with the sequences raises an error of classnestimate_bad_input.- adjust_length
Whether to add the number of observed states per sequence as a covariate. Default
FALSE, as in codyna.- group
The column identifying the actor (or other cluster) each sequence belongs to; it adds a random intercept per group. It needs lme4, otherwise an error of class
nestimate_no_lme4is raised. DefaultNULL. A name that is not a column stored with the sequences raises an error of classnestimate_bad_input.- reference
The reference outcome value; the odds ratios are for the other value. Default
NULL, the first value in sorted order; a value that does not occur raises an error of classnestimate_bad_input.- ci_level
The confidence level of the Wald intervals, a number between 0 and 1. Default
0.95.- cols
The state columns of a wide data frame; see
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 selected pattern, ordered by
pattern name, with the columns pattern, length, occurrences,
n_sequences, support and lift (as in sequence_patterns()); the
share of the sequences of each outcome value that contain the pattern
(support_<value>); chisq (the selection statistic); estimate (the
log odds ratio, adjusted for the other terms), std_error, ci_lower,
ci_upper and p_value (Wald z); and odds_ratio, or_lower and
or_upper.
Sequences with a missing outcome, covariate or group are dropped with a
warning of class nestimate_missing_outcome. A selected pattern
collinear with the other terms gets NA estimates (and NA standard
error, intervals, p-value and odds ratios), its descriptive columns
kept, and a warning of class
nestimate_aliased_pattern. Warnings from the model fit (such as
separation) are passed on unchanged.
Details
pattern_outcome() reproduces codyna::analyze_outcome(): the same
pattern discovery and filters, the same ranking and the same model, so
the coefficients agree. The steps:
Patterns are found as in
sequence_patterns()and filtered bymin_freq,min_support,start,endandcontain. Patterns absent from all sequences of one outcome value are dropped.Each pattern gets the chi-square statistic of the number of sequences containing it under each outcome value, against an equal split across the values (codyna's statistic; it does not weight by the size of each outcome group).
The top
npatterns bypriorityenter one model,outcome ~ adjust + pattern_1 + ... + pattern_n, as presence indicators (or occurrence counts withoccurrences = TRUE). Ties keep codyna's order: more occurrences first, then first appearance. Withgroup, a random intercept per group is added (lme4::glmer()); otherwise the model is a plainglm().
References
Saqr, M., Tikka, S., & López-Pernas, S. (2026). codyna: Complex Dynamic Systems. R package version 1.0.0.
Examples
pattern_outcome(group_regulation_long, outcome = "Achiever",
actor = "Actor", action = "Action", time = "Time")
#> pattern length occurrences n_sequences support lift
#> 1 adapt 1 554 475 0.2375 1.00000000
#> 2 adapt->cohesion 2 139 137 0.0685 0.50203839
#> 3 adapt->consensus 2 243 222 0.1110 0.51218457
#> 4 cohesion->cohesion 2 46 42 0.0210 0.06362668
#> 5 consensus->discuss 2 1190 828 0.4140 0.57539458
#> 6 coregulate->discuss 2 539 452 0.2260 0.47258065
#> 7 discuss->adapt 2 282 258 0.1290 0.68884958
#> 8 discuss->consensus 2 1269 880 0.4400 0.61153048
#> 9 emotion->discuss 2 289 267 0.1335 0.22848693
#> 10 synthesis->adapt 2 153 146 0.0730 1.01946408
#> support_High support_Low chisq estimate std_error ci_lower
#> 1 0.145 0.330 72.05263 -0.35794847 0.2848304 -0.9162057
#> 2 0.037 0.100 28.97080 0.14226023 0.2879495 -0.4221105
#> 3 0.068 0.154 33.31532 -0.06048539 0.2541657 -0.5586410
#> 4 0.037 0.005 24.38095 -1.95703140 0.5129015 -2.9622999
#> 5 0.513 0.315 47.34783 -0.84235929 0.1129553 -1.0637476
#> 6 0.179 0.273 19.54867 0.56362598 0.1273555 0.3140139
#> 7 0.047 0.211 104.24806 2.24802414 0.2818028 1.6957007
#> 8 0.545 0.335 50.11364 -0.66382982 0.1135967 -0.8864753
#> 9 0.171 0.096 21.06742 -0.62744477 0.1563031 -0.9337931
#> 10 0.039 0.107 31.67123 1.57967906 0.2981577 0.9953006
#> ci_upper p_value odds_ratio or_lower or_upper
#> 1 0.2003088 2.088596e-01 0.6991091 0.40003400 1.2217800
#> 2 0.7066309 6.212739e-01 1.1528766 0.65566161 2.0271501
#> 3 0.4376702 8.118996e-01 0.9413075 0.57198585 1.5490940
#> 4 -0.9517629 1.358477e-04 0.1412772 0.05169988 0.3860598
#> 5 -0.6209710 8.820688e-14 0.4306932 0.34515988 0.5374223
#> 6 0.8132381 9.616864e-06 1.7570319 1.36890874 2.2551987
#> 7 2.8003476 1.495760e-15 9.4690079 5.45046393 16.4503631
#> 8 -0.4411844 5.104103e-09 0.5148757 0.41210576 0.6432741
#> 9 -0.3210964 5.962671e-05 0.5339544 0.39305994 0.7253533
#> 10 2.1640575 1.169935e-07 4.8533979 2.70553754 8.7063924