Extract Motifs from Network Data

Extract and analyze triad motifs from network data with flexible filtering, pattern selection, and statistical significance testing. Supports both individual-level analysis (with tna objects or grouped data) and aggregate analysis (with matrices or networks).

Usage

extract_motifs(
  x = NULL,
  data = NULL,
  id = NULL,
  level = NULL,
  edge_method = c("any", "expected", "percent"),
  edge_threshold = 1.5,
  pattern = c("triangle", "network", "closed", "all"),
  exclude_types = NULL,
  include_types = NULL,
  top = NULL,
  by_type = FALSE,
  min_transitions = 5,
  significance = FALSE,
  n_perm = 100,
  seed = NULL
)

# S3 method for class 'cograph_motif_analysis'
print(x, n = 20, ...)

Arguments

x

Input data. Can be:

A tna object (supports individual-level analysis)
A matrix (aggregate analysis only, unless data and id provided)
A cograph_network object
An igraph object

data

Optional data.frame containing transition data with an ID column for individual-level analysis. Required columns: from, to, and the column(s) specified in id. If provided, x should be NULL or a matrix of node labels.

id

Column name(s) identifying individuals/groups in data. Can be a single string or character vector for multiple grouping columns. Required for individual-level analysis with non-tna inputs.

level

Analysis level: "individual" counts how many people have each triad, "aggregate" analyzes the summed/single network. Default depends on input: "individual" for tna or when id provided, "aggregate" otherwise.

edge_method

Method for determining edge presence:

"any": Edge exists if count > 0 (simple, recommended)
"expected": Edge exists if observed/expected >= threshold
"percent": Edge exists if edge/total >= threshold

Default "any".

edge_threshold

Threshold value for "expected" or "percent" methods. For "expected", a ratio (e.g., 1.5 means 50\ The default 1.5 is calibrated for this method. For "percent", a proportion (e.g., 0.15 for 15\ When using "percent", set this explicitly (e.g., 0.15). Ignored when edge_method = "any". Default 1.5.

pattern

Pattern filter for which triads to include:

"triangle": All 3 node pairs must be connected (any direction). Types: 030C, 030T, 120C, 120D, 120U, 210, 300. Default.
"network": Exclude simple sequential patterns (chains/single edges). Excludes: 003, 012, 021C. Includes stars and triangles.
"closed": Network without chain patterns. Excludes: 003, 012, 021C, 120C. Similar to network but also removes mutual+chain (120C).
"all": Include all 16 MAN types, no filtering.

exclude_types

Character vector of MAN types to explicitly exclude. Applied after pattern filter. E.g., c("300") to exclude cliques.

include_types

Character vector of MAN types to exclusively include. If provided, only these types are returned (overrides pattern/exclude).

top

Return only the top N results (by observed count or z-score). NULL returns all results. Default NULL.

by_type

If TRUE, group results by MAN type in output. Default FALSE.

min_transitions

At individual level: minimum total transitions for a person to be included in the analysis. At aggregate level: minimum triad weight to count as present. Default 5.

significance

Logical. Run permutation significance test? Default FALSE.

n_perm

Number of permutations for the significance test. When significance = TRUE, must be a whole number of at least 2. Default 100.

seed

Random seed for reproducibility.

n

Number of motif rows to print.

...

Passed to methods; currently unused.

Value

A cograph_motif_analysis object (list) containing:

results: Data frame with one row per node-triple and MAN type, the display label triad, unambiguous node1/node2/ node3 columns, its observed count, and (if significance = TRUE) expected count, z-score, empirical p-value, and significance marker. A node triple that has different types across individuals therefore appears in more than one row.
type_summary: Summary counts by motif type across individuals.
params: List of parameters used

Details

Individual significance uses the same directed weighted stub-matching null as individual-level motifs(): positive weights retain at least one integer stub, shuffled targets preserve the integerized in/out margins, and generated loops/parallel edges are reduced to a simple loopless projection for triad classification. Observed self-loops are excluded before activity gating, counting, and null construction.

MAN Notation

The 16 triad types use MAN (Mutual-Asymmetric-Null) notation where:

First digit: number of Mutual (bidirectional) pairs
Second digit: number of Asymmetric (one-way) pairs
Third digit: number of Null (no edge) pairs
Letter suffix: subtype variant (C=cycle, T=transitive, D=down, U=up)

Pattern Types

Triangle patterns (all pairs connected):: 030C (cycle), 030T (feed-forward), 120C (regulated cycle), 120D (two out-stars), 120U (two in-stars), 210 (mutual+asymmetric), 300 (clique)
Network patterns (has structure):: 021D (out-star), 021U (in-star), 102 (mutual pair), 111D (out-star+mutual), 111U (in-star+mutual), 201 (mutual+in-star), plus all triangle patterns
Sequential patterns (chains):: 012 (single edge), 021C (A->B->C chain)
Empty:: 003 (no edges)

Examples

# Small aggregate example -- no significance test for speed
mat <- matrix(c(0,3,2,0, 0,0,5,1, 0,0,0,4, 2,0,0,0), 4, 4, byrow = TRUE)
rownames(mat) <- colnames(mat) <- c("Plan","Execute","Monitor","Adapt")
m <- extract_motifs(mat, significance = FALSE)
print(m)
#> Motif Analysis
#> Pattern: triangle | Edge method: any
#> Individuals: 1 | States: 4 | Total triads: 4
#> 
#> Type distribution:
#> 
#> 030C 030T 
#>    2    2 
#> 
#> Top 4 triads:
#>                       triad type observed
#> 1    Plan - Execute - Adapt 030C        1
#> 2    Plan - Monitor - Adapt 030C        1
#> 3 Execute - Monitor - Adapt 030T        1
#> 4  Plan - Execute - Monitor 030T        1

# \donttest{
Mod <- tna::tna(tna::group_regulation)
# Individual-level from tna -- keep n_perm tiny for example speed
extract_motifs(Mod, top = 10, significance = TRUE, n_perm = 10L, seed = 1)
#> Motif Analysis
#> Pattern: triangle | Edge method: any
#> Individuals: 2000 | States: 9 | Total triads: 10
#> 
#> Type distribution:
#> 
#> 120C 030C 030T  210 120U 120D  300 
#> 1481 1044  620  581  190  178   79 
#> 
#> Top 10 triads:
#>                               triad type observed expected     z sig
#> 1         adapt - discuss - monitor 120D        2      0.0    NA    
#> 2       adapt - discuss - synthesis 120U        1      0.0    NA    
#> 3    cohesion - consensus - emotion 030T       57     11.0 24.40    
#> 4   consensus - discuss - synthesis 120C       82     19.6 15.69    
#> 5     consensus - coregulate - plan 120C      172     71.5 15.62    
#> 6       adapt - discuss - synthesis 030T       11      0.8 12.93    
#> 7       adapt - discuss - synthesis 120C        7      0.6 12.39    
#> 8    cohesion - consensus - emotion 120C       98     32.6 12.07    
#> 9   consensus - discuss - synthesis 030C       59     17.6 10.71    
#> 10 consensus - coregulate - emotion 030C       74     35.3 10.34    
# Filter to feed-forward loops only
extract_motifs(Mod, include_types = "030T", significance = FALSE)
#> Motif Analysis
#> Pattern: triangle | Edge method: any
#> Individuals: 2000 | States: 9 | Total triads: 59
#> 
#> Type distribution:
#> 030T 
#>  620 
#> 
#> Top 20 triads:
#>                                triad type observed
#> 1     cohesion - consensus - emotion 030T       57
#> 2           discuss - emotion - plan 030T       33
#> 3   consensus - coregulate - discuss 030T       32
#> 4        coregulate - emotion - plan 030T       27
#> 5  cohesion - consensus - coregulate 030T       26
#> 6    consensus - discuss - synthesis 030T       26
#> 7      consensus - coregulate - plan 030T       23
#> 8     cohesion - consensus - discuss 030T       22
#> 9      consensus - discuss - emotion 030T       22
#> 10        consensus - emotion - plan 030T       22
#> 11          discuss - monitor - plan 030T       21
#> 12  consensus - coregulate - monitor 030T       20
#> 13      cohesion - discuss - emotion 030T       19
#> 14    coregulate - discuss - emotion 030T       18
#> 15       adapt - consensus - discuss 030T       17
#> 16       coregulate - discuss - plan 030T       17
#> 17         cohesion - emotion - plan 030T       17
#> 18     consensus - discuss - monitor 030T       14
#> 19        consensus - monitor - plan 030T       13
#> 20  consensus - coregulate - emotion 030T       12
# }