Skip to contents

Discover Sequence Patterns

Source: R/patterns.R
discover_patterns.Rd

Discover various types of patterns in sequence data. Provides n-gram extraction, gapped pattern discovery, analysis of repeated patterns and targeted pattern search. Supports comparison of pattern presence between groups.

Usage

discover_patterns(
  data,
  cols = tidyselect::everything(),
  outcome,
  type = "ngram",
  pattern,
  len = 2:5,
  gap = 1:3,
  min_freq = 2,
  min_support = 0.01,
  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.

outcome

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

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.

pattern

[character(1)]
A specific pattern to search for as a character string (e.g., "A->*->B"). If provided, type is ignored. Supports wildcards * to denote an arbitrary state.

len

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

gap

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

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.

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.

start

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

end

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

contain

[character()]
Filter patterns containing these states.

Value

An object of class patterns which is a tibble with the following columns:

  • pattern: The discovered patterns.

  • length: The length of the pattern.

  • frequency: The number of times the pattern occurs across all sequences.

  • proportion: Frequency divided by the total frequency of patterns of the same length.

  • count: The number of sequences that contain the pattern.

  • support: The proportion of sequences that contain the pattern.

  • lift: the support divided by the product of the supports of the individual states of the pattern. For wildcards, the support is always 1.

In addition, if outcome is provided, additional columns giving the counts in each outcome group, the chi-squared test statistic values (chisq), and p-values (p_value) are included.

Examples

# N-grams
ngrams <- discover_patterns(engagement, type = "ngram")

# Gapped patterns
gapped <- discover_patterns(engagement, type = "gapped")

# Repeated patterns
repeated <- discover_patterns(engagement, type = "repeated")

# Custom pattern with a wildcard state
custom <- discover_patterns(engagement, pattern = "Active->*")