% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cluster_centroids_impl.R
\name{cluster_centroids}
\alias{cluster_centroids}
\title{ClusterCentroids Algorithm}
\usage{
cluster_centroids(df, var, under_ratio = 1, voting = "soft")
}
\arguments{
\item{df}{data.frame or tibble. Must have 1 factor variable and remaining
numeric variables.}

\item{var}{Character, name of variable containing factor variable.}

\item{under_ratio}{A numeric value for the ratio of the
majority-to-minority frequencies. The default value (1) means
that all other levels are sampled down to have the same
frequency as the least occurring level. A value of 2 would mean
that the majority levels will have (at most) (approximately)
twice as many rows than the minority level.

A named numeric vector can be used instead to give different levels
different targets, for example \code{c(a = 2, b = 3)}. The names must be levels
of the outcome and the values are ratios of the minority level, exactly as
in the single-number case. Levels that are not named are left untouched, as
are rows with a missing outcome. Because a vector of targets is not a
single value, supplying one means this argument can no longer be tuned. See
\code{vignette("ratio", package = "themis")} for more details.}

\item{voting}{A character string. Either \code{"soft"} (the default) to use the
cluster centroids themselves, or \code{"hard"} to use the observation closest to
each centroid.}
}
\value{
A data.frame or tibble, depending on type of \code{df}.
}
\description{
Under-samples the majority classes by replacing them with cluster
representatives found with k-means.
}
\details{
Each class larger than the target count is summarized by running k-means on
the observations of that class, using as many clusters as the target count.
The class is then replaced by one representative per cluster:

\describe{
\item{\code{voting = "soft"}}{the cluster centroids themselves are used, so the
returned observations are synthetic points that need not appear in the
input.}
\item{\code{voting = "hard"}}{the observation closest to each centroid is used,
so all returned observations are real rows. The representative is always
picked from the class being under-sampled.}
}

This makes it the one \emph{prototype generation} under-sampler in this package.
The other under-sampling methods perform \emph{prototype selection}, keeping a
subset of the original rows.

Because two clusters can share the same closest observation, \code{voting = "hard"} can return slightly fewer observations than the target count.

All columns used in this function must be numeric with no missing data.
}
\examples{
circle_numeric <- circle_example[, c("x", "y", "class")]

res <- cluster_centroids(circle_numeric, var = "class")

res <- cluster_centroids(circle_numeric, var = "class", voting = "hard")

res <- cluster_centroids(circle_numeric, var = "class", under_ratio = 1.5)
}
\seealso{
\code{\link[=step_cluster_centroids]{step_cluster_centroids()}} for step function of this method

Other Direct Implementations:
\code{\link[=adasyn]{adasyn()}},
\code{\link[=bsmote]{bsmote()}},
\code{\link[=cnn]{cnn()}},
\code{\link[=enn]{enn()}},
\code{\link[=instance_hardness]{instance_hardness()}},
\code{\link[=kmeans_smote]{kmeans_smote()}},
\code{\link[=ncl]{ncl()}},
\code{\link[=nearmiss]{nearmiss()}},
\code{\link[=oss]{oss()}},
\code{\link[=rose]{rose()}},
\code{\link[=smogn]{smogn()}},
\code{\link[=smote]{smote()}},
\code{\link[=smoten]{smoten()}},
\code{\link[=smotenc]{smotenc()}},
\code{\link[=svmsmote]{svmsmote()}},
\code{\link[=tomek]{tomek()}}
}
\concept{Direct Implementations}
