\name{RISE}
\alias{RISE}
\encoding{UTF-8}
\title{
Rank In Similarity Graph Edge-count two-sample test (RISE)
}
\description{
Performs the Rank In Similarity Graph Edge-count two-sample test (RISE) for multivariate data (\cite{Zhou and Chen, 2023}). The implementation here uses the \code{\link[GraphRankTest]{RISE}} implementation from the \pkg{GraphRankTest} package.
}
\usage{
RISE(X1, X2, sim.fun = function(x, ...) -as.matrix(stats::dist(x, ...)), K = 10, 
     rank.type = "RgNN", n.perm = 0, dist.args = NULL, seed = NULL)
}
\arguments{
  \item{X1}{
First dataset as matrix or data.frame
}
  \item{X2}{
Second dataset as matrix or data.frame
}
  \item{sim.fun}{
Function for calculating a similarity matrix on the pooled dataset (default: negative value of \code{\link[stats:dist]{stats::dist}}, Euclidean distance).
}
  \item{K}{
Parameter \eqn{K} of the chosen graph (default: 10). Must be a positive number.
}
  \item{rank.type}{
Character specifying the similarity graph (\eqn{K}-nearest neighbor graph, \eqn{K}-NN; \eqn{K}-minimum spanning tree, \eqn{K}-MST; \eqn{K}-minimum-distance non-bipartite matching, \eqn{K}-MDP) and the rank definition (graph-induced ranks, Rg; overall ranks, Ro; see Details). Possible options are all combinations of the aforementioned options: \code{"RgNN"} (default), \code{"RoNN"}, \code{"RgMST"}, \code{"RoMST"}, \code{"RgMDP"}, \code{"RoMDP"}.
}
  \item{n.perm}{
Number of permutations for permutation test (default: 0, asymptotic test is performed).
}
  \item{dist.args}{
Named list of further arguments passed to \code{dist.fun} (default: \code{NULL}).
}
  \item{seed}{
Random seed (default: NULL). A random seed will only be set if one is provided.
}
}
\details{
\cite{Zhou and Chen, 2023} define the following two graph-based rank matrices \eqn{R = (R_{ij})_{i,j=1}^N} using sequences of similarity graphs \eqn{G_l} based on the distance matrix \eqn{S} of the two datasets. 
The \emph{graph-induced ranks} are defined as 
\deqn{
R_{ij} = \sum_{l=1}^K \boldsymbol{1}\left(\left(i,j\right)\in G_l\right).
}
They can be interpreted as the number of graphs that contain the edge \eqn{(i,j)} in the sequence of graphs. 
The \emph{overall ranks} are defined as
\deqn{
R_{ij} = \text{rank}\left(S\left(Z_i, Z_j\right), G_K\right),
}
where \eqn{\text{rank}\left(S\left(Z_i, Z_j\right), G_K\right)} denotes the rank of \eqn{S\left(Z_i, Z_j\right)} among the values \eqn{\{S\left(Z_u, Z_v\right)\}_{(u,v)\in G_K}} if \eqn{(i,j)\in G_k} and zero otherwise. 
The overall rank can be interpreted as the rank of the similarity of edges in the graph \eqn{G_K}. 
Both rank definitions depend on the choice of the parameter \eqn{K} that defines the length of the graph sequence. 
For the test, the symmetrized rank matrix \eqn{1/2(R+R^T)} is used, which is also denoted by $R$ for convenience.

For the test statistic, the within-sample rank sums of the first and second sample are defined as 
\deqn{
U_x = \sum_{i,j=1}^{n_1} R_{ij}, U_y = \sum_{i,j=n_1 + 1}^{N} R_{ij}.
}
Using these, the \emph{rank in similarity graph edge-count two-sample test (RISE)} statistic is defined as 
\deqn{
T_R = (U_{X1} - \mu_{X1}, U_{X2} - \mu_{X2})\Sigma^{-1}(U_{X1} - \mu_{X1}, U_{X2} - \mu_{X2})^T,
}
where \eqn{\mu_{X1} = \mathbb{E}(U_{X1})}, \eqn{\mu_{X2} = \mathbb{E}(U_{X2})}, and \eqn{\Sigma = \mathbb{C}\text{ov}((U_{X1}, U_{X2})^T)} can be calculated explicitly under the permutation null hypothesis. 

For small samples, the exact permutation null distribution can be used for testing. 
For large samples and under several assumptions on the similarity graphs, the asymptotic \eqn{\chi^2_2}-distribution of \eqn{T_R} can be used for testing. 

High values of the test statistic indicate dissimilarity of the datasets. Thus, the null hypothesis of equal distributions is rejected for large values. 

For \code{n.perm = 0}, an asymptotic test using the asymptotic \eqn{\chi^2_2} approximation of the null distribution is performed. For \code{n.perm > 0}, a permutation test is performed. 

This implementation is a wrapper function around the function \code{\link[GraphRankTest]{RISE}} that modifies the in- and output of that function to match the other functions provided in this package. For more details see the \code{\link[GraphRankTest]{RISE}}. 
}
\value{
An object of class \code{htest} with the following components:
\item{statistic }{Observed value of the test statistic}
\item{parameter }{Degrees of freedom for asymptotic test}
\item{p.value}{Asymptotic or permutation p value}
\item{alternative }{The alternative hypothesis}
\item{method }{Description of the test}
\item{data.name }{The dataset names}
}
\section{Applicability}{
\tabular{llll}{
     Target variable?   \tab Numeric? \tab Categorical? \tab K-sample? \cr
     No \tab Yes \tab No \tab No \cr
  }
}
\references{
Zhou, D. and Chen, H. (2023). A new ranking scheme for modern data and its application to two-sample hypothesis testing. In Proceedings of the 36th Annual Conference on Learning Theory (COLT 2023), PMLR, pp. 3615–3668. 

Stolte, M., Kappenberg, F., Rahnenführer, J., Bommert, A. (2024). Methods for quantifying dataset similarity: a review, taxonomy and comparison. Statist. Surv. 18, 163 - 298. \doi{10.1214/24-SS149}
}
\note{
Because this method cannot handle missing data, any missing values are removed automatically and a warning is issued.
}
\examples{
set.seed(1234)
# Draw some data
X1 <- matrix(rnorm(1000), ncol = 10)
X2 <- matrix(rnorm(1000, mean = 0.5), ncol = 10)
# Perform RISE
if(requireNamespace("GraphRankTest", quietly = TRUE)) {
  # Using 10-NNG and graph-induced ranks
  RISE(X1, X2)
  # Using 10-NNG and overall ranks
  RISE(X1, X2, rank.type = "RoNN")
  # Using 5-MST and graph-induced ranks
  RISE(X1, X2, K = 5, rank.type = "RgMST")
}
}
\keyword{ htest }
\keyword{ numeric }
\keyword{ rank-based }
\concept{ dataset similarity }
