% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build_network.R
\name{build_network}
\alias{build_network}
\title{Build a Network}
\usage{
build_network(
  data,
  method,
  actor = NULL,
  action = NULL,
  time = NULL,
  session = NULL,
  order = NULL,
  codes = NULL,
  group = NULL,
  format = "auto",
  window_size = 3L,
  mode = c("non-overlapping", "overlapping"),
  scaling = NULL,
  threshold = 0,
  level = NULL,
  time_threshold = 900,
  predictability = TRUE,
  params = list(),
  ...
)
}
\arguments{
\item{data}{Data frame (sequences or per-observation frequencies) or a
square symmetric matrix (correlation or covariance).}

\item{method}{Character. Required. Name of a registered estimator.
Built-in methods: \code{"relative"}, \code{"frequency"},
\code{"co_occurrence"}, \code{"cor"}, \code{"pcor"}, \code{"glasso"}.
Aliases: \code{"tna"} and \code{"transition"} map to \code{"relative"};
\code{"ftna"} and \code{"counts"} map to \code{"frequency"};
\code{"cna"} maps to \code{"co_occurrence"};
\code{"corr"} and \code{"correlation"} map to \code{"cor"};
\code{"partial"} maps to \code{"pcor"};
\code{"ebicglasso"} and \code{"regularized"} map to \code{"glasso"}.}

\item{actor}{Character. Name of the actor/person ID column for sequence
grouping. Default: \code{NULL}.}

\item{action}{Character. Name of the action/state column (long format).
Default: \code{NULL}.}

\item{time}{Character. Name of the time column (long format).
Default: \code{NULL}.}

\item{session}{Character. Name of the session column. Default: \code{NULL}.}

\item{order}{Character. Name of the ordering column. Default: \code{NULL}.}

\item{codes}{Character vector. Column names of one-hot encoded states
(for onehot format). Default: \code{NULL}.}

\item{group}{Character. Name of a grouping column for per-group networks.
Returns a \code{netobject_group} (named list of netobjects).
Default: \code{NULL}.}

\item{format}{Character. Input format: \code{"auto"}, \code{"wide"},
\code{"long"}, or \code{"onehot"}. Default: \code{"auto"}.}

\item{window_size}{Integer. Window size for one-hot windowing.
Default: \code{3L}.}

\item{mode}{Character. Windowing mode: \code{"non-overlapping"} or
\code{"overlapping"}. Default: \code{"non-overlapping"}.}

\item{scaling}{Character vector or NULL. Post-estimation scaling to apply
(in order). Options: \code{"minmax"}, \code{"max"}, \code{"rank"},
\code{"normalize"}. Can combine: \code{c("rank", "minmax")}.
Default: \code{NULL} (no scaling).}

\item{threshold}{Numeric. Absolute values below this are set to zero in the
result matrix. Default: 0 (no thresholding).}

\item{level}{Character or NULL. Multilevel decomposition for association
methods. One of \code{NULL}, \code{"between"}, \code{"within"},
\code{"both"}. Requires \code{id_col}. Default: \code{NULL}.}

\item{time_threshold}{Numeric. Maximum time gap (seconds) for long format
session splitting. Default: \code{900}.}

\item{predictability}{Logical. If \code{TRUE} (default), compute and store
node predictability (R-squared) for undirected association methods
(glasso, pcor, cor). Stored in \code{$predictability} and auto-displayed
as donuts by \code{cograph::splot()}.}

\item{params}{Named list. Method-specific parameters passed to the estimator
function (e.g. \code{list(gamma = 0.5)} for glasso, or
\code{list(format = "wide")} for transition methods). This is the key
composability feature: downstream functions like bootstrap or grid search
can store and replay the full params list without knowing method internals.}

\item{...}{Additional arguments passed to the estimator function.}
}
\value{
An object of class \code{c("netobject", "cograph_network")} containing:
\describe{
\item{data}{The input data used for estimation, as a data frame.}
\item{weights}{The estimated network weight matrix.}
\item{nodes}{Data frame with columns \code{id}, \code{label}, \code{name},
\code{x}, \code{y}. Node labels are in \code{$nodes$label}.}
\item{edges}{Data frame of non-zero edges with integer \code{from}/\code{to}
(node IDs) and numeric \code{weight}.}
\item{directed}{Logical. Whether the network is directed.}
\item{method}{The resolved method name.}
\item{params}{The params list used (for reproducibility).}
\item{scaling}{The scaling applied (or NULL).}
\item{threshold}{The threshold applied.}
\item{n_nodes}{Number of nodes.}
\item{n_edges}{Number of non-zero edges.}
\item{level}{Decomposition level used (or NULL).}
\item{meta}{List with \code{source}, \code{layout}, and \code{tna} metadata
(cograph-compatible).}
\item{node_groups}{Node groupings data frame, or NULL.}
\item{predictability}{Named numeric vector of R-squared predictability
values per node (for undirected association methods when
\code{predictability = TRUE}). NULL for directed methods.}
}
Method-specific extras (e.g. \code{precision_matrix}, \code{cor_matrix},
\code{frequency_matrix}, \code{lambda_selected}, etc.) are preserved
from the estimator output.

When \code{level = "both"}, returns an object of class
\code{"netobject_ml"} with \code{$between} and \code{$within}
sub-networks and a \code{$method} field.
}
\description{
Universal network estimation function that supports both transition
networks (relative, frequency, co-occurrence) and association networks
(correlation, partial correlation, graphical lasso). Uses the global
estimator registry, so custom estimators can also be used.
}
\details{
The function works as follows:
\enumerate{
\item Resolves method aliases to canonical names.
\item Retrieves the estimator function from the global registry.
\item For association methods with \code{level} specified, decomposes
the data (between-person means or within-person centering).
\item Calls the estimator: \code{do.call(fn, c(list(data = data), params))}.
\item Applies scaling and thresholding to the result matrix.
\item Extracts edges and constructs the \code{netobject}.
}
}
\examples{
seqs <- data.frame(V1 = c("A","B","C","A"), V2 = c("B","C","A","B"))
net <- build_network(seqs, method = "relative")
net
\donttest{
# Transition network (relative probabilities)
seqs <- data.frame(
  V1 = sample(LETTERS[1:4], 30, TRUE), V2 = sample(LETTERS[1:4], 30, TRUE),
  V3 = sample(LETTERS[1:4], 30, TRUE), V4 = sample(LETTERS[1:4], 30, TRUE)
)
net <- build_network(seqs, method = "relative")
print(net)

# Association network (glasso)
freq_data <- convert_sequence_format(seqs, format = "frequency")
net_glasso <- build_network(freq_data, method = "glasso",
                             params = list(gamma = 0.5, nlambda = 50))

# With scaling
net_scaled <- build_network(seqs, method = "relative",
                             scaling = c("rank", "minmax"))
}

}
\seealso{
\code{\link{register_estimator}}, \code{\link{list_estimators}},
\code{\link{bootstrap_network}}
}
