% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/netsubsamp-package.R
\docType{package}
\name{netsubsamp-package}
\alias{netsubsamp-package}
\alias{netsubsamp}
\title{netsubsamp: Multivariate Inference of Network Moments by Subsampling}
\description{
\pkg{netsubsamp} implements the three subsampling algorithms from
Qi, Hua, Li and Zhou (2024) for multivariate inference on network moments
(rescaled counts of graph motifs such as V-shapes, triangles, and stars)
under a sparse graphon model.
}
\section{The three algorithms}{


\strong{Algorithm 1 -- \code{\link{subsample_moments}}: Uniform node
subsampling.}
Draws \eqn{N_{\mathrm{sub}}} random node-induced subgraphs of size
\eqn{b} from a single network \eqn{G} and computes the vector of network
moments for each subsample.  The resulting empirical distribution
consistently approximates the joint distribution of multiple network moments
for networks of size \eqn{b} drawn from the same graphon.  This provides
the foundation for any downstream inference task: confidence regions,
goodness-of-fit tests, or visualization of the joint moment distribution.

\strong{Algorithm 2 -- \code{\link{sparsify_moments}}: Externally
sparsified moments.}
Given two independently sampled subgraphs \eqn{G_1} and \eqn{G_2} and a
target density \eqn{\rho^\dagger}, uses \eqn{G_1} to estimate the
required edge-removal probability and then randomly removes edges from
\eqn{G_2} to produce a graph at the target density.  Returns the
density-normalised moment vector
\eqn{\bar\Psi_{\rho^\dagger}(G_1, G_2)}.  This building block handles
the practical complication that the true graphon density is unknown.

\strong{Algorithm 3 -- \code{\link{two_sample_test}}: Two-sample test for
unmatchable networks with unequal densities.}
Tests \eqn{H_0: w = w'} for two unmatchable networks \eqn{G} (size
\eqn{n}) and \eqn{G'} (size \eqn{b}) that may have different edge
densities.  The nodes of \eqn{G'} are split randomly into two halves;
Algorithm 2 is applied to compute an observed statistic.  Node subsampling
from \eqn{G} (again via Algorithm 2) generates a reference distribution.
A final multivariate test---either a Mahalanobis distance test or the
Cauchy combination test of Liu and Xie (2020)---yields a p-value.  This
is the first subsampling-based procedure that is valid for unmatchable
networks with unequal densities.
}

\section{Motif support}{

Three motifs are built in: \code{"v_shape"} (2-star, 2 edges),
\code{"triangle"} (3 edges), and \code{"star3"} (3-star, 3 edges).
All three functions accept a \code{motifs} argument that can include
user-supplied specifications: a list with element \code{fn}, a
\code{function(A)} returning a \emph{named} numeric vector of one or more
moment values, and element \code{n_edges}, an integer vector of the
corresponding edge counts used for density normalisation.
}

\section{Parallel execution}{

The \eqn{N_{\mathrm{sub}}} subsampling loop in \code{subsample_moments}
and \code{two_sample_test} can be parallelised by setting
\code{parallel = TRUE} (uses \pkg{doParallel} and \pkg{foreach}).
Parallel mode requires the \pkg{netsubsamp} package to be installed on
all worker nodes.
}

\examples{
\donttest{
library(randnet)

## ---- Algorithm 1: approximate the joint moment distribution ----------
set.seed(1)
G   <- BlockModel.Gen(lambda = 15, n = 200, K = 3)$A
res <- subsample_moments(G, b = 60, N_sub = 500)

# Estimated density
res$rho

# First few rows of the N_sub x 3 moment matrix
head(res$moments)


## ---- Algorithm 2: externally sparsified moments ----------------------
set.seed(2)
G1  <- BlockModel.Gen(lambda = 15, n = 100, K = 3)$A
G2  <- BlockModel.Gen(lambda = 15, n = 100, K = 3)$A
sparsify_moments(G1, G2, rho_target = 0.08)


## ---- Algorithm 3: two-sample test under unequal densities -----------
set.seed(3)
G       <- BlockModel.Gen(lambda = 20, n = 400, K = 3)$A
G_prime <- BlockModel.Gen(lambda = 15, n = 100, K = 3)$A

# Choose rho_target as 0.7 * min(density(G), density(G_prime))
rho_G       <- sum(G)       / (400 * 399)
rho_G_prime <- sum(G_prime) / (100 * 99)
rho_target  <- 0.7 * min(rho_G, rho_G_prime)

res <- two_sample_test(G, G_prime,
                       rho_target = rho_target,
                       N_sub      = 500,
                       test       = "mahalanobis")
res$p_value
}

}
\references{
Qi M, Hua C-W, Li T, Zhou W (2024).
Multivariate Inference of Network Moments by Subsampling.
\emph{Biometrika}, \strong{111}(1), 1--18.
\href{https://arxiv.org/abs/2409.01599}{arXiv:2409.01599}.

Liu Y, Xie J (2020).
Cauchy combination test: a powerful test with analytic p-value calculation
under arbitrary dependency structures.
\emph{Journal of the American Statistical Association}, \strong{115},
393--402.
}
\author{
\strong{Maintainer}: Tianxi Li \email{tianxili@umn.edu}

Authors:
\itemize{
  \item Mingyu Qi
  \item Chen-Wei Hua
  \item Wen Zhou
}

}
