build_mcml() builds a Multi-Cluster Multi-Level (MCML) model from
transitions: it recodes every state to its cluster and counts the
transitions that occur, which gives the Markov chain over clusters (the
macro network) and one network per cluster of the transitions among its
own states. It reads sequences (one row per sequence), event logs (with
action), edge lists (with from and to), tna models and
netobjects that carry their data, and it re-partitions an existing
mcml (see combine and expand). A weight matrix has no transitions to
count, so it is passed to cluster_summary(), which aggregates the
weights instead.
With the defaults (type = "tna", method = "sum"), a macro edge is the
probability that the
next state lies in cluster j given that the current one lies in cluster i;
its diagonal is the probability of staying in a cluster, whether in the
same state or a different one. Both levels depend on the partition, which
is the analyst's: compare a few partitions with combine and expand
rather than reading one. The weights are point estimates;
as_tna()
turns the levels into networks that carry their sequences, so
bootstrap_network() can show how far each edge moves under resampling.
Usage
build_mcml(
x,
clusters = NULL,
method = c("sum", "mean", "median", "max", "min", "density", "geomean"),
type = c("tna", "frequency", "cooccurrence", "raw"),
directed = TRUE,
compute_within = TRUE,
actor = NULL,
action = NULL,
time = NULL,
order = NULL,
session = NULL,
time_threshold = 900,
exclude = NULL,
trim = NULL,
end = FALSE,
end_by = NULL,
labels = NULL,
combine = NULL,
expand = NULL,
from = NULL,
to = NULL,
weight = NULL,
cols = NULL
)
# S3 method for class 'mcml_layer'
print(x, ...)
# S3 method for class 'mcml'
print(x, ...)
# S3 method for class 'mcml'
summary(object, ...)Arguments
- x
The data. Accepted forms:
- data frame with
fromandtoset An edge list: one row per transition, with an optional
weightcolumn.- data frame with
actionset An event log, turned into sequences by
prepare().- data frame of positions
Sequences, one row per sequence and one column per time step: either a numbered run of columns (
T1,T2, ...) and nothing else, or the columns named incols. Each pair of adjacent columns (t, t + 1) whose two states are both observed is a transition; a missing cell breaks the sequence.tnamodelIts stored sequences are decoded and counted; a model without data is passed to
cluster_summary().netobjector barecograph_networkA network of a counting method (
relative,frequency,co_occurrenceand their aliases) is re-counted from the data it carries. A network of another method (such as an association or attention network), a one-hot network, or one without data is passed tocluster_summary(), which aggregates its weights.mcmlReturned unchanged, unless
clusters,combineorexpandchanges its partition: it is then re-estimated from the sequences it carries (seecombine).- square numeric matrix
Passed to
cluster_summary().- non-square or character matrix
Read as sequences.
A data frame that declares no role and is not a numbered run of positions, or whose columns hold only 0 and 1, raises an error of class
nestimate_bad_input. For theprint()methods: anmcmlobject or one of its layers (anmcml_layer).- data frame with
- clusters
The cluster of each state. Accepted forms:
- named list
Cluster names mapped to their states, such as
list(A = c("N1", "N2"), B = c("N3", "N4")).- data frame
State names in the first column, cluster names in the second, such as
data.frame(node = c("N1", "N2", "N3"), group = c("A", "A", "B")).- membership vector
One cluster per state, such as
c("A", "A", "B", "B"), matched to the states of the data in alphabetical order (a named vector is matched by name).- column name
For an edge list only: a column holding each row's cluster, given to both its endpoints. It suits edge lists whose edges never cross clusters; a node that gets two clusters raises an error, so pass a list or a data frame for any other edge list.
NULL(default) Read from a
netobject's node table (a columnclusters,cluster,groupsorgroup) or from itsnode_groups(aligned to the node table by label). The values are then taken in the order of the node table, which must list the states in the orderbuild_network()gives them (alphabetical for sequence data). Other input needs an explicit assignment and raises an error without one.
Every state must belong to exactly one cluster, the
endstate included. On the sequence and edge-list routes the clusters of the result come in alphabetical order.- method
How the transitions between (or within) two clusters are combined into one weight, with
net_aggregate_weights():"sum"(default),"mean","median","max","min","density"or"geomean". On sequences and event logs every transition weighs 1, so only"sum"keeps the counts:"mean","median","max","min"and"geomean"give 1 for every pair of clusters with a transition, and"density"divides each count byn_i * n_j. The other methods suit weighted edge lists and weight matrices, where each row is already a measurement rather than one observation. On sequences and event logs the within-cluster networks likewise get 1 for each observed pair of states under every method but"sum"("density"too, which is not divided byn_i * n_jthere); on an edge list they hold the aggregated weights.- type
How the aggregated counts are turned into weights:
"tna"(default) Each row is normalised to sum to 1, giving first-order Markov transition probabilities.
"raw"The counts as they are.
"frequency"The same counts as
"raw", under the name frequency networks use."cooccurrence"The mean of the count matrix and its transpose (undirected co-occurrence); the result is recorded as undirected.
"semi_markov"raises an error: the package has no semi-Markov (holding-time) construction. For input passed tocluster_summary()(a weight matrix, atnamodel ornetobjectwithout data, or anetobjectof a method that is not a count, such as"attention"or"glasso")typehas no effect; setting it gives a warning for a matrix, or for atnamodel ornetobjectwithout data.- directed
Whether transitions are directed. Default
TRUE.FALSEreplaces the counts by the mean of the count matrix and its transpose beforetypeis applied.- compute_within
Whether to build the within-cluster networks. Default
TRUE. Anmcmlbuilt withFALSEkeeps no per-cluster sequences, so it cannot be re-partitioned (seecombine).- actor, action, time, order, session, time_threshold
For an event log: the columns and the session gap (in seconds, default
900) passed toprepare(), which forms the sequences that are then counted, asprepare(...) |> build_network() |> build_mcml()would. Settingactiondeclares the data an event log.- exclude
States to drop before anything is counted, such as a technical marker. In an event log the matching events are removed before sequences are formed, so a dropped state never takes a position; in wide sequences the matching cells become missing. Default
NULL. Only for wide sequences and event logs: an edge list, anetobjector atnamodel raises an error. The same holds fortrimandend. On an existingmcmlthey raise an error together with a re-partition (clusters,combineorexpand); without one themcmlis returned unchanged and they have no effect (seecombine).- trim
How much of each sequence to keep.
NULL(default) keeps every time step. A fraction in (0, 1) keeps the columns up to that quantile of the sequence lengths (the last observed position of each row), sotrim = 0.95cuts only the longest 5% of sequences; a value of 1 or more keeps that many leading columns (trim = 10keeps the first 10). It changes the data, so it only ever cuts the end of a sequence; the fraction insequence_plot()'strimworks differently because it changes only the drawing.- end
A terminal state put in the cell after each sequence's last observed state.
FALSE(default) adds none,TRUEadds one labelled"End", and a single string adds one with that label; assign it to a cluster inclusters. It is added aftertrim, so trimming never removes it.- end_by
Columns grouping the terminal marker at a coarser unit than the sequence: only the sequence holding each group's last event is marked. For example,
session = "AttemptID", end = "Conclude", end_by = "SkillID"closes each skill once, not each attempt. It needsendand an event log, and raises an error otherwise. DefaultNULL(every sequence is marked).- labels
New display labels for the states of the within-cluster networks, applied after estimation: a two-column data frame (
name,label), a named character vectorc(name = "label")or a named list. States not listed keep their names. The new labels also replace the state names in the cluster membership and the edge table; the macro network keeps its cluster names.- combine, expand
Change the partition.
combinemerges clusters into one: a character vector merges one group, and a list merges several, labelled by its names (default label"A + B"); the merged cluster lists its states in cluster-name order.expandthen splits the named clusters (or every cluster, with"all"orTRUE) into one cluster per state, named by the state. On new input they apply toclusters(in any of its forms, auto-detection included) before estimation, sobuild_mcml(data, clusters = cl, combine = c("A", "B"))equals a build withAandBmerged incl; this works for every input, matrices included. On an existingmcmlthey re-estimate the model (macro network, within-cluster networks and stored sequences) from the sequences it carries, with its originaltype,methodanddirectedunless these are passed; a newclustersdoes the same under that partition, and an unchanged partition returns an equal object. With none ofclusters,combineandexpandthemcmlis returned as it is, and a shaping argument passed with it is ignored with a warning of classnestimate_ignored_argument. Any session split,exclude,trimorendapplied at build time is already in those sequences, so passing one of them (oractor,action,time,order,session,time_threshold,end_by,labels,from,to,weight,cols) with a re-partition raises an error, as does passingclusterstogether withcombineorexpand. Anmcmlbuilt from a matrix, from an edge list (it keeps only the within-cluster edges) or withcompute_within = FALSEraises an error of classnestimate_mcml_no_sequences.sequence_plot()takes the same two arguments as display options: itscombinedraws what it draws forbuild_mcml(x, combine = ), while itsexpandopens clusters in the Summary panel only and keeps one panel per cluster.- from, to, weight
The columns of an edge list: its source, its target and an optional non-negative weight (each transition counts 1 without it). Names give no role: a frame is read as an edge list only when
fromandtoare set, and setting them withactionorcolsraises an error of classnestimate_bad_input.- cols
For a wide data frame: the columns holding the positions, needed when the frame is anything but a numbered run (
T1,T2, ...). DefaultNULL.- ...
For the
print()andsummary()methods: not used; any extra argument raises an error.- object
For
summary(): anmcmlobject.
Value
An mcml object with the layout described under
cluster_summary(). Print it for the type, the method, the node and
cluster counts, the clusters,
the number of transitions between and within clusters and the macro
weights; printing one layer (an mcml_layer) shows its node and edge
counts, weight range, weight matrix, initial probabilities and the size
of the data it carries. summary() returns a data frame with one row
per cluster, with
columns cluster, size, within_total (the total absolute weight of
the within-cluster network, NA when it was not built), between_out
and between_in (the absolute macro weight leaving and entering the
cluster, diagonal excluded); for an undirected macro network, between_out is
the total incident weight and between_in is NA.
as_tna() turns
the levels into a netobject_group, as_htna() rebuilds the
node-level network with its clusters, macro_network() opens chosen
clusters into their states, and sequence_plot() draws the sequences
by cluster. The print() methods return their input invisibly.
On the sequence and edge-list routes, the object differs from the matrix route's in these fields:
- edges
A data frame with one row per observed node-level transition and columns
from,to,weight,cluster_from,cluster_toandtype("within"or"between").- macro
Its
initsare the shares of the clusters among the first-column states (missing cells left out), or the normalised column sums for an edge list; itsdataholds the sequences recoded to cluster labels, or onefrom/torow per transition for an edge list.- clusters
Each layer counts only the transitions between states of its own cluster. Its
initsare the shares of its states among the first-column states that belong to it (normalised column sums for an edge list), and itsdatathe sequences with the states of other clusters set missing (for an edge list, its within-cluster transitions).- meta
sourceis"transitions",typerecords thetypeused, anddirectedwhether the stored weights are directed (FALSEfortype = "cooccurrence").
Input passed to cluster_summary() gives its result: source
"matrix" in meta, and no edge table.
See also
cluster_summary for matrix-based aggregation,
as_tna to promote the layers to netobjects,
macro_network for the cluster-level network with one
cluster expanded
Examples
# Edge list with clusters: its columns are declared
edges <- data.frame(
source = c("A", "A", "B", "C", "C", "D"),
target = c("B", "C", "A", "D", "D", "A"),
count = c(1, 2, 1, 3, 1, 2)
)
clusters <- list(G1 = c("A", "B"), G2 = c("C", "D"))
build_mcml(edges, clusters, from = "source", to = "target", weight = "count")
#> MCML Network
#> ============
#> Type: tna | Method: sum
#> Nodes: 4 | Clusters: 2
#> Transitions: 6
#> Macro: 2 | Per-cluster: 4
#>
#> Clusters:
#> G1 (2): A, B
#> G2 (2): C, D
#>
#> Macro (cluster-level) weights:
#> G1 G2
#> G1 0.5000 0.5000
#> G2 0.3333 0.6667
# Sequence data with clusters
seqs <- data.frame(
T1 = c("A", "C", "B"),
T2 = c("B", "D", "A"),
T3 = c("C", "C", "D"),
T4 = c("D", "A", "C")
)
cs <- build_mcml(seqs, clusters, type = "raw")
cs
#> MCML Network
#> ============
#> Type: raw | Method: sum
#> Nodes: 4 | Clusters: 2
#> Transitions: 9
#> Macro: 3 | Per-cluster: 6
#>
#> Clusters:
#> G1 (2): A, B
#> G2 (2): C, D
#>
#> Macro (cluster-level) weights:
#> G1 G2
#> G1 2 2
#> G2 1 4
summary(cs)
#> cluster size within_total between_out between_in
#> 1 G1 2 2 2 1
#> 2 G2 2 4 1 2
# Change the partition while building ...
three <- build_mcml(seqs, list(G1 = "A", G2 = "B", G3 = c("C", "D")))
build_mcml(seqs, list(G1 = "A", G2 = "B", G3 = c("C", "D")),
combine = c("G1", "G2"))
#> MCML Network
#> ============
#> Type: tna | Method: sum
#> Nodes: 4 | Clusters: 2
#> Transitions: 9
#> Macro: 3 | Per-cluster: 6
#>
#> Clusters:
#> G1 + G2 (2): A, B
#> G3 (2): C, D
#>
#> Macro (cluster-level) weights:
#> G1 + G2 G3
#> G1 + G2 0.5 0.5
#> G3 0.2 0.8
# ... or re-partition an existing mcml: the model is re-estimated
build_mcml(three, combine = c("G1", "G2")) # G1 + G2 as one cluster
#> MCML Network
#> ============
#> Type: tna | Method: sum
#> Nodes: 4 | Clusters: 2
#> Transitions: 9
#> Macro: 3 | Per-cluster: 6
#>
#> Clusters:
#> G1 + G2 (2): A, B
#> G3 (2): C, D
#>
#> Macro (cluster-level) weights:
#> G1 + G2 G3
#> G1 + G2 0.5 0.5
#> G3 0.2 0.8
build_mcml(three, combine = list(AB = c("G1", "G2"))) # named merge
#> MCML Network
#> ============
#> Type: tna | Method: sum
#> Nodes: 4 | Clusters: 2
#> Transitions: 9
#> Macro: 3 | Per-cluster: 6
#>
#> Clusters:
#> AB (2): A, B
#> G3 (2): C, D
#>
#> Macro (cluster-level) weights:
#> AB G3
#> AB 0.5 0.5
#> G3 0.2 0.8
build_mcml(three, expand = "G3") # C and D as clusters
#> MCML Network
#> ============
#> Type: tna | Method: sum
#> Nodes: 4 | Clusters: 4
#> Transitions: 9
#> Macro: 9 | Per-cluster: 0
#>
#> Clusters:
#> C (1): C
#> D (1): D
#> G1 (1): A
#> G2 (1): B
#>
#> Macro (cluster-level) weights:
#> C D G1 G2
#> C 0.0 0.6667 0.3333 0.0
#> D 1.0 0.0000 0.0000 0.0
#> G1 0.0 0.5000 0.0000 0.5
#> G2 0.5 0.0000 0.5000 0.0