% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/motifs-api.R
\name{motifs}
\alias{motifs}
\alias{print.cograph_motif_result}
\alias{plot.cograph_motif_result}
\title{Network Motif Analysis}
\usage{
motifs(
  x,
  named_nodes = FALSE,
  actor = NULL,
  window = NULL,
  window_type = c("rolling", "tumbling"),
  pattern = c("triangle", "network", "closed", "all"),
  include = NULL,
  exclude = NULL,
  significance = TRUE,
  n_perm = 1000L,
  min_count = if (named_nodes) 5L else NULL,
  edge_method = c("any", "expected", "percent"),
  edge_threshold = 1.5,
  min_transitions = 5,
  top = NULL,
  seed = NULL
)

\method{print}{cograph_motif_result}(x, ...)

\method{plot}{cograph_motif_result}(
  x,
  type = c("triads", "types", "significance", "patterns"),
  n = 15,
  ncol = 5,
  colors = c("#2166AC", "#B2182B"),
  node_size = 5,
  label_size = 11,
  title_size = 12,
  stats_size = 13,
  legend_size = 13,
  legend = TRUE,
  motif_color = "#800020",
  spacing = 1,
  base_size = 12,
  combined = TRUE,
  ...
)
}
\arguments{
\item{x}{Input data: a tna object, cograph_network, matrix, igraph, or
data.frame (edge list).}

\item{named_nodes}{Logical. If FALSE (default), performs census (type-level
counts). If TRUE, extracts specific node triples (instance-level).
\code{subgraphs()} is a convenience wrapper that sets this to TRUE.}

\item{actor}{Character. Column name in the edge list metadata to group by.
If NULL (default), auto-detects standard column names (session_id, session,
actor, user, participant). If no grouping column found, performs aggregate
analysis.}

\item{window}{Numeric. Window size for windowed analysis. Splits each actor's
transitions into windows of this size. NULL (default) means no windowing.}

\item{window_type}{Character. Window type: "rolling" (default) or "tumbling".
Only used when \code{window} is set.}

\item{pattern}{Which MAN triad types to include in the analysis:
\describe{
\item{\code{"triangle"}}{(default) Only the 7 closed triangle types:
030C, 030T, 120C, 120D, 120U, 210, 300. Excludes trivial open patterns
(empty triads, single edges, chains, stars, mutual pairs).}
\item{\code{"network"}}{All types except trivially open ones. Excludes
003 (empty), 012 (single edge), 021C (chain).}
\item{\code{"closed"}}{Like \code{"network"} but also excludes 120C
(mixed regulated). Excludes 003, 012, 021C, 120C.}
\item{\code{"all"}}{All 16 MAN types, including empty and trivial patterns.}
}}

\item{include}{Character vector of MAN types to include exclusively.
Overrides \code{pattern}.}

\item{exclude}{Character vector of MAN types to exclude. Applied after
\code{pattern} filter.}

\item{significance}{Logical. Run permutation significance test? Default TRUE.}

\item{n_perm}{Number of permutations for significance. Default 1000.}

\item{min_count}{Inclusive minimum count to keep a row — rows with
\code{count >= min_count} are retained. In instance mode
(\code{named_nodes = TRUE}) this filters the \code{observed} column:
at individual level the number of subjects exhibiting the triad, at
aggregate level the triad's weighted edge mass (sum of its 6 directed
edge weights). In census mode (\code{named_nodes = FALSE}) this filters
the \code{count} column — the number of times each MAN type appears.
Default 5 for instances, NULL for census (no filter).}

\item{edge_method}{Method for determining edge presence: "any" (default),
"expected", or "percent".}

\item{edge_threshold}{Threshold for "expected" or "percent" methods. Default 1.5.}

\item{min_transitions}{Minimum total transitions for a unit to be included.
Default 5.}

\item{top}{Return only the top N results. NULL returns all.}

\item{seed}{Random seed for reproducibility.}

\item{...}{Additional arguments passed to internal plot helpers.}

\item{type}{Plot type:
\describe{
\item{\code{"triads"}}{Network diagrams of specific node triples
(instance mode) or falls back to patterns (census mode). Each panel
title reads \code{"<MAN code>: <description>"} (e.g. \code{"030T:
      Feed-forward"}) and, in census mode, appends the z-score and a
significance star (\code{*} p<.05, \code{**} p<.01, \code{***}
p<.001). Arranged in a grid.}
\item{\code{"types"}}{Bar chart of MAN type frequencies. In census
mode bars are colored by significance direction (see \code{colors});
in instance mode bars use a single fill because per-type
significance would need an aggregation rule across multiple
node-triple rows of the same type.}
\item{\code{"significance"}}{Z-score bars per row of
\code{x$results}. In census mode each bar is one MAN type; in
instance mode each bar is one concrete node-triple, labeled
\code{"<triple> [<MAN code>: <description>]"}. Bars are colored
with the same three-tone rule (see \code{colors}). Requires
\code{significance = TRUE} in the \code{motifs()} call.}
\item{\code{"patterns"}}{Abstract MAN pattern diagrams showing the
edge structure of each triad type. In census mode panel nodes are
filled by significance direction (red sig over / blue sig under /
grey ns); in instance mode panels use a single fill, same reason
as \code{"types"}.}
}}

\item{n}{Maximum number of items to plot. Default 15.}

\item{ncol}{Number of columns in the triad/pattern grid. Default 5.}

\item{colors}{Two-element color vector mapped to a three-tone
significance scale (used by \code{type = "significance"}, plus
\code{type = "types"} and \code{type = "patterns"} in census mode):
\code{colors[1]} fills items that are significantly under-represented
(\code{p < .05} and \code{z < 0}); \code{colors[2]} fills items that
are significantly over-represented (\code{p < .05} and \code{z > 0});
everything else is filled neutral grey (\code{"#9E9E9E"}). Default
\code{c("#2166AC", "#B2182B")} (blue for under, red for over).
When significance was not run, \code{type = "types"} falls back to a
single \code{colors[1]} fill and patterns nodes use \code{colors[1]}.}

\item{node_size}{Triad node radius (relative). Default 5.
(\code{type = "triads"} only.)}

\item{label_size}{Triad node-label font size in points. Default 11.}

\item{title_size}{Per-panel title font size in points. Default 12.}

\item{stats_size}{Per-panel statistics caption font size in points
(e.g., \code{n=34 z=-55.3 p<.001}). Default 13.}

\item{legend_size}{Bottom legend font size in points. Default 13.}

\item{legend}{Logical. Show the abbreviation legend strip below the
triad grid. Default \code{TRUE}. (\code{type = "triads"} only.)}

\item{motif_color}{Color of triad nodes/edges/labels. Default
\code{"#800020"} (deep burgundy). (\code{type = "triads"} only.)}

\item{spacing}{Triangle spread inside each panel; \code{> 1} pulls
nodes inward, \code{< 1} pushes them apart. Default 1.}

\item{base_size}{Base font size for the \code{ggplot2} themes used
by \code{type = "types"} and \code{type = "significance"}.
Default 12.}

\item{combined}{Logical: when TRUE (default) and \code{type = "patterns"}
(or \code{type = "triads"} on unnamed-node input that falls back to
pattern plotting), arrange the per-motif panels in an internal grid via
\code{graphics::par(mfrow=...)}. Set to FALSE to draw into a layout the
caller has already configured (e.g. via \code{\link{panel_layout}()}).}
}
\value{
A \code{cograph_motif_result} object (a list) with:
\describe{
\item{results}{Data frame of results. Census mode
(\code{named_nodes = FALSE}): one row per MAN type with columns
\code{type}, \code{count}, and when \code{significance = TRUE} also
\code{expected}, \code{z}, \code{p}, \code{sig}. Instance mode
(\code{named_nodes = TRUE}): one row per concrete node triple with
columns \code{triad}, \code{type}, \code{observed}, and when
\code{significance = TRUE} also \code{expected}, \code{z}, \code{p},
\code{sig}.}
\item{type_summary}{Named \code{table} of MAN-type counts. In census
mode the values come from the \code{count} column; in instance
mode they come from \code{table(results$type)} and describe how
many concrete node-triples fall under each MAN type. Sorted
descending so \code{plot(., type = "patterns")} draws the most
frequent types first.}
\item{level}{Analysis level: \code{"individual"} when the input
carried per-subject sequence data (\code{tna} with \code{$data},
edge list with an actor column, Nestimate \code{netobject} built
from \code{build_tna()}/similar), otherwise \code{"aggregate"}
(a single transition matrix).}
\item{named_nodes}{Logical mirror of the \code{named_nodes} argument.
Plot helpers gate per-type significance decoration on this so the
instance-mode case (multiple triples per MAN type) doesn't get
silently aggregated.}
\item{n_units}{Number of subjects/units. 1 at aggregate level,
\code{nrow} of the input sequence data at individual level.}
\item{params}{List of the call's parameters (\code{pattern},
\code{edge_method}, \code{edge_threshold}, \code{significance},
\code{n_perm}, \code{min_count}, \code{labels}, \code{n_states},
and the window settings if any). Read by \code{print()} and the
\code{plot()} dispatcher.}
}

Invisibly returns the input \code{x} for \code{"triads"} and
\code{"patterns"}, or the underlying \code{ggplot} for \code{"types"} and
\code{"significance"}.
}
\description{
Two modes of motif analysis for networks:
\itemize{
\item \strong{Census} (\code{named_nodes = FALSE}, default): Counts MAN type
frequencies with significance testing. Nodes are exchangeable.
\item \strong{Instances} (\code{named_nodes = TRUE}, or use \code{subgraphs()}):
Lists specific node triples forming each pattern. Nodes are NOT
exchangeable.
}
}
\details{
Detects input type and analysis level automatically. For inputs with
individual/group data (tna objects, cograph networks from edge lists with
metadata), performs per-group analysis. For aggregate inputs (matrices,
igraph), analyzes the single network.
}
\examples{
# Census from a matrix (no significance test -- fastest path)
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")
motifs(mat, significance = FALSE)

# With a minimal significance test (set n_perm >= 500 in practice)
motifs(mat, n_perm = 10L, seed = 1)

\dontshow{if (requireNamespace("tna", quietly = TRUE)) withAutoprint(\{ # examplesIf}
\donttest{
Mod <- tna::tna(tna::group_regulation)
motifs(Mod, n_perm = 10L, seed = 1)
subgraphs(Mod, n_perm = 10L, seed = 1)
}
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=subgraphs]{subgraphs()}}, \code{\link[=motif_census]{motif_census()}}, \code{\link[=extract_motifs]{extract_motifs()}}

Other motifs: 
\code{\link{extract_motifs}()},
\code{\link{extract_triads}()},
\code{\link{get_edge_list}()},
\code{\link{motif_census}()},
\code{\link{plot.cograph_motif_analysis}()},
\code{\link{plot.cograph_motifs}()},
\code{\link{subgraphs}()},
\code{\link{triad_census}()}
}
\concept{motifs}
