Skip to contents

Build a Heterogeneous Transition Network (HTNA)

Source: R/build_htna.R
build_htna.Rd

Builds a transition network over a combined sequence of two or more actor groups (e.g. Human and AI) and preserves the actor partition on the result so downstream plotting and analysis can treat each actor's codes as a distinct node group.

Usage

build_htna(
  data,
  actor_type = NULL,
  actor = NULL,
  node_groups = NULL,
  action = "code",
  session = "session_id",
  order = "order_in_session",
  method = "relative",
  group = NULL,
  disambiguate = FALSE,
  source_data = NULL,
  ...
)

Arguments

data

Either:

  • A named list of long-format data frames, one per actor type (e.g. list(Human = human_simplified, AI = ai_simplified)). All frames must share the same column schema.

  • A single long-format data frame. In that case either actor_type (row-level actor-type IDs) or node_groups (node-level actor-type lookup) must be supplied.

  • A fitted clustering result from Nestimate::build_clusters(), Nestimate::cluster_mmm() (a net_mmm), or tna::cluster_sequences(), or an already-materialized netobject_group. One HTNA network is returned per sequence cluster. The clustering fit is not rerun; assignments, diagnostics, fitted MMM weights, and actor metadata are preserved.

  • A fitted Nestimate::build_mcml() object. Its node clusters become the HTNA actor groups and one full node-level network is rebuilt from the original source, including transitions between clusters.

actor_type

Character. Name of the column tagging each row's actor type / group (e.g. "Human" vs "AI") when data is a single data frame. Ignored when data is a named list or when node_groups is supplied.

actor

Character. Name of an optional column identifying the individual actor that performed each event (e.g. a learner / user id). Forwarded to build_network with the same semantics; orthogonal to actor_type, which encodes the group/type partition over codes.

node_groups

Node-to-actor-type lookup, in either of two forms:

  • A named list mapping actor-type labels to character vectors of code names, e.g. list(Human = c("Specify", "Command"), AI = c("Plan", "Execute")).

  • A 2-column data frame with one column named after action (the codes) and one other column tagging each code with its actor type, e.g. data.frame(code = c("Specify", "Plan"), actor_type = c("Human", "AI")). The actor-type ordering follows the column's factor levels or, for character vectors, the order of first appearance.

Use node_groups when data is a single long-format frame with no actor-type column and you want to declare the node-to-type partition directly. Each code in data[[action]] must appear in exactly one entry. For clustering inputs, the canonical two-column data.frame(node, group) stored on an existing HTNA model is also accepted. The argument may be omitted when Nestimate preserved the partition from an HTNA input. Mutually exclusive with actor_type. For an mcml input, this optionally overrides $cluster_members; otherwise the fitted membership is used.

action

Character. Name of the action/code column. Default "code".

session

Character. Name of the session column. Default "session_id".

order

Character. Name of the within-session order column. Default "order_in_session".

method

Character. Transition method passed to build_network: "relative" (default), "frequency", "co_occurrence", or "attention". Co-occurrence models are undirected and preserve the same actor partition as transition models.

group

Character. Optional name of a column in data used to split sessions into cohorts (e.g. "cluster"). When supplied, one network is built per group level and the result is a named list of htna networks with class c("htna_group", "netobject_group").

disambiguate

Logical. If FALSE (default), the function errors when a code label appears in more than one actor-type group. If TRUE, codes are prefixed with the actor-type label ("Human:Ask", "AI:Ask") so they become distinct nodes.

source_data

Original node-level data for an mcml input. Usually unnecessary when Nestimate::build_mcml() retained its sequence source. Required when the fitted object has no expandable source, such as an mcml built from a transition matrix or edge list. The fitted macro and within-cluster weights are deliberately not stitched together: rebuilding from this source is what preserves cross-cluster transitions.

...

Additional arguments forwarded to build_network.

Value

A netobject with the actor partition stored in cograph's canonical schema, so cograph::plot_htna(net) auto-detects the groups with no further arguments:

  • $nodes$groups - actor label per node (the column name cograph::plot_htna auto-detects).

  • $node_groups - data frame with columns node and group (canonical cograph_network schema, also readable by cograph::get_groups, cluster_summary, and the print method for cograph_network).

  • $actor_levels - declared actor ordering, also retained as metadata on $node_groups so the table can be passed back to build_htna() without losing that order.

All other slots are exactly as returned by build_network. Clustering inputs return an htna_group; its children retain the actor partition and its outer clustering assignments, posterior probabilities, diagnostics, and other attributes are preserved. An mcml input instead returns one htna, equivalent to Nestimate::as_htna().

See also

build_network, build_tna, plot_htna

Examples

data(human_ai, human_simplified, ai_simplified)

# Form 1: named list of per-actor frames
net <- build_htna(list(Human = human_simplified, AI = ai_simplified))
#> Warning: A network with one long sequence is not recommended and can't be validated using bootstrap and other confirmatory testings.
#> Metadata aggregated per session: ties resolved by first occurrence in 'session_date' (1 sessions), 'cluster' (42 sessions), 'actor_type' (24 sessions)
head(net$node_groups)
#>        node group
#> 1       Ask    AI
#> 2     Check Human
#> 3  Delegate    AI
#> 4   Execute    AI
#> 5 Frustrate Human
#> 6   Inquire Human

# Form 2: single combined frame with a row-level actor-type tag
net <- build_htna(human_ai, actor_type = "actor_type")
#> Warning: A network with one long sequence is not recommended and can't be validated using bootstrap and other confirmatory testings.
#> Metadata aggregated per session: ties resolved by first occurrence in 'session_date' (1 sessions), 'cluster' (42 sessions), 'actor_type' (24 sessions)