Skip to contents

Analyze Pattern-Outcome Relationships

Source: R/patterns.R
analyze_outcome.Rd

Fit a (mixed) logistic regression model to the data using sequence patterns as predictors. The patterns are first determined using discover_patterns() and used as predictors as specified by the user (either frequency or presence). The user can further select the maximum number of patterns to use and how to prioritize the patterns (frequency, support, lift, etc.). Additional covariates and random effects can also be included in the model. The logistic model is fitted using stats::glm() or by lme4::glmer() in the case of a mixed model.

Usage

analyze_outcome(
  data,
  cols = tidyselect::everything(),
  group = NULL,
  outcome = "last_obs",
  reference,
  n = 10,
  freq = FALSE,
  priority = "chisq",
  desc = TRUE,
  formula = ~1,
  re_formula,
  mixed = TRUE,
  type = "ngram",
  len = 1:2,
  gap = 1,
  min_support = 0.01,
  min_freq = 5,
  start,
  end,
  contain,
  ...
)

Arguments

data

[data.frame]
Sequence data in wide format (rows are sequences, columns are time points). The input should be coercible to a data.frame object.

cols

[tidy-select]
A tidy selection of columns that should be considered as sequence data. By default, all columns are used.

group

[tidy-select]
An optional tidy selection of columns that define the grouping factors. If provided, group-specific random effects can be specified via re_formula. The default value NULL disables grouping and a fixed-effects model is fitted instead.

outcome

[character(1), vector()]
Outcome variable specification. The option "last_obs" assumes that the last non-missing observation of each sequence specifies the outcome. Alternatively, a column name of data or a vector with the same length as the number of rows of data.

reference

[character(1)]
The name of the outcome class to be taken as the reference. The probability of the other class is modeled. If not provided, uses the first class in lexicographic order.

n

[integer(1)]
Maximum number of patterns to include in the model as covariates. The default is 10.

freq

[logical()]
Should the pattern frequency be used as a predictor?. If FALSE (the default), instead defines a binary predictor that attains the value 1 if the pattern is present in the sequence and 0 otherwise.

priority

[character(): "chisq"]
Criteria giving the priority of pattern inclusion in the model. Multiple criteria can be selected simultaneously. The available options are the column names of the return object of discover_patterns(), excluding pattern.

desc

[logical(), TRUE]
A logical vector of the same length as priority that defines which criteria should be evaluated in descending order of magnitude. Automatically recycled if the lengths do not match.

formula

[formula]
Formula specification for the fixed effects of the non-pattern covariates. The default is ~ 1, adding no covariates.

re_formula

[formula]
Formula specification of the random effects when group is provided. By default, a random intercept is added for each grouping variable in group.

mixed

[logical(1)]
Should a mixed model be fitted when group is provided? (default: TRUE)

type

[character(1): "ngram"]
The pattern type to analyze:

  • "ngram": Extract contiguous n-grams.

  • "gapped": Discover patterns with gaps/wildcards.

  • "repeated": Detect repeated occurrences of the same state.

len

[integer(): 1:2]
Pattern lengths to consider for n-grams and repeated patterns.

gap

[integer(): 1]
Gap sizes to consider for gapped patterns.

min_support

[integer(1): 0.01]
Minimum support threshold, i.e., the proportion of sequences that must contain a specific pattern for the pattern to be included.

min_freq

[integer(1): 2L]
Minimum pattern frequency threshold, i.e., the number of times a pattern must occur across all sequences for it to be included.

start

[character()]
Filter patterns starting with these states.

end

[character()]
Filter patterns ending with these states.

contain

[character()]
Filter patterns containing these states.

...

Additional arguments passed to discover_patterns() and the model-fitting function (stats::glm() or lme4::glmer()).

Value

Either a glm or a glmerMod object depending on whether random effects were included.

Examples

fit <- analyze_outcome(engagement, outcome = rep(1:2, each = 500))
summary(fit)
#> 
#> Call:
#> glm(formula = f, family = binomial, data = df)
#> 
#> Coefficients:
#>                          Estimate Std. Error z value Pr(>|z|)  
#> (Intercept)              -0.35284    0.53815  -0.656   0.5120  
#> Average                  -0.31300    0.42069  -0.744   0.4569  
#> Disengaged                0.33727    0.34574   0.976   0.3293  
#> Active_to_Active          0.18548    0.38447   0.482   0.6295  
#> Average_to_Average        0.09155    0.17088   0.536   0.5921  
#> Active_to_Disengaged      0.12652    0.15329   0.825   0.4092  
#> Average_to_Disengaged     0.30276    0.15745   1.923   0.0545 .
#> Disengaged_to_Average    -0.05845    0.19382  -0.302   0.7630  
#> Disengaged_to_Disengaged -0.40839    0.24822  -1.645   0.0999 .
#> Active_to_Average         0.39736    0.15731   2.526   0.0115 *
#> Disengaged_to_Active     -0.08686    0.15715  -0.553   0.5805  
#> ---
#> Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
#> 
#> (Dispersion parameter for binomial family taken to be 1)
#> 
#>     Null deviance: 1386.3  on 999  degrees of freedom
#> Residual deviance: 1370.2  on 989  degrees of freedom
#> AIC: 1392.2
#> 
#> Number of Fisher Scoring iterations: 4
#>