extract_motifs: Extract Motifs from Network Data

In cograph: Analysis and Visualization of Complex Networks

Extract Motifs from Network Data

Description

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
)

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	Minimum total transitions for a person to be included (individual level) or minimum triad weight (aggregate). Default 5.
significance	Logical. Run permutation significance test? Default FALSE.
n_perm	Number of permutations for significance test. Default 100.
seed	Random seed for reproducibility.

Value

A cograph_motif_analysis object (list) containing:

results

Data frame with triad, type, observed count, and (if significance=TRUE) expected, z-score, p-value

type_summary

Summary counts by motif type

params

List of parameters used

level

Analysis level used

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)

See Also

motifs(), subgraphs(), extract_triads(), motif_census()

Other motifs: extract_triads(), get_edge_list(), motif_census(), motifs(), plot.cograph_motif_analysis(), plot.cograph_motifs(), subgraphs(), triad_census()

Examples

## Not run: 
Mod <- tna::tna(tna::group_regulation)

# Basic: triangles only (default) - individual level for tna
m <- extract_motifs(Mod)
print(m)

# Top 20 with significance testing
m <- extract_motifs(Mod, top = 20, significance = TRUE, n_perm = 100)
plot(m)

# From a matrix (aggregate level)
mat <- Mod$weights
m <- extract_motifs(mat)

# Only feed-forward loops
m <- extract_motifs(Mod, include_types = "030T")

# Triangles but exclude cliques
m <- extract_motifs(Mod, pattern = "triangle", exclude_types = "300")

# From data.frame with ID column (individual level)
# df has columns: id, from, to (and optionally weight)
# m <- extract_motifs(data = df, id = "id")
# m <- extract_motifs(data = df, id = c("group", "person"))

## End(Not run)

cograph documentation built on April 1, 2026, 1:07 a.m.