Skip to contents

Build a Grouped Transition Network Analysis Model

Source: R/clusters.R
group_model.Rd

This function constructs a transition network analysis (TNA) model for each cluster from a given sequence, wide-format dataframe, or a mixture Markov model.

Usage

group_model(x, ...)

# Default S3 method
group_model(
  x,
  group,
  type = "relative",
  scaling = character(0L),
  cols,
  params = list(),
  na.rm = TRUE,
  ...
)

# S3 method for class 'mhmm'
group_model(x, ...)

group_tna(x, ...)

group_ftna(x, ...)

group_ctna(x, ...)

Arguments

x

An stslist object describing a sequence of events or states to be used for building the Markov model. The argument x also accepts data.frame objects in wide format, and tna_data objects. Alternatively, the function accepts a mixture Markov model from seqHMM.

...

Ignored.

group

A vector indicating the cluster assignment of each row of the data / sequence. Must have the same length as the number of rows/sequences of x. Alternatively, a single character string giving the column name of the data that defines the group when x is a wide format data.frame or a tna_data object.

type

A character string describing the weight matrix type. Currently supports the following types:

  • "relative" for relative frequencies (probabilities, the default)

  • "frequency" for frequencies.

  • "co-occurrence" for co-occurrences.

  • "n-gram" for n-gram transitions. Captures higher-order transitions by considering sequences of n states, useful for identifying longer patterns.

  • "gap" allows transitions between non-adjacent states, with transitions weighted by the gap size.

  • "window" creates transitions between all states within a sliding window, capturing local relationships (several sequences together).

  • "reverse" considers the sequences in reverse order (resulting in what is called a reply network in some contexts). The resulting weight matrix is the transpose of the "frequency" option.

scaling

A character vector describing how to scale the weights defined by type. When a vector is provided, the scaling options are applied in the respective order. For example, c("rank", "minmax") would first compute the ranks, then scale them to the unit interval using min-max normalization. An empty vector corresponds to no scaling. Currently supports the following options:

  • "minmax" performs min-max normalization to scale the weights to the unit interval. Note that if the smallest weight is positive, it will be zero after scaling.

  • "max" Multiplies the weights by the reciprocal of the largest weight to scale the weights to the unit interval. This options preserves positive ranks, unlike "minmax" when all weights are positive.

  • "rank" Computes the ranks of the weights using base::rank() with ties.method = "average".

cols

An integer/character vector giving the indices/names of the columns that should be considered as sequence data. Defaults to all columns, i.e., seq(1, ncol(x)). The columns are automatically determined for tna_data objects.

params

A list of additional arguments for models of specific type. The potential elements of this list are:

  • n_gram: An integer for n-gram transitions specifying the number of adjacent events. The default value is 2.

  • max_gap: An integer for the gap-allowed transitions specifying the largest allowed gap size. The default is 1.

  • window_size: An integer for the sliding window transitions specifying the window size. The default is 2.

  • weighted: A logical value. If TRUE, the transitions are weighted by the inverse of the sequence length. Can be used for frequency, co-occurrence and reverse model types. The default is FALSE.

na.rm

A logical value that determines if observations with NA value in group be removed. If FALSE, an additional category for NA values will be added. The default is FALSE and a warning is issued if NA values are detected.

Value

An object of class group_tna which is a list containing one element per cluster. Each element is a tna object.

See also

Cluster-related functions communities(), mmm_stats(), rename_groups()

Examples

group <- c(rep("High", 1000), rep("Low", 1000))
model <- group_model(group_regulation, group = group)

model <- group_model(engagement_mmm)

model <- group_tna(group_regulation, group = gl(2, 1000))

model <- group_ftna(group_regulation, group = gl(2, 1000))

model <- group_ctna(group_regulation, group = gl(2, 1000))