% 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,
  state_cols = NULL,
  metadata_cols = NULL,
  start = FALSE,
  end = FALSE,
  params = list(),
  labels = NULL,
  ...
)
}
\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"},
\code{"ising"}, \code{"mgm"}, \code{"attention"}, \code{"wtna"},
\code{"wtna_cooccurrence"}.
Aliases: \code{"tna"} and \code{"transition"} map to \code{"relative"};
\code{"ftna"} and \code{"counts"} map to \code{"frequency"};
\code{"cna"} and \code{"wcna"} map 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"};
\code{"isingfit"} maps to \code{"ising"};
\code{"atna"} maps to \code{"attention"};
\code{"mixed"} and \code{"mixed_graphical"} map to \code{"mgm"};
\code{"wtna_transition"} maps to \code{"wtna"}.}

\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 for one-hot input only:
\code{"non-overlapping"} or \code{"overlapping"}. Has no effect on
wide or long sequence data (only the one-hot/wtna path reads it).
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{state_cols}{Character vector or \code{NULL}. Explicit names of columns
to classify as state columns in the returned netobject's \code{$data}
slot. When provided, all other columns of the cleaned input go to
\code{$metadata}. Auto-detection (values-in-nodes heuristic) is bypassed.
Use this when a metadata column happens to contain values that overlap
with node names (e.g. condition labels \code{"A","B","C"} and nodes
\code{"A","B","C"}) and auto-detection would misclassify it. Default:
\code{NULL} (auto-detect).}

\item{metadata_cols}{Character vector or \code{NULL}. Explicit names of
columns to force into the \code{$metadata} slot. The remaining columns
are auto-detected as state via the values-in-nodes rule. Cannot overlap
with \code{state_cols}. Default: \code{NULL}.}

\item{start}{Boundary marker prepended to every sequence as an explicit
start state (a pure source: no incoming edges, every sequence's first
transition is \code{start -> first_observed}). \code{FALSE} (default)
adds nothing; \code{TRUE} uses the label \code{"Start"}; a single string
uses that string as the label. Only valid for the transition methods
(\code{relative}, \code{frequency}, \code{co_occurrence},
\code{attention}); errors otherwise.}

\item{end}{Boundary marker placed in the single cell after each sequence's
last observed (non-\code{NA}) state, as an explicit terminal state (a
pure sink: no outgoing edges, no self-loop -- distinct from
\code{\link{mark_terminal_state}}, which fills all trailing NAs into an
absorbing state). \code{FALSE} (default) adds nothing; \code{TRUE} uses
the label \code{"End"}; a single string uses that string as the label.
Same method restriction as \code{start}.}

\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.
Transition estimators accept tna-style sequence options such as
\code{weighted} and \code{concat} (and the low-level \code{begin_state}
/ \code{end_state}, of which \code{start} / \code{end} are the public
form -- see those arguments).
Column-like entries in \code{params} (\code{action}, \code{id},
\code{id_col}, \code{time}, \code{session}, \code{order}, \code{codes},
and \code{group}) are resolved before format detection and must name
existing columns. If the same column role is supplied both directly and
through \code{params}, the names must agree.}

\item{labels}{Optional name -> label remap applied after construction.
Accepts a 2-column data.frame \code{(name, label)}, a named character
vector \code{c(name = "label")}, or a named list. Rewrites
\code{$nodes$label} and \code{dimnames(weights)}. Unmapped names pass
through unchanged.}

\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 Validates explicit column arguments before any format guessing.
\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}.
}

For long-format transition data, supplying \code{action} without
\code{actor} is allowed and treats all rows as one sequence in row/time
order. The function warns because a one-sequence transition network is not
recommended and cannot be validated by bootstrap or other confirmatory
tests.
}
\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}}
}
