% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/netdx.R
\name{netdx}
\alias{netdx}
\title{Dynamic Network Model Diagnostics}
\usage{
netdx(
  x,
  nsims = 1,
  dynamic = TRUE,
  nsteps = NULL,
  nwstats.formula = "formation",
  set.control.ergm = control.simulate.formula(),
  set.control.tergm = control.simulate.formula.tergm(MCMC.maxchanges =
    .Machine$integer.max),
  sequential = TRUE,
  keep.tedgelist = FALSE,
  keep.tnetwork = FALSE,
  verbose = TRUE,
  ncores = 1,
  skip.dissolution = FALSE,
  future.use.plan = FALSE
)
}
\arguments{
\item{x}{An \code{EpiModel} object of class \code{netest}.}

\item{nsims}{Number of simulations to run. For dynamic diagnostics, 5--10
simulations are usually sufficient to assess model fit. For static
diagnostics, use 10,000+ draws to obtain stable estimates.}

\item{dynamic}{If \code{TRUE}, runs dynamic diagnostics that simulate the
temporal network forward in time, checking both formation targets
and partnership duration/dissolution. If \code{FALSE}, draws from the
static ERGM fit to check cross-sectional network structure only
(faster, but does not verify dissolution dynamics). Static
diagnostics are only available when the model was fit with the
edges dissolution approximation (\code{edapprox = TRUE} in \code{\link{netest}}).}

\item{nsteps}{Number of time steps per simulation (dynamic simulations
only). Should be at least several multiples of the longest target
partnership duration to allow the duration and dissolution statistics
to stabilize. For example, if the target duration is 50, running for
500 time steps is a reasonable starting point.}

\item{nwstats.formula}{A right-hand sided ERGM formula with the network
statistics of interest. The default is the formation formula of the
network model contained in \code{x}. You may track additional network
statistics beyond the formation terms by specifying them here, such
as \code{~ edges + meandeg + concurrent + degree(0:4)}. This is useful
for verifying that the model produces reasonable values for network
features that were not directly targeted in the formation model.}

\item{set.control.ergm}{Control arguments passed to \code{ergm}'s
\code{simulate_formula.network} (see details).}

\item{set.control.tergm}{Control arguments passed to \code{tergm}'s
\code{simulate_formula.network} (see details).}

\item{sequential}{For static diagnostics (\code{dynamic=FALSE}): if
\code{FALSE}, each of the \code{nsims} simulated Markov chains begins
at the initial network; if \code{TRUE}, the end of one simulation is
used as the start of the next.}

\item{keep.tedgelist}{If \code{TRUE}, keep the timed edgelist generated from
the dynamic simulations. Returned in the form of a list of matrices,
with one entry per simulation. Accessible at \verb{$edgelist}.}

\item{keep.tnetwork}{If \code{TRUE}, keep the full networkDynamic objects
from the dynamic simulations. Returned in the form of a list of nD
objects, with one entry per simulation. Accessible at \verb{$network}.}

\item{verbose}{If \code{TRUE}, print progress to the console.}

\item{ncores}{Number of processor cores to run multiple simulations
on, using the \code{future} framework.}

\item{skip.dissolution}{If \code{TRUE}, skip over the calculations of
duration and dissolution stats in \code{netdx}.}

\item{future.use.plan}{If \code{FALSE}, \code{netdx} will use \code{multisession} is used with \verb{workers = ncores for its parallelization. If }TRUE\verb{, }netdx\verb{will use the user defined plan from}globalEnv\verb{. Finally, it can take the output of a }future::tweak()\verb{call to setup a user defined temporary plan within}netdx`.
Which can be useful for distributed computation (HPC).}
}
\value{
A list of class \code{netdx}. Use \code{print()} to view summary tables of
formation statistics, duration, and dissolution diagnostics. Use
\code{\link{plot.netdx}} to visualize these diagnostics over time. Use
\code{\link[=as.data.frame.netdx]{as.data.frame.netdx()}} to extract timed edgelists (if
\code{keep.tedgelist = TRUE}).
}
\description{
Runs diagnostic simulations on an ERGM/STERGM estimated with
\code{\link{netest}} to assess whether the fitted model reproduces the
intended network features. Both static (cross-sectional) and
dynamic (temporal) diagnostics are supported. This is the
recommended second step in the network modeling pipeline, after
estimation with \code{\link{netest}} and before epidemic simulation with
\code{\link{netsim}}.
}
\details{
The \code{netdx} function handles dynamic network diagnostics for network
models fit with the \code{\link{netest}} function. Given the fitted model,
\code{netdx} simulates a specified number of dynamic networks for a specified
number of time steps per simulation. The network statistics in
\code{nwstats.formula} are saved for each time step. Summary statistics for
the formation model terms, as well as dissolution model and relational
duration statistics, are then calculated and can be accessed when printing or
plotting the \code{netdx} object. See \code{\link{print.netdx}} and \code{\link{plot.netdx}}
for details on printing and plotting.
}
\section{Control Arguments}{

Models fit with the full STERGM method in \code{netest} (setting the
\code{edapprox} argument to \code{FALSE}) require only a call to
\code{tergm}'s \code{simulate_formula.network}. Control parameters for those
simulations may be set using \code{set.control.tergm} in \code{netdx}.
The parameters should be input through the \code{control.simulate.formula.tergm}
function, with the available parameters listed in the
\code{\link[tergm:control.simulate.formula.tergm]{tergm::control.simulate.formula.tergm}} help page in the \code{tergm}
package.

Models fit with the ERGM method with the edges dissolution approximation
(setting \code{edapprox} to \code{TRUE}) require a call first to
\code{ergm}'s \code{simulate_formula.network} for simulating an initial
network, and second to \code{tergm}'s \code{simulate_formula.network} for
simulating that static network forward through time. Control parameters may
be set for both processes in \code{netdx}. For the first, the parameters
should be input through the \code{control.simulate.formula()} function, with
the available parameters listed in the
\code{\link[ergm:control.simulate.formula]{ergm::control.simulate.formula}} help
page in the \code{ergm} package. For the second, parameters should be input
through the \code{control.simulate.formula.tergm()} function, with the
available parameters listed in the \code{\link[tergm:control.simulate.formula.tergm]{tergm::control.simulate.formula.tergm}}
help page in the \code{tergm} package. An example is shown below.
}

\section{Static vs. Dynamic Diagnostics}{

Static diagnostics (\code{dynamic = FALSE}) draw many independent networks from
the fitted ERGM and compare the resulting statistics to the target values.
This is fast and checks whether the cross-sectional structure is correct,
but it does not verify partnership durations or dissolution rates. Dynamic
diagnostics (\code{dynamic = TRUE}) simulate the full temporal network forward
in time, checking both formation targets and dissolution/duration dynamics.
Dynamic diagnostics are slower but more comprehensive, and are required to
verify models that will be used with vital dynamics (arrivals/departures).
}

\section{Interpreting Diagnostics}{

After running \code{netdx}, use \code{print()} and \code{\link{plot.netdx}} to inspect the
results. Key indicators of a good model fit include:
\itemize{
\item \strong{Formation statistics:} The "Sim Mean" should be close to the
"Target" value. A small "Pct Diff" (< 5\\%) and a "Z Score" near 0
indicate good fit.
\item \strong{Duration statistics} (dynamic only): The simulated mean edge
durations should match the values passed to \code{\link{dissolution_coefs}}.
\item \strong{Dissolution statistics} (dynamic only): The simulated dissolution
rates should be approximately \code{1 / duration}.
}

Common problems: If formation statistics are off, the ERGM may need
increased burn-in (via \code{set.control.ergm}), or the target statistics
may be incompatible (e.g., specifying more edges than the network can
support). If durations are off but formation is correct, verify that
\code{d.rate} was correctly specified in \code{\link{dissolution_coefs}} for models
with vital dynamics.
}

\examples{
\donttest{
# Static diagnostics on a simple model
nw <- network_initialize(n = 100)
formation <- ~edges
target.stats <- 50
coef.diss <- dissolution_coefs(dissolution = ~offset(edges), duration = 25)
est <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)
dx <- netdx(est, nsims = 1e4, dynamic = FALSE, verbose = FALSE)
dx
plot(dx)
}

\dontrun{
# Static diagnostics with additional network statistics
dx1 <- netdx(est,
  nsims = 1e4, dynamic = FALSE,
  nwstats.formula = ~ edges + meandeg + concurrent
)
dx1
plot(dx1, method = "b", stats = c("edges", "concurrent"))

# Dynamic diagnostics on the STERGM approximation
dx2 <- netdx(est,
  nsims = 5, nsteps = 500,
  nwstats.formula = ~ edges + meandeg + concurrent,
  set.control.ergm = control.simulate.formula(MCMC.burnin = 1e6)
)
dx2
plot(dx2, stats = c("edges", "meandeg"), plots.joined = FALSE)
plot(dx2, type = "duration")
plot(dx2, type = "dissolution", qnts.col = "orange2")
plot(dx2, type = "dissolution", method = "b", col = "bisque")

# Dynamic diagnostics on a more complex model
nw <- network_initialize(n = 1000)
nw <- set_vertex_attribute(nw, "neighborhood", rep(1:10, 100))
formation <- ~edges + nodematch("neighborhood", diff = TRUE)
target.stats <- c(800, 45, 81, 24, 16, 32, 19, 42, 21, 24, 31)
coef.diss <- dissolution_coefs(dissolution = ~offset(edges) +
                    offset(nodematch("neighborhood", diff = TRUE)),
                    duration = c(52, 58, 61, 55, 81, 62, 52, 64, 52, 68, 58))
est2 <- netest(nw, formation, target.stats, coef.diss, verbose = FALSE)
dx3 <- netdx(est2, nsims = 5, nsteps = 100)
print(dx3)
plot(dx3)
plot(dx3, type = "duration", plots.joined = TRUE, qnts = 0.2, legend = TRUE)
plot(dx3, type = "dissolution", mean.smooth = FALSE, mean.col = "red")
}

}
\seealso{
Estimate the network model with \code{\link{netest}} before running diagnostics.
Plot diagnostics with \code{\link{plot.netdx}} and print summary tables with
\code{\link{print.netdx}}. After diagnostics confirm a good fit, simulate the
epidemic with \code{\link{netsim}}.
}
