% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/motifs-api.R
\name{motifs}
\alias{motifs}
\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{plot}{cograph_motif_result}(
  x,
  type = c("triads", "types", "significance", "patterns"),
  n = 15,
  ncol = 5,
  colors = c("#2166AC", "#B2182B"),
  ...
)
}
\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}{Pattern filter: "triangle" (default), "network", "closed", "all".}

\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}{Minimum observed count to include a triad (instance mode
only). Default 5 for instances, NULL for census.}

\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{type}{Plot type: "triads" (network diagrams), "types" (bar chart),
"significance" (z-score plot), "patterns" (abstract MAN diagrams).}

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

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

\item{colors}{Colors for visualization. Default blue/red.}

\item{...}{Additional arguments passed to plot helpers.}
}
\value{
A \code{cograph_motif_result} object with:
\describe{
\item{results}{Data frame of results. Census: type, count, (z, p, sig).
Instances: triad, type, observed, (z, p, sig).}
\item{type_summary}{Named counts by MAN type}
\item{level}{Analysis level: "individual" or "aggregate"}
\item{named_nodes}{Whether nodes are identified (TRUE) or exchangeable (FALSE)}
\item{n_units}{Number of units analyzed}
\item{params}{List of parameters used}
}
}
\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{
\dontrun{
# Census from a matrix
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)

if (requireNamespace("tna", quietly = TRUE)) {
  # Census from tna object
  Mod <- tna::tna(tna::group_regulation)
  motifs(Mod)

  # Instances: specific node triples
  subgraphs(Mod)
}
}

}
\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}
