% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bd.R
\name{bd.test}
\alias{bd.test}
\title{Ball Divergence based Equality of Distributions Test}
\usage{
bd.test(x, y = NULL, R = 99, dst = FALSE, size = NULL, seed = 4,
  num.threads = 2, kbd.type = "sum")
}
\arguments{
\item{x}{a numeric vector, matrix, data.frame, \code{dist} object or list containing vector, matrix, or data.frame.}

\item{y}{a numeric vector, matrix or data.frame.}

\item{R}{the number of replications, when R equals to 0, the function returns
the sample version of ball divergence. Default: \code{R = 99}}

\item{dst}{if \code{dst = TRUE}, x will be considered as a distance matrix. Default: \code{dst = FALSE}}

\item{size}{a vector record sample size of each group.}

\item{seed}{the random seed.}

\item{num.threads}{Number of threads. Default \code{num.threads = 2}.}

\item{kbd.type}{a character value controlling the output information. 
Setting \code{kdb.type = "sum"}, \code{kdb.type = "summax"}, or \code{kdb.type = "max"}, 
the corresponding statistics value and \eqn{p}-value of \eqn{K}-sample test procedure are demonstrated. 
Note that this arguments actually only influences the printed result in R console. Default: \code{kdb.type = "sum"}}
}
\value{
bd.test returns a list with class "htest" containing the following components:
\item{\code{statistic}}{ball divergence statistic.}            
\item{\code{p.value}}{the p-value for the test.}
\item{\code{replicates}}{replicates of the test statistic.}
\item{\code{size}}{sample sizes.}
\item{\code{complete.info}}{a \code{list} containing multiple statistics value and their corresponding $p$ value.}
\item{\code{alternative}}{a character string describing the alternative hypothesis.}
\item{\code{method}}{a character string indicating what type of test was performed.}
\item{\code{data.name}}{description of data.}
}
\description{
Performs the nonparametric two-sample or K-sample ball divergence test for
equality of multivariate distributions
}
\details{
\code{bd.test} are ball divergence based multivariate nonparametric tests of two-sample or 
K-sample problem. If only \code{x} is given, the statistic is 
computed from the original pooled samples, stacked in 
matrix where each row is a multivariate observation, or from the distance matrix 
when \code{dst = TRUE}. The first \code{sizes[1]} rows of \code{x} are the first sample, the next 
\code{sizes[2]} rows of \code{x} are the second sample, etc.
If x is a list, its elements are taken as the samples to be compared, 
and hence have to be numeric data vectors, matrix or data.frame.

Based on sample version ball divergence (see \code{\link{bd}}), the test is implemented by 
permutation with R replicates. The function simply returns the test statistic 
when \code{R = 0}.
}
\examples{
################# Quick Start #################
x <- rnorm(50)
y <- rnorm(50, mean = 1)
# plot(density(x))
# lines(density(y), col = "red")
# ball divergence:
bd.test(x = x, y = y)

################# Quick Start #################
x <- matrix(rnorm(100), nrow = 50, ncol = 2)
y <- matrix(rnorm(100, mean = 3), nrow = 50, ncol = 2)
# Hypothesis test with Standard Ball Divergence:
bd.test(x = x, y = y)

################# Simlated Non-Hilbert data #################
data("bdvmf")
\dontrun{
library(scatterplot3d)
scatterplot3d(bdvmf[["x"]], color = bdvmf[["group"]], 
              xlab = "X1", ylab = "X2", zlab = "X3")
}
# calculate geodesic distance between sample:
Dmat <- nhdist(bdvmf[["x"]], method = "geodesic")
# hypothesis test with BD :
bd.test(x = Dmat, size = c(150, 150), R = 99, dst = TRUE)

################# Non-Hilbert Real Data #################
# load data:
data("macaques")
# number of femala and male Macaca fascicularis:
table(macaques[["group"]])
# calculate Riemannian shape distance matrix:
Dmat <- nhdist(macaques[["x"]], method = "riemann")
# hypothesis test with BD:
bd.test(x = Dmat, R = 99, size = c(9, 9), dst = TRUE)

################  K-sample Test  #################
n <- 150
bd.test(rnorm(n), size = c(40, 50, 60))
# alternative input method:
x <- lapply(c(40, 50, 60), rnorm)
bd.test(x)

}
\references{
Pan, Wenliang; Tian, Yuan; Wang, Xueqin; Zhang, Heping. Ball Divergence: Nonparametric two sample test. Ann. Statist. 46 (2018), no. 3, 1109--1137. doi:10.1214/17-AOS1579. https://projecteuclid.org/euclid.aos/1525313077
}
\seealso{
\code{\link{bd}}
}
\author{
Wenliang Pan, Yuan Tian, Xueqin Wang, Heping Zhang
}
