Package {BET}

Binary Expansion Testing

Description

The BET package provides functions for nonparametric detection of nonuniformity and dependence with Binary Expansion Testing (BET).

BET functions

MaxBET symm get.signs cell.counts bet.plot MaxBETs BEAST

Reference(s)

Kai Zhang (2019) BET on Independence, Journal of the American Statistical Association, 114:528, 1620-1637, doi:10.1080/01621459.2018.1537921, Kai Zhang, Zhigen Zhao, and Wen Zhou (2021). BEAUTY Powered BEAST, <arXiv:2103.00674> and Wan Zhang, Zhigen Zhao, Michael Baiocchi, Yao Li, Kai Zhang. SorBET: A Fast and Powerful Algorithm to Test Dependence of Variables. Techinical report, 2023.

Binary Expansion Adaptive Symmetry Test

Description

BEAST (Binary Expansion Adaptive Symmetry Test) is used for nonparametric detection of nonuniformity or dependence.

Usage

BEAST(
  X,
  dep,
  subsample.percent = 1/2,
  B = 100,
  unif.margin = FALSE,
  lambda = NULL,
  index = list(c(1:ncol(X))),
  method = "p",
  num = NULL
)

Arguments

Value

Examples

## Elapsed times 7.32 secs
## Measured in R 4.0.2, 32 bit, on a processor 3.3 GHz 6-Core Intel Core i5 under MacOS, 2024/9/6
## Not run: 
  x1 = runif(128)
  x2 = runif(128)
  y = sin(4*pi*(x1 + x2)) + 0.8*rnorm(128)
  ##test independence between (x1, x2) and y
  BEAST(cbind(x1, x2, y), 3, index = list(c(1,2), c(3)))
  ##test mutual independence among x1, x2 and y
  BEAST(cbind(x1, x2, y), 3, index = list(1, 2, 3))
  
  ##test bivariate uniformity
  x1 = rbeta(128, 2, 4)
  x2 = rbeta(128, 2, 4)
  BEAST(cbind(x1, x2), 3)
  ##test multivariate uniformity
  x1 = rbeta(128, 2, 4)
  x2 = rbeta(128, 2, 4)
  x3 = rbeta(128, 2, 4)
  BEAST(cbind(x1, x2, x3), 3)

## End(Not run)

Bivariate Asymptotic BEAST Test

Description

Tests independence between two continuous variables using a stored calibration based on the joint Gaussian limit of full-sample and internally reranked subsample interactions.

Usage

BEAST.asymptotic(X, calibration, alpha = 0.05, seed = NULL)
## S3 method for class 'BEASTAsymptoticResult'
print(x, ...)

Arguments

Details

The function calls BEAST(method="stat") with the tuning parameters stored in calibration and compares \sqrt{n-1}B_\lambda with its G0 draws.

The p-value is mean(calibration$G0 >= Scaled.Statistic). The critical value is sort(calibration$G0)[ceiling((1-alpha)*G)], and rejection uses Scaled.Statistic > critical.value. At atoms, this strict decision can differ from comparing the empirical p-value with alpha.

The dataset must have two columns and the calibration's sample size. Marginal ties produce a warning; permutation calibration is recommended for tied data. A nonpositive critical value also requires permutation calibration and produces an error. A nonfinite BEAST statistic produces an error.

The same calibration can be reused across datasets with matching sample size and tuning parameters, and at different significance levels. See BEAST.asymptotic.calibrate for its construction.

Value

An object of class BEASTAsymptoticResult, with BEAST.Statistic, Scaled.Statistic, p.value, critical.value, logical reject, alpha, Interaction from the BEAST statistic, calibration configuration/method summary, tie indicator and optional seed.

See Also

BEAST.asymptotic.calibrate, BEAST

Examples

# Small counts for illustration; use larger H and G for inference.
i <- seq_len(32)
X1 <- cbind(i/33, i/33 + 0.08*sin(i))
X2 <- cbind(i/33, -i/33 + 0.08*cos(i))
cal <- BEAST.asymptotic.calibrate(32, dep=2, subsample.percent=1/2,
  B=2, lambda=0, H=12, G=64, seed=1)
BEAST.asymptotic(X1, cal, seed=11)
BEAST.asymptotic(X2, cal, seed=12)

Reusable Bivariate Asymptotic BEAST Calibration

Description

Constructs a reusable joint Gaussian reference for BEAST testing independence between two continuous variables.

Usage

BEAST.asymptotic.calibrate(n, dep = 3, subsample.percent = 3/16,
  B = 128, lambda = NULL, H = 1000, G = 10000, seed = NULL,
  ncores = 1)
## S3 method for class 'BEASTAsymptoticCalibration'
print(x, ...)

Arguments

Details

Calibration uses all q=(2^{\mathtt{dep}}-1)^2 cross interactions. For each of H independent bivariate normal null samples, it computes the full-sample interaction means and their average over B size-r subsamples drawn without replacement. Marginal ranks are recomputed within each subsample. The covariance of this joint vector, scaled by \sqrt{n-1}, is estimated and negative eigenvalues are set to zero.

Joint Gaussian draws are soft-thresholded at \sqrt{n-1}\lambda. The BEAST limit map divides the inner product of the thresholded full and subsample vectors by the norm of the full vector, returning zero when that norm is zero. The resulting G0 draws are stored for testing at different significance levels.

Both n and the effective r must be divisible by 2^{\mathtt{dep}}, with r\ge 2. A calibration can be saved with saveRDS() and reused for bivariate datasets with the same sample size and tuning parameters. For multivariate blocks, the covariance also depends on within-block dependence, so this reusable calibration is bivariate only.

An explicit seed makes calibration reproducible and preserves the caller's RNG state. With seed=NULL, a master seed is drawn from the current RNG stream and recorded in the object. Calibration is serial.

Value

An object of class BEASTAsymptoticCalibration, containing n, dep, subsample.percent, effective r, B, actual lambda, q, H, G, the covariance Gamma, pre-clipping Gamma.raw, G0, nonzero fraction, minimum raw eigenvalue, count of clipped eigenvalues, basis/configuration, RNG metadata, package version, method identifier and bivariate continuous-margin scope.

See Also

BEAST.asymptotic, BEAST

Examples

# Small counts for illustration; use larger H and G for inference.
cal <- BEAST.asymptotic.calibrate(32, dep = 2, subsample.percent = 1/2,
  B = 2, H = 8, G = 32, seed = 1)
cal
length(cal$G0)

Binary Expansion Testing at a Certain Depth

Description

MaxBET stands for Binary Expansion Testing. It is used for nonparametric detection of nonuniformity or dependence. It can be used to test whether a column vector is [0, 1]-uniformly distributed. It can also be used to detect dependence between columns of a matrix X, if X has more than one column.

Usage

MaxBET(
  X,
  dep,
  unif.margin = FALSE,
  asymptotic = TRUE,
  plot = FALSE,
  index = list(c(1:ncol(X)))
)

Arguments

Details

MaxBET tests the independence or uniformity by considering the maximal magnitude of the symmetry statistics in the sigma-field generated from marginal binary expansions at the depth d.

Value

Examples

##test mutual independence
v <- runif(128, -pi, pi)
X1 <- cos(v) + 2.5 * rnorm(128, 0, 1/20)
X2 <- sin(v) + 2.5 * rnorm(128, 0, 1/20)
MaxBET(cbind(X1, X2), 3, asymptotic = FALSE, index = list(1,2))

##test independence between (x1, x2) and y
x1 = runif(128)
x2 = runif(128)
y = sin(4*pi*(x1 + x2)) + 0.4*rnorm(128)
MaxBET(cbind(x1, x2, y), 3, index = list(c(1,2), c(3)))

##test uniformity
x1 = rbeta(128, 2, 4)
x2 = rbeta(128, 2, 4)
x3 = rbeta(128, 2, 4)
MaxBET(cbind(x1, x2, x3), 3)

Binary Expansion Testing up to a Certain Depth

Description

MaxBETs is used for nonparametric dependence detection. Extended from BET, for a chosen maximal depth d.max, MaxBETs does a sequential test up to d.max and avoids overlapping symmetry statistics in different depths, for all 2 \le d \le d.max. The adjustment is done by multiplying the number of interactions which are in the \sigma-field generated by marginal binary expansions at depth d but not in that at depth d-1.

Usage

MaxBETs(
  X,
  d.max = 4,
  unif.margin = FALSE,
  asymptotic = TRUE,
  plot = FALSE,
  index = list(c(1:ncol(X)))
)

Arguments

Value

Examples

##test mutual independence
v <- runif(128, -pi, pi)
X1 <- cos(v) + 2.5 * rnorm(128, 0, 1/20)
X2 <- sin(v) + 2.5 * rnorm(128, 0, 1/20)
MaxBETs(cbind(X1, X2), 3, asymptotic = FALSE, index = list(1,2))

##test independence between (x1, x2) and y
x1 = runif(128)
x2 = runif(128)
y = sin(4*pi*(x1 + x2)) + 0.4*rnorm(128)
MaxBETs(cbind(x1, x2, y), 3, index = list(c(1,2), c(3)))

##test uniformity
x1 = rbeta(128, 2, 4)
x2 = rbeta(128, 2, 4)
x3 = rbeta(128, 2, 4)
MaxBETs(cbind(x1, x2, x3), 3)

Plotting Binary Expansion Testing (2-dimensions)

Description

bet.plot shows the cross interaction of the strongest asymmetry, which the BET returns with the rejection of independence null. This function only works for the test on two variables, that is, X can only have two columns. There are 2^{2dep} - 1 nontrivial binary variables in the \sigma-field and (2^dep - 1)^2 of them are cross interactions, whose positive regions are in plotted in white and whose negative regions are plotted in blue. bet.plot shows the cross interaction where the difference of number of observations in the positive and negative region is largest.

Usage

## S3 method for class 'plot'
bet(X, dep, unif.margin = FALSE, cex=0.5, index = list(c(1:ncol(X))), ...)

Arguments

Examples

v <- runif(128, -pi, pi)
X1 <- cos(v) + 2.5 * rnorm(128, 0, 1/20)
X2 <- sin(v) + 2.5 * rnorm(128, 0, 1/20)
bet.plot(cbind(X1, X2), 3, index = list(1,2))

Counts the amount of points in each cell after binary expansion.

Description

cell.counts returns the amount of data points in each cell getting from binary expansion.

Usage

cell.counts(X, dep, unif.margin = FALSE)

Arguments

Value

The result is a dataframe with 2 rows and 2^(p*dep) columns, where p is the number of columns of X. The first column is the binary index, the second column is the amount of data points.

Examples

v <- runif(128, -pi, pi)
X1 <- cos(v) + 2.5 * rnorm(128, 0, 1/20)
X2 <- sin(v) + 2.5 * rnorm(128, 0, 1/20)
cell.counts(cbind(X1, X2), 3)

Signs of Colors of all Points for all Interactions

Description

get.signs returns all the signs of colors for each point under all interactions up to depth d in marginal binary expansions for the tests BET and BETs.

Usage

get.signs(X, dep, unif.margin = FALSE)

Arguments

Value

The result is a dataframe with n rows and 2^(p*dep) columns, where p is the number of columns of X and n is the number of rows of X. The values of 1 or -1 stand for the sign of color, while the marginal interactions return 0.

Examples

v <- runif(128, -pi, pi)
X1 <- cos(v) + 2.5 * rnorm(128, 0, 1/20)
X2 <- sin(v) + 2.5 * rnorm(128, 0, 1/20)
get.signs(cbind(X1, X2), 3)

Coordinates of Brightest Stars in the Night Sky

Description

This data set collects the galactic coordinates of the 256 brightest stars in the night sky (Perryman et al. 1997). We consider the longitude (x) and sine latitude (y) here.

Usage

data(star)

Format

An object of class data.frame with 256 rows and 2 columns.

Examples

data(star)
MaxBETs(cbind(star$x.raw, star$y.raw), asymptotic = FALSE, plot = TRUE, index = list(1,2))

Symmetry Statistics for all Interactions

Description

symm returns all the symmetry statistics up to depth d in marginal binary expansions for the tests BET and BETs.

Usage

symm(
  X,
  dep,
  unif.margin = FALSE,
  print.sample.size = TRUE
)

Arguments

Value

The result is a dataframe with (p+2) columns, where p is the number of columns of X. The first column gives the binary index for all variables, the next p columns displays all the interactions of respective variables, the last column of Statistics gives the respective symmetry statistic.

Examples

v <- runif(128, -pi, pi)
X1 <- cos(v) + 2.5 * rnorm(128, 0, 1/20)
X2 <- sin(v) + 2.5 * rnorm(128, 0, 1/20)
symm(cbind(X1, X2), 3)