% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/discretize_jointly.R
\name{discretize.jointly}
\alias{discretize.jointly}
\title{Discretize Multivariate Continuous Data by a Cluster-Preserving Grid}
\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{
\item{data}{a matrix containing two or more continuous variables.
Columns are variables, rows are observations.}

\item{k}{either an integer, a vector of integers, or \code{Inf}, specifying
different ways to find clusters in \code{data}. The default is a vector
containing integers from 2 to 10. If 'k' is a single number, \code{data} will
be grouped into into exactly 'k' clusters. If 'k' is an integer vector, an
optimal 'k' is chosen from among the integers, that maximizes the average
silhouette width. If 'k' is set to \code{Inf}, an optimal k is chosen among
2 to \code{nrow(data)}. If \code{cluster_label} is specified, \code{k} is
ignored.}

\item{min_level}{integer or vector, signifying the minimum number of levels
along each dimension. If a vector of size \code{ncol(data)}, then each element
will be mapped 1:1 to each dimension in order. If an integer, then all dimensions
will have the same minimum number of levels.}

\item{max_level}{integer or vector, signifying the maximum number of levels
along each dimension. Works in the same way as \code{min_level}. Max_level will
be set to the smaller one between the number of compressed zones and itself, if
the grid_method is set to "dp compressed likelihood" or "dp compressed majority"}

\item{cluster_method}{the clustering method to be used. Ignored if cluster
labels are given.

\code{"kmeans+silhouette"} will use k-means to cluster \code{data} and the average
Silhouette score to select the number of clusters k.

\code{"Ball+BIC"}: Uses a custom, multithreaded spherical clustering method.
It builds isotropic, variable-radius clusters and uses the BIC score to
automatically select the optimal k.

\code{"mclust_VII"}: Uses the \code{mclust} package (\code{modelNames = "VII"})
to perform spherical clustering, also using BIC for k selection.

\code{"PAM"} pam is partition around medoids

See Details for more information.}

\item{grid_method}{a character string to specify the discretization method.
Default: \code{"DP approx likelihood 1-way"}. The methods
can be roughly separate into three different categories:
by cluster likelihood, by density, and by SSE (Sum of Squared Errors).

See Details for more information.}

\item{eval_method}{a character string to
specify the method to evaluate quality
of discretized data}

\item{cluster_label}{a vector of user-specified cluster labels for each observation
in \code{data}. The user is free to choose any clustering.
If unspecified, k-means clustering is used by default.}

\item{cutoff}{a floating number. Tell the quality to decide whether cut that
line or not. If the statistic, a value to evaluate the quality of a cut,is
smaller then cut_off, no cut will be performed. Only will be used when the
\code{grid_method} is set to "DP" or "DP Compressed majority"}

\item{entropy}{Boolean variable decide whether using entropy or likelihood,
default value is false.}

\item{noise}{adding jitter noise to the original data, only will be used when
the \code{cluster_method} set to "Ball+BIC". When the data are very dense,
adding noise could improve the Mclust's result.}

\item{dim_reduction}{a logical to turn on/off
dimension reduction. Default: \code{FALSE}.}

\item{scale}{a logical to specify linear
scaling of the variable in each dimension.
Default: \code{FALSE}.}

\item{variance}{a numeric value to specify
noise variance to be added to the data}

\item{min_pts}{an integer to specify the minimum number of points inside
a cluster. Default: 5}

\item{nthread}{Integer. Number of CPU threads to use.
Automatically adjusted if invalid or
exceeds available cores. Default: 1}

\item{debug}{logical. If \code{TRUE}, it enables the debug mode.
Default: \code{FALSE}}
}
\value{
A list that contains four items:
\item{\code{D}}{a matrix that contains the discretized version of the original \code{data}.
Discretized values are one(1)-based.}

\item{\code{grid}}{a list of vectors containing decision boundaries for each variable/dimension.}

\item{\code{clabels}}{a vector containing cluster labels for each observation in \code{data}.}

\item{\code{csimilarity}}{a similarity score between clusters from joint discretization
\code{D} and cluster labels \code{clabels}. The score is the adjusted Rand index.}
}
\description{
Discretize multivariate continuous data using a grid that captures the joint distribution via
preserving clusters in the original data
}
\details{
The function implements both published algorithms described in
\insertCite{Jwang2020BCB}{GridOnClusters} and new algorithms for
multivariate discretization.

The grid methods provided is roughly in three different kinds.
\itemize{
\item By Density
\itemize{
\item \code{"Sort+split"} \insertCite{Jwang2020BCB}{GridOnClusters}
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.
}
\item By SSE (Sum of Squared Errors)
\itemize{
\item \code{"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.
\item \code{"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.
\item \code{"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.
}
\item By cluster likelihood
\itemize{
\item \code{"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.
\item \code{"DP approx likelihood 1-way"} is a speed up version of the
\code{"DP exact likelihood"} method, but no optimal will be guaranteed.
\item \code{"DP approx likelihood 2-way"} is a bidirectional variant of the
\code{"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:

\if{html}{\out{<div class="sourceCode">}}\preformatted{- \code{"Ball+BIC"}: Employs a custom, high-performance spherical clustering 
}\if{html}{\out{</div>}}

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.

\if{html}{\out{<div class="sourceCode">}}\preformatted{- \code{"mclust_VII"}: Utilizes the \code{mclust} package to fit a Gaussian 
}\if{html}{\out{</div>}}

Mixture Model with a spherical, unequal volume covariance structure
(\code{modelNames = "VII"}). It relies on the BIC score to automatically
determine the optimal number of components.
}
\note{
The default value of \code{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.
}
\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

#
}
\references{
\insertAllCited{}
}
\seealso{
See \link[Ckmeans.1d.dp]{Ckmeans.1d.dp} for discretizing univariate continuous data.
}
\author{
Jiandong Wang, Sajal Kumar and Mingzhou Song
}
