Package {GridOnClusters}

Type:	Package
Title:	Cluster-Preserving Multivariate Joint Grid Discretization
Version:	0.4.1
Date:	2026-07-18
Depends:	R (≥ 3.5.0)
Author:	Jiandong Wang [aut], Sajal Kumar [aut], Joe Song [aut, cre]
Maintainer:	Joe Song <joemsong@nmsu.edu>
Description:	Discretize multivariate continuous data using a grid to capture the joint distribution that preserves clusters in original data (Wang et al 2020) <doi:10.1145/3388440.3412415>. It can handle both labeled or unlabeled data. Joint grid discretization can prepare data for model-free inference of association, function, or causality.
Imports:	Rcpp, Ckmeans.1d.dp, cluster, fossil, dqrng, mclust, Rdpack, plotrix
Suggests:	FunChisq, knitr, testthat (≥ 2.1.0), rmarkdown
RdMacros:	Rdpack
License:	LGPL (≥ 3)
Encoding:	UTF-8
LinkingTo:	BH, Rcpp, RcppArmadillo
NeedsCompilation:	yes
VignetteBuilder:	knitr
Config/roxygen2/version:	8.0.0
Packaged:	2026-07-18 12:05:55 UTC; joesong
Repository:	CRAN
Date/Publication:	2026-07-18 12:40:02 UTC

Fast VII Gaussian Mixture Model

Description

Fast VII Gaussian Mixture Model

Usage

ballclust(
  data,
  G = NULL,
  threads = parallel::detectCores() - 1,
  min_pts = 5,
  verbose = FALSE
)

Arguments

Value

An object of class ballclust, mimicking mclust.

Cluster Multivariate Data

Description

The function obtains clusters from data using the given number of clusters, which may be a range.

Usage

cluster(data, k, method, noise, min_pts, nthread)

Arguments

Discretize Multivariate Continuous Data by a Cluster-Preserving Grid

Description

Discretize multivariate continuous data using a grid that captures the joint distribution via preserving clusters in the original data

Usage

discretize.jointly(
  data,
  k = c(2:10),
  min_level = 1,
  max_level = 100,
  cluster_method = c("Ball+BIC", "mclust_VII", "kmeans+silhouette", "PAM"),
  grid_method = c("DP approx likelihood 1-way", "DP approx likelihood 2-way",
    "DP exact likelihood", "DP Compressed majority", "DP", "Sort+split",
    "MultiChannel.WUC"),
  eval_method = c("ARI", "purity", "upsllion", "CAIR"),
  cluster_label = NULL,
  cutoff = 0,
  entropy = FALSE,
  noise = FALSE,
  dim_reduction = FALSE,
  scale = FALSE,
  variance = 0.5,
  min_pts = 5,
  nthread = 1,
  debug = FALSE
)

Arguments

Details

The function implements both published algorithms described in (Wang et al. 2020) and new algorithms for multivariate discretization.

The grid methods provided is roughly in three different kinds.

• By Density

  • "Sort+split" (Wang et al. 2020) will sort the cluster by cluster mean in each dimension and then split consecutive pairs only if the sum of the error rate of each cluster is less than or equal to 50%. It is possible that no grid line will be added in a certain dimension. The maximum number of lines is the number of clusters minus one.

• By SSE (Sum of Squared Errors)

  • "MultiChannel.WUC" will split each dimension by weighted with-in cluster sum of squared distances by "Ckmeans.1d.dp::MultiChannel.WUC". Applied in each projection on each dimension. The channel of each point is defined by its multivariate cluster label.

  • "DP" will order the label by the data in each dimension and then cut the data into max of max_level bins, then evaluating the quality of each cut to find the best number of bins.

  • "DP Compressed majority" will order the label by the data in each dimension and then compress the labels that neighbored by the same label to avoid trying discretization within consecutive points of the same cluster label to greatly reduce runtime of dynamic programming. Then cut the data into max of max_level bins, and evaluating the quality of each cut by the majority of the data has been spliced clearly to find the best number of bins.

• By cluster likelihood

  • "DP exact likelihood" will order the label by the data in each dimension and then compress the labels that neighbored by the same label to avoid trying discretization within consecutive points of the same cluster label to greatly reduce runtime of dynamic programming. Then cut the data into max of max_level bins.

  • "DP approx likelihood 1-way" is a speed up version of the "DP exact likelihood" method, but no optimal will be guaranteed.

  • "DP approx likelihood 2-way" is a bidirectional variant of the "DP approx likelihood" method. It performs approximate dynamic programming cuts in both the forward and backward directions and selects the better of the two results. This approach provides additional robustness compared to the one-directional version, but optimality is still not guaranteed.

The clsuter methods provided:

- \code{"Ball+BIC"}: Employs a custom, high-performance spherical clustering 

algorithm. It models clusters as isotropic spheres (equal shape, variable volume) and automatically selects the optimal number of clusters (k) by maximizing the Bayesian Information Criterion (BIC). This implementation supports multithreading for scalable execution on high-dimensional data.

- \code{"mclust_VII"}: Utilizes the \code{mclust} package to fit a Gaussian 

Mixture Model with a spherical, unequal volume covariance structure (modelNames = "VII"). It relies on the BIC score to automatically determine the optimal number of components.

Value

A list that contains four items:

Note

The default value of grid_method is changed from "Sort+Split" (up to released package version 0.1.0.2) to "DP approx likelihood 1-way" representing a much improved approach.

For the default configuration, it will also add some jitter noise to the data randomly only for clustering to avoid clustering failure by too many overlapping points in the data.

For more details, please check the documents.

Author(s)

Jiandong Wang, Sajal Kumar and Mingzhou Song

References

Wang J, Kumar S, Song M (2020). “Joint Grid Discretization for Biological Pattern Discovery.” In Proceedings of the 11th ACM International Conference on Bioinformatics, Computational Biology and Health Informatics. ISBN 9781450379649. doi:10.1145/3388440.3412415.

See Also

See Ckmeans.1d.dp for discretizing univariate continuous data.

Examples

# using a specified k
x = rnorm(100)
y = sin(x)
z = cos(x)
data = cbind(x, y, z)
discretized_data = discretize.jointly(data, k=5)$D

# using a range of k
x = rnorm(100)
y = log1p(abs(x))
z = x^2 # tan(x)
data = cbind(x, y, z)
discretized_data = discretize.jointly(data, k=c(3:10))$D

# using k = Inf
x = c()
y = c()
mns = seq(0,1200,100)
for(i in 1:12){
  x = c(x,runif(n=20, min=mns[i], max=mns[i]+20))
  y = c(y,runif(n=20, min=mns[i], max=mns[i]+20))
}
data = cbind(x, y)
discretized_data = discretize.jointly(data, k=Inf)$D

# using an alternate clustering method to k-means
library(cluster)
x = rnorm(100)
y = log1p(abs(x))
z = sin(x)
data = cbind(x, y, z)

# pre-cluster the data using partition around medoids (PAM)
cluster_label = pam(x=data, diss = FALSE, metric = "euclidean", k = 5)$clustering
discretized_data = discretize.jointly(data, cluster_label = cluster_label)$D

#

Generate Simulated Data

Description

Generate Simulated Data

Usage

gen_simdata(cord, sim_table, noise = 0.3, plot = FALSE)

Arguments

Hashed Upsilon Test of Association

Description

Hashed Upsilon Test of Association

Usage

hashed_upsilon(points, log.p = FALSE)

Arguments

See Also

upsilon.test for full description of the Upsilon test.

Plotting the continuous data along with cluster-preserving Grid

Description

Plots examples of jointly discretizing continuous data based on grids that preserve clusters in the original data.

Usage

## S3 method for class 'GridOnClusters'
plot(
  x,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  main.table = NULL,
  col,
  line_col = "black",
  cex = 1.125,
  sub = NULL,
  pch = 19,
  plot.table = TRUE,
  ...
)

Arguments

(OBOSOLETE) Plotting the continuous data along with cluster-preserving Grid

Description

Plots examples of jointly discretizing continuous data based on grids that preserve clusters in the original data.

Usage

plotGOCpatterns(data, res)

Arguments