# ============================================================
# Package-level documentation.
# ============================================================

#' 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.
#'
#' @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.
#'
#' @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
#' }
#'
#' @docType package
#' @name netsubsamp-package
#' @aliases netsubsamp
"_PACKAGE"
