build_mmm() fits a mixture of first-order Markov chains to a set of
sequences by expectation-maximisation: it looks for k subgroups whose
members move between states in different ways, each with its own
transition matrix and initial-state distribution. Every sequence gets a
posterior probability of belonging to each subgroup and is assigned to the
most probable one. Covariates can shape the mixing proportions during
estimation or be related to the subgroups afterwards (see
covariate_effect).
EM finds a local maximum, so the fit is started n_starts times (one
start from k-means on the transition counts, the rest random), each is
screened with a short EM run, the most promising are continued for up to
max_iter iterations, and the one with the highest log-likelihood is
kept. print() reports whether it converged within
max_iter; a fit that did not is not a result. The information criteria
(BIC, AIC, ICL) compare fits with different k – compare_mmm() fits a
range of them – while average posterior probability (AvePP), entropy and
classification error describe how cleanly the sequences separate within
one fit. None of them picks k alone: also check that the subgroups'
transition matrices differ in ways that can be interpreted, and that
each subgroup holds enough sequences to estimate its matrix.
Usage
build_mmm(
data,
k = 2L,
n_starts = 50L,
max_iter = 200L,
tol = 1e-06,
smooth = 0.01,
seed = NULL,
covariates = NULL,
covariate_effect = c("em", "posthoc"),
estimator = c("auto", "firth", "multinom", "chisq")
)
# S3 method for class 'net_mmm'
print(x, digits = 3L, ...)
# S3 method for class 'net_mmm'
summary(object, ...)
# S3 method for class 'net_mmm'
plot(x, type = c("posterior", "covariates"), combined = TRUE, ...)
# S3 method for class 'net_mmm_clustering'
print(x, digits = 3L, ...)
# S3 method for class 'net_mmm_clustering'
plot(
x,
type = c("posterior", "covariates", "predictors"),
combined = TRUE,
...
)Arguments
- data
The sequences: a data frame with one row per sequence and one column per position, a
netobjector barecograph_networkbuilt from sequences, or atnamodel (whose stored states are decoded to their labels). Columns take the same roles as inbuild_network(): an id or a covariate is not a position, and the columns set aside are named in a message and kept as metadata. Association networks (cor,pcor,glasso,ising,mgm) hold variables, not sequences, and raise an error of classnestimate_bad_input.- k
The number of subgroups (mixture components), a whole number of at least 2. Default
2.- n_starts
How many starting configurations to try, a positive whole number. More starts make it likelier that the best local maximum is found. Default
50.- max_iter
The most EM iterations a start may run, a positive whole number. Default
200.- tol
The convergence tolerance: EM stops when the log-likelihood changes by less than this between iterations (with
covariate_effect = "em", also when its relative change does). A finite positive number; default1e-6.- smooth
A pseudo-count added to every transition count before the matrices are estimated, so a transition unseen in a subgroup gets a small probability instead of zero. A finite non-negative number; default
0.01.- seed
An integer that makes the random starts reproducible. Default
NULL. The session's own random stream is left as it was.- covariates
Variables describing each sequence (such as a course or a grade), given as a column name, a character vector of names, a one-sided formula or a data frame, as in
build_clusters(). For anetobject, names are looked up in its metadata first, so a typical call isbuild_mmm(net, k = 3, covariates = "session_label"). How they enter the model is set bycovariate_effect. DefaultNULL.- covariate_effect
How
covariatesenter the model."em"(default) makes the mixing proportions depend on them during EM, so they shape the subgroups found and add(k - 1) * pparameters forpcovariate columns; rows with a missing covariate are dropped first, with a warning."posthoc"fits a plain mixture on every sequence and relates the covariates to the subgroups only afterwards, with a multinomial logit, so neither their values nor their missingness change the subgroups. Ignored withoutcovariates.- estimator
How the after-fit multinomial logit is estimated; it never affects the EM.
"auto"(default) uses Firth's penalised likelihood (brglm2::brmultinom(), finite under separation) when a cell of the subgroup-by-covariate table has fewer than 5 sequences, andnnet::multinom()otherwise."firth"and"multinom"force one of them ("multinom"warns about separation risk), and"chisq"runs descriptive tests instead of a logit.build_clusters()has the details. Ignored withoutcovariates.- x
For the
print()andplot()methods: anet_mmmfit, or thenet_mmm_clusteringattribute of thenetobject_groupbuilt from one.- digits
For the
print()methods: decimal places of the statistics. Default3.- ...
For the
print(),summary()andplot()methods: not used; any extra argument raises an error.- object
For the
summary()method: anet_mmmfit.- type
For the
plot()methods:"posterior"(default), a histogram of each sequence's largest posterior probability, coloured by cluster; or"covariates", a forest plot of the covariate effects, for a model fitted withcovariates. On anet_mmm_clustering,"predictors"is an alias of"covariates".- combined
For the
plot()methods withtype = "covariates":TRUE(default) draws the forest panels as one faceted plot;FALSEreturns a list of ggplots, one per cluster.
Value
A net_mmm object. print() shows the fit statistics,
classification quality and subgroup sizes; summary() adds each
subgroup's transition matrix and returns one row per subgroup (mixing
proportion, sequences assigned, mean posterior, AvePP); plot() draws
the posterior probabilities or the covariate effects;
build_network() turns the fit into one network per subgroup (a
netobject_group); cluster_diagnostics() and session_ids() give the
classification and each sequence's subgroup. The object's fields:
- data
The full N-row sequence frame used for estimation.
- models
List of
netobjects, one per component. Each component carries the rows assigned to that component in its$dataslot, while its transition matrix is the EM-estimated component transition matrix.- k
Number of components.
- mixing
Numeric vector of mixing proportions.
- posterior
N x k matrix of posterior probabilities.
- assignments
Integer vector of hard assignments (1..k).
- quality
List:
avepp(per-class),avepp_overall,entropy,relative_entropy,classification_error,class_entropy.- log_likelihood, BIC, AIC, ICL
Model fit statistics.
- n_params
Number of free parameters behind BIC/AIC/ICL. With
covariate_effect = "em"it grows by(k - 1) * pforpcovariate columns.- iterations, converged
EM iterations used by the retained fit and whether it met
tol.- states
Character vector of state names.
- n_sequences
Number of sequences actually fitted (rows with missing covariates are dropped under
covariate_effect = "em").- covariates
The post-hoc covariate analysis (list), or NULL when
covariates = NULL.- network_method, build_args, htna_partition
Provenance kept from
netobject/ HTNA input so per-cluster networks can be rebuilt the same way; NULL otherwise.- metadata
The
netobject's per-sequence metadata, one row per fitted sequence in the row order ofposterior, sosession_idscan name each sequence; NULL for other input.
The print() methods return their input invisibly. For a model
fitted with covariates, summary() also prints the covariate profiles
and effects and returns, invisibly, a tidy_covariates data frame of
the effects (one row per subgroup other than the reference and per
predictor term, so a factor gives one row per non-reference level; one
row per covariate test with estimator = "chisq"), with the
per-subgroup table as its cluster_stats attribute. The plot()
methods print the plot and return the ggplot invisibly; with
type = "covariates" and combined = FALSE they return, invisibly and
without printing, a list of ggplots named by subgroup.
Initial states
Each sequence's initial state is the value in its first position column,
read as it is: the function does not look ahead to the first observed
state, and it does not convert missing-value symbols as build_clusters()
does. The states are the distinct non-missing values of all position
columns, so a placeholder such as "*" or "%" for an empty cell becomes
a state, and a sequence starting with it starts in that state. Recode such
placeholders to NA first: a missing first position gives the sequence
no initial state, which leaves its subgroup to the transitions alone. Or
trim leading empty cells so every first position holds an observed state.
A one-hot network is different: its units are windows of codes, not positions, so its initial state is the one code active in the first window, and none when that window holds several codes or none.
Methods
print() of a net_mmm shows a header with the numbers of sequences,
subgroups and states, the log-likelihood and the information criteria; a
quality line with the overall AvePP, the normalised entropy (0 when every
sequence is classified with certainty, 1 when all posteriors are equal)
and the classification error (the expected share of sequences
misclassified when each is assigned to its most likely subgroup, the mean
of one minus the largest posterior; Vermunt & Magidson, 2005); a line when the EM did not converge;
and one row per subgroup with its size, mixing proportion and AvePP. For a
model fitted with covariates, a last line names them, says whether they
entered the EM (integrated) or were related post hoc, and gives their
number. The layout follows print() of a net_clustering from
build_clusters(), so dissimilarity-based and model-based clusterings read
alike.
build_network() on a fit, and cluster_network() with
cluster_by = "mmm", return a netobject_group whose "clustering"
attribute is a net_mmm_clustering: the fit without its
subgroup networks. Its print() shows the same quality line,
information criteria and subgroup table, without the state count, the
log-likelihood or the convergence line, and its plot() draws the same
two views as plot() of a net_mmm. The "silhouette", "mds" and
"heatmap" views of a dissimilarity-based clustering need a distance
matrix, which an MMM clustering does not have, so asking for them raises
an error.
References
Helske, S., & Helske, J. (2019). Mixture hidden Markov models for sequence data: The seqHMM package in R. Journal of Statistical Software, 88(3), 1–32. doi:10.18637/jss.v088.i03
Vermunt, J. K., & Magidson, J. (2005). Latent GOLD 4.0 User's Guide. Statistical Innovations.
Examples
seqs <- data.frame(V1 = sample(c("A","B","C"), 30, TRUE),
V2 = sample(c("A","B","C"), 30, TRUE))
mmm <- build_mmm(seqs, k = 2, n_starts = 1, max_iter = 10, seed = 1)
mmm
#> Mixed Markov Model
#> Sequences: 30 | Clusters: 2 | States: 3
#> ICs: LL = -62.330 | BIC = 182.480 | AIC = 158.659 | ICL = 184.652
#> Quality: AvePP = 0.965 | Entropy = 0.212 | Class.Err = 3.5%
#>
#> Cluster N Mix% AvePP
#> 1 24 (80.0%) 78.1% 0.966
#> 2 6 (20.0%) 21.9% 0.961
# \donttest{
seqs <- data.frame(
V1 = sample(LETTERS[1:3], 30, TRUE), V2 = sample(LETTERS[1:3], 30, TRUE),
V3 = sample(LETTERS[1:3], 30, TRUE), V4 = sample(LETTERS[1:3], 30, TRUE)
)
mmm <- build_mmm(seqs, k = 2, seed = 42)
print(mmm)
#> Mixed Markov Model
#> Sequences: 30 | Clusters: 2 | States: 3
#> ICs: LL = -120.823 | BIC = 299.466 | AIC = 275.646 | ICL = 299.990
#> Quality: AvePP = 0.992 | Entropy = 0.035 | Class.Err = 0.8%
#>
#> Cluster N Mix% AvePP
#> 1 12 (40.0%) 40.7% 0.999
#> 2 18 (60.0%) 59.3% 0.987
summary(mmm)
#> Mixed Markov Model
#> Sequences: 30 | Clusters: 2 | States: 3
#> ICs: LL = -120.823 | BIC = 299.466 | AIC = 275.646 | ICL = 299.990
#> Quality: AvePP = 0.992 | Entropy = 0.035 | Class.Err = 0.8%
#>
#> Cluster N Mix% AvePP
#> 1 12 (40.0%) 40.7% 0.999
#> 2 18 (60.0%) 59.3% 0.987
#>
#> --- Cluster 1 (40.7%, n=12) ---
#> A B C
#> A 0.003 0.365 0.632
#> B 0.002 0.001 0.997
#> C 0.176 0.309 0.515
#>
#> --- Cluster 2 (59.3%, n=18) ---
#> A B C
#> A 0.438 0.132 0.430
#> B 0.526 0.473 0.001
#> C 0.396 0.603 0.001
#>
#> component prior n_assigned mean_posterior avepp
#> 1 1 0.407233 12 0.9991433 0.9991433
#> 2 2 0.592767 18 0.9873740 0.9873740
# }