% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/two_sample_test.R
\name{two_sample_test}
\alias{two_sample_test}
\title{Two-sample test for unmatchable networks with unequal densities (Algorithm 3)}
\usage{
two_sample_test(
  G,
  G_prime,
  rho_target,
  N_sub = 2000L,
  motifs = list("v_shape", "triangle", "star3"),
  test = c("mahalanobis", "cauchy"),
  parallel = FALSE,
  n_cores = NULL
)
}
\arguments{
\item{G}{A square symmetric binary adjacency matrix (dense or sparse
\code{Matrix}) of size \eqn{n \times n}.  Typically the larger or
reference network.}

\item{G_prime}{A square symmetric binary adjacency matrix of size
\eqn{b \times b}.  The network to compare against \code{G}.}

\item{rho_target}{Numeric in \eqn{(0, 1)}; the common target edge density
\eqn{\rho^\dagger}.  See the \emph{Choice of \code{rho_target}} section.}

\item{N_sub}{Integer; number of subsampling replicates.  Default 2000.}

\item{motifs}{A list of motif specifications; see
\code{\link{subsample_moments}} for the format.  Defaults to
\code{list("v_shape", "triangle", "star3")}.}

\item{test}{Character; the multivariate test to apply.  Either
\code{"mahalanobis"} (default) or \code{"cauchy"}.}

\item{parallel}{Logical; whether to parallelise the subsampling loop.
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 when
\code{parallel = TRUE}.}
}
\value{
A list with:
\describe{
  \item{\code{p_value}}{The p-value of the test.}
  \item{\code{test_statistic}}{Observed test statistic: Mahalanobis
    distance \eqn{D_0} when \code{test = "mahalanobis"}, or Cauchy
    combination statistic \eqn{T} when \code{test = "cauchy"}.}
  \item{\code{observed_moments}}{Named numeric vector; the observed
    \eqn{\bar\Psi} statistic.}
  \item{\code{null_moments}}{\eqn{N_{\mathrm{sub}} \times m} matrix of
    null \eqn{\bar\Psi} statistics (including any \code{NA} rows from
    degenerate subsamples).}
  \item{\code{null_statistic}}{Numeric vector of per-replicate null
    Mahalanobis distances (or marginal p-values for \code{"cauchy"}).}
  \item{\code{marginal_p_values}}{(Only for \code{test = "cauchy"}.) Named
    numeric vector of per-motif marginal p-values.}
  \item{\code{method}}{The test method used.}
  \item{\code{motif_names}}{Character vector of moment names.}
}
}
\description{
Tests whether two unmatchable networks --- differing in node set, size, and
possibly edge density --- arise from the same underlying graphon model.
The procedure avoids the density-mismatch problem via a
\emph{split-and-sparsify} strategy: each network is randomly split into two
halves, one used to estimate the sparsification probability and the other to
compute density-normalised moments at a shared target density.  Node
subsampling from the larger network then generates a reference distribution
against which the observed statistic is compared.
}
\section{Algorithm}{

\enumerate{
  \item Randomly partition the nodes of \code{G_prime} into two equal
    halves \eqn{G'_1} and \eqn{G'_2}; compute the observed statistic
    \eqn{\bar\Psi_{\rho^\dagger}(G'_1, G'_2)} via Algorithm 2.
  \item For \eqn{i = 1, \ldots, N_{\mathrm{sub}}}: independently draw
    two sets of \eqn{\lfloor b/2 \rfloor} nodes from \eqn{G} and compute
    \eqn{\bar\Psi_{\rho^\dagger}(G^*_{i1}, G^*_{i2})} via Algorithm 2.
  \item Compare the observed statistic against the empirical null
    distribution using the selected \code{test}.
}
}

\section{Choice of \code{rho_target}}{

A recommended default is
\eqn{\rho^\dagger = \kappa \cdot \min(\hat\rho_G, \hat\rho_{G'})},
with \eqn{\kappa \in (0.5,\, 0.9)}.  Values close to 0 discard too many
edges and inflate variance; values too close to
\eqn{\min(\hat\rho_G, \hat\rho_{G'})} leave little room for edge removal
and can break the density-matching property.  A value of \eqn{\kappa = 0.7}
(corresponding to
\code{rho_target = 0.7 * min(rho_hat_G, rho_hat_G_prime)}) works well
across a range of settings.
}

\section{Tests}{

\describe{
  \item{Mahalanobis (default)}{Computes a multivariate distance that fully
    exploits the joint distribution of all moments.  The p-value is the
    proportion of null distances exceeding the observed distance.  This test
    is more powerful when the signal lies in the \emph{joint} rather than
    the \emph{marginal} distribution of the moments.}
  \item{Cauchy combination}{Combines marginal p-values via the Cauchy
    combination test of Liu & Xie (2020).  Controls type I error under
    arbitrary dependence but ignores cross-moment correlation.}
}
}

\examples{
\donttest{
library(randnet)
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, Hua, Li and Zhou (2024). Multivariate Inference of Network Moments by
Subsampling. \emph{Biometrika}, \strong{111}(1), 1--18.
\doi{10.1093/biomet/asad056}.

Liu, Y. and 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. \doi{10.1080/01621459.2018.1554485}.
}
