% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/subsample_moments.R
\name{subsample_moments}
\alias{subsample_moments}
\title{Uniform node subsampling for multivariate network moments (Algorithm 1)}
\usage{
subsample_moments(
  G,
  b,
  N_sub,
  motifs = list("v_shape", "triangle", "star3"),
  parallel = FALSE,
  n_cores = NULL
)
}
\arguments{
\item{G}{A square symmetric binary adjacency matrix (dense \code{matrix}
or sparse \code{Matrix}) of size \eqn{n \times n}.}

\item{b}{Integer; the subsampling size.  Must satisfy \eqn{3 \le b < n}.}

\item{N_sub}{Integer; number of subsamples to draw.}

\item{motifs}{A list of motif specifications.  Each element is either:
\itemize{
  \item a character string: \code{"v_shape"}, \code{"triangle"}, or
    \code{"star3"} (built-in defaults); or
  \item a named list with elements \code{fn} -- a
    \code{function(A)} returning a \emph{named} numeric vector -- and
    \code{n_edges} -- an integer vector of edge counts matching the
    output length of \code{fn}.
}
Defaults to \code{list("v_shape", "triangle", "star3")}.}

\item{parallel}{Logical; if \code{TRUE} the subsampling loop is run in
parallel via \pkg{doParallel} and \pkg{foreach}.  Default \code{FALSE}.
Requires the \pkg{netsubsamp} package to be \emph{installed} on all
worker nodes when \code{TRUE}.}

\item{n_cores}{Integer or \code{NULL}; number of cores to use when
\code{parallel = TRUE}.  If \code{NULL}, uses
\code{parallel::detectCores() - 1} (minimum 1).}
}
\value{
A list with:
\describe{
  \item{\code{rho}}{Estimated edge density of \code{G}.}
  \item{\code{moments}}{An \eqn{N_{\mathrm{sub}} \times m} numeric matrix
    of subsampled network moments.  Rows for which the subsampled graph has
    zero density contain \code{NA}.}
  \item{\code{motif_names}}{Character vector of moment names, in column
    order of \code{moments}.}
  \item{\code{b}}{The subsampling size used.}
}
}
\description{
Repeatedly draws random node-induced subgraphs of size \code{b} from
network \code{G} and computes network moments for each subsample.  The
resulting empirical distribution approximates the joint distribution of
network moments for networks of size \code{b} drawn from the same
underlying graphon model, providing the foundation for downstream inference.
}
\examples{
\donttest{
library(randnet)
set.seed(1)
G   <- BlockModel.Gen(lambda = 15, n = 200, K = 3)$A
res <- subsample_moments(G, b = 60, N_sub = 500)
head(res$moments)
res$rho
}

}
\references{
Qi, Hua, Li and Zhou (2024). Multivariate Inference of Network Moments by
Subsampling. \emph{Biometrika}, \strong{111}(1), 1--18.
\doi{10.1093/biomet/asad056}.
}
