% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mlvar.R
\name{build_mlvar}
\alias{build_mlvar}
\title{Build a Multilevel Vector Autoregression (mlVAR) network}
\usage{
build_mlvar(
  data,
  vars,
  id,
  day = NULL,
  beep = NULL,
  lag = 1L,
  standardize = FALSE
)
}
\arguments{
\item{data}{A \code{data.frame} containing the panel data.}

\item{vars}{Character vector of variable column names to model.}

\item{id}{Character string naming the person-ID column.}

\item{day}{Character string naming the day/session column, or \code{NULL}.
When provided, lag pairs are only formed within the same day.}

\item{beep}{Character string naming the measurement-occasion column, or
\code{NULL}. When \code{NULL}, row position within each (id, day) is used.}

\item{lag}{Integer. The lag order (default 1).}

\item{standardize}{Logical. If \code{TRUE}, each variable is grand-mean
centered and divided by its pooled SD \emph{before} augmentation. Default
\code{FALSE}, matching \code{mlVAR::mlVAR(scale = FALSE)} - the only setting for
which numerical equivalence has been validated.}
}
\value{
A dual-class \code{c("net_mlvar", "netobject_group")} object - a
named list of three full netobjects, one per network, plus
model-level metadata stored as attributes. Each element is a
standard \code{c("netobject", "cograph_network")} weight-matrix wrapper
(no raw \verb{$data}), so \code{print()}, \code{summary()}, \code{\link[=coefs]{coefs()}}, and
\code{cograph::splot(fit$temporal)} work directly. The three constituents
are matrix-wrapped and carry no underlying panel data, so
data-resampling verbs such as \code{\link[=bootstrap_network]{bootstrap_network()}} (and
reliability/stability) cannot iterate over them - extract a single
constituent and rebuild via \code{\link[=build_network]{build_network()}} if you need those.
Structure:
\describe{
\item{\code{fit$temporal}}{Directed netobject for the \verb{d x d} matrix of
fixed-effect lagged coefficients. \verb{$weights[i, j]} is the effect
of variable j at t-lag on variable i at t. \code{method = "mlvar_temporal"}, \code{directed = TRUE}.}
\item{\code{fit$contemporaneous}}{Undirected netobject for the \verb{d x d}
partial-correlation network of within-person lmer residuals.
\code{method = "mlvar_contemporaneous"}, \code{directed = FALSE}.}
\item{\code{fit$between}}{Undirected netobject for the \verb{d x d}
partial-correlation network of person means, derived from
\code{D (I - Gamma)}. \code{method = "mlvar_between"}, \code{directed = FALSE}.}
\item{\code{attr(fit, "coefs")} / \code{\link[=coefs]{coefs()}}}{Tidy \code{data.frame} with one
row per \verb{(outcome, predictor)} pair and columns \code{outcome},
\code{predictor}, \code{beta}, \code{se}, \code{t}, \code{p}, \code{ci_lower}, \code{ci_upper},
\code{significant}. Filter, sort, or plot with base R or the tidyverse.
Retrieve with \code{coefs(fit)}.}
\item{\code{attr(fit, "n_obs")}}{Number of rows in the augmented panel
after na.omit.}
\item{\code{attr(fit, "n_subjects")}}{Number of unique subjects remaining.}
\item{\code{attr(fit, "lag")}}{Lag order used.}
\item{\code{attr(fit, "standardize")}}{Logical; whether pre-augmentation
standardization was applied.}
}
}
\description{
Estimates three networks from ESM/EMA panel data, matching
\code{mlVAR::mlVAR()} with \code{estimator = "lmer"}, \code{temporal = "fixed"},
\code{contemporaneous = "fixed"} at machine precision: (1) a directed
temporal network of fixed-effect lagged regression coefficients, (2)
an undirected contemporaneous network of partial correlations among
residuals, and (3) an undirected between-subjects network of partial
correlations derived from the person-mean fixed effects.

#' @details The algorithm follows mlVAR's lmer pipeline exactly:
\enumerate{
\item Drop rows with NA in id/day/beep and optionally grand-mean
standardize each variable.
\item Expand the per-(id, day) beep grid and right-join original
values, producing the augmented panel (\code{augData}).
\item Add within-person lagged predictors (\verb{L1_*}) and person-mean
predictors (\verb{PM_*}).
\item For each outcome variable fit
\code{lmer(y ~ within + between-except-own-PM + (1 | id))} with
\code{REML = FALSE}. Collect the fixed-effect temporal matrix \code{B},
between-effect matrix \code{Gamma}, random-intercept SDs (\code{mu_SD}),
and lmer residual SDs.
\item Contemporaneous network:
\code{cor2pcor(D \%*\% cov2cor(cor(resid)) \%*\% D)}.
\item Between-subjects network:
\code{cor2pcor(pseudoinverse(forcePositive(D (I - Gamma))))}.
}

Validated to machine precision (max_diff < 1e-10) against
\code{mlVAR::mlVAR()} on 25 real ESM datasets from \code{openesm} and 20 simulated
configurations (seeds 201-220). See \code{tmp/mlvar_equivalence_real20.R} and
\code{tmp/mlvar_equivalence_20seeds.R}.
}
\examples{
\dontrun{
d <- simulate_data("mlvar", seed = 1)
fit <- build_mlvar(d, vars = attr(d, "vars"),
                   id = "id", day = "day", beep = "beep")
print(fit)
summary(fit)
}

}
\seealso{
\code{\link[=build_network]{build_network()}}
}
