encode_sequence_data: Encode Ordered Sequence States

In gp3sequences: Transparent Analysis of Ordered Categorical Sequences

Encode Ordered Sequence States

Description

Creates a deterministic dictionary and adds integer and labelled state codes to long-format sequence data.

Usage

encode_sequence_data(
  data,
  sequence_id_col,
  order_col,
  state_col,
  duration_col = NULL,
  metadata_cols = NULL,
  expected_states = NULL,
  state_levels = NULL,
  prefix = "S",
  width = NULL
)

Arguments

data	A data frame containing ordered state observations.
sequence_id_col	Name of the sequence identifier column.
order_col	Name of the numeric sequence-order column.
state_col	Name of the categorical state column.
duration_col	Optional name of a numeric duration column.
metadata_cols	Optional character vector naming columns that should remain constant within each sequence.
expected_states	Optional vector of known or permitted state values.
state_levels	Optional atomic vector defining the complete state ordering. When omitted, factor levels are respected; otherwise observed state labels are sorted alphabetically.
prefix	Character prefix used for labelled codes.
width	Optional positive integer width for the numeric part of each labelled code. The default is determined from the dictionary size.

Details

The function does not reinterpret states. State codes are transparent identifiers derived from an explicit or deterministic state ordering.

Value

A named list containing:

• data: deterministically sorted canonical data with state_index and state_code;

• dictionary: state labels, integer indices, labelled codes, and an observed-state indicator;

• audit, status, and mapping from input validation;

• settings: the resolved code prefix and width.

Examples

sequences <- data.frame(
  id = c("s1", "s1", "s2", "s2"),
  position = c(1, 2, 1, 2),
  state = c("home", "search", "home", "product")
)

encoded <- encode_sequence_data(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state"
)

encoded$dictionary
encoded$data

gp3sequences documentation built on Aug. 23, 2026, 5:10 p.m.